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