3rdparties/software/usocket-0.8.3/README.md (5678 bytes)
1 ## USOCKET - Universal socket library for Common Lisp 2 3 https://common-lisp.net/project/usocket/ 4 5 This is the usocket Common Lisp sockets library: a library to bring 6 sockets access to the broadest of common lisp implementations as possible. 7 8 ## The library currently supports: 9 10 1. Allegro CL 11 2. ABCL (ArmedBear) 12 3. Clasp 13 4. Clozure CL 14 5. Corman Lisp 15 6. GNU CLISP 16 7. CMUCL 17 8. ECL 18 9. LispWorks (4.3 and up) 19 10. Digitool MCL and RMCL (5.0 and up) 20 11. Mezzano 21 12. MOCL 22 13. SBCL 23 14. Scieneer CL 24 15. Symbolics Lisp Machine (Genera) 25 26 If your favorite common lisp misses in the list above, please contact 27 usocket-devel@common-lisp.net and submit a request. Please include 28 references to available sockets functions in your lisp implementation. 29 30 The library has been ASDF (http://cliki.net/ASDF) enabled, meaning 31 that you can tar up a checkout and use that to ASDF-INSTALL:INSTALL 32 the package in your system package site. (Or use your usual ASDF 33 tricks to use the checkout directly.) 34 35 ## Remarks on licensing 36 37 Even though the source code has an MIT style license attached to it, 38 when compiling this code with some of the supported lisp implementations 39 you may not end up with an MIT style binary version due to the licensing 40 of the implementations themselves. ECL is such an example and - when 41 it will become supported - GCL is like that too. 42 43 ## Non-support of :external-format 44 45 Because of its definition in the hyperspec, there's no common 46 external-format between lisp implementations: every vendor has chosen 47 a different way to solve the problem of newline translation or 48 character set recoding. 49 50 Because there's no way to avoid platform specific code in the application 51 when using external-format, the purpose of a portability layer gets 52 defeated. So, for now, usocket doesn't support external-format. 53 54 The workaround to get reasonably portable external-format support is to 55 layer a flexi-stream (from flexi-streams) on top of a usocket stream. 56 57 ## API definition 58 59 - usocket (class) 60 - stream-usocket (class; usocket derivative) 61 - stream-server-usocket (class; usocket derivative) 62 - socket-connect (function) [ to create an active/connected socket ] 63 socket-connect host port &key element-type 64 where `host' is a vectorized ip 65 or a string representation of a dotted ip address 66 or a hostname for lookup in the DNS system 67 - socket-listen (function) [ to create a passive/listening socket ] 68 socket-listen host port &key reuseaddress backlog element-type 69 where `host' has the same definition as above 70 - socket-accept (method) [ to create an active/connected socket ] 71 socket-accept socket &key element-type 72 returns (server side) a connected socket derived from a 73 listening/passive socket. 74 - socket-close (method) 75 socket-close socket 76 where socket a previously returned socket 77 - socket (usocket slot accessor), 78 the internal/implementation defined socket representation 79 - socket-stream (usocket slot accessor), 80 socket-stream socket 81 the return value of which satisfies the normal stream interface 82 - socket-shutdown 83 84 ### Errors: 85 - address-in-use-error 86 - address-not-available-error 87 - bad-file-descriptor-error 88 - connection-refused-error 89 - connection-aborted-error 90 - connection-reset-error 91 - invalid-argument-error 92 - no-buffers-error 93 - operation-not-supported-error 94 - operation-not-permitted-error 95 - protocol-not-supported-error 96 - socket-type-not-supported-error 97 - network-unreachable-error 98 - network-down-error 99 - network-reset-error 100 - host-down-error 101 - host-unreachable-error 102 - shutdown-error 103 - timeout-error 104 - unkown-error 105 106 ### Non-fatal conditions: 107 - interrupted-condition 108 - unkown-condition 109 110 (for a description of the API methods and functions see 111 https://common-lisp.net/project/usocket/api-docs.shtml) 112 113 ## Test suite 114 115 The test suite unfortunately isn't mature enough yet to run without 116 some manual configuration. Several elements are required which are 117 hard to programatically detect. Please adjust the test file before 118 running the tests, for these variables: 119 120 - +non-existing-host+: The stringified IP address of a host on the 121 same subnet. No physical host may be present. 122 - +unused-local-port+: A port number of a port not in use on the 123 machine the tests run on. 124 - +common-lisp-net+: A vector with 4 integer elements which make up 125 an IP address. This must be the IP "common-lisp.net" resolves to. 126 127 ## Known problems 128 129 - CMUCL error reporting wrt sockets raises only simple-errors 130 meaning there's no way to tell different error conditions apart. 131 All errors are mapped to unknown-error on CMUCL. 132 133 - The ArmedBear backend doesn't do any error mapping (yet). Java 134 defines exceptions at the wrong level (IMO), since the exception 135 reported bares a relation to the function failing, not the actual 136 error that occurred: for example 'Address already in use' (when 137 creating a passive socket) is reported as a BindException with 138 an error text of 'Address already in use'. There's no way to sanely 139 map 'BindException' to a meaningfull error in usocket. [This does not 140 mean the backend should not at least map to 'unknown-error'!] 141 142 - When using the library with ECL, you need the C compiler installed 143 to be able to compile and load the Foreign Function Interface. 144 Not all ECL targets support DFFI yet, so on some targets this would 145 be the case anyway. By depending on this technique, usocket can 146 reuse the FFI code on all platforms (including Windows). This benefit 147 currently outweighs the additional requirement. (hey, it's *Embeddable* 148 Common Lisp, so, you probably wanted to embed it all along, right?)