GopherProxy

	tREADME.md - clic - Clic is an command line interactive client for gopher writt…
	git clone git://bitreich.org/clic/ git://hg6vgqziawt5s4dj.onion/clic/
	Log
	Files
	Refs
	Tags
	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 possibl…
	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 [email protected] 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?)