README.md - clic - Clic is an command line interactive client for gopher written in Common LISP
(HTM) git clone git://bitreich.org/clic/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/clic/
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) Tags
(DIR) README
(DIR) 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 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?)