README.md - clic - Clic is an command line interactive client for gopher writte… | |
git clone git://bitreich.org/clic/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65… | |
Log | |
Files | |
Refs | |
Tags | |
README | |
LICENSE | |
--- | |
README.md (5678B) | |
--- | |
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 possibl… | |
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 [email protected] 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?) |