| The class socket implements the support of the system sockets that one can use for networking or interprocess communication. In case of error occuring during the execution of a socket class method, the thread local variable *lastsocketerror* will be set to the corresponding system error message, and must be reset to nil after use. Timeouts for socket-accept , socket-connect , and all the read and write methods can be set by calling the socket-setsockopt method of a socket object. For example, do (setsockopt mysock nil 'SO_SNDTIMEO 10000) to set a timeout of 10000 milliseconds on the socket mysock for writing. Set a timeout of 0 to deactivate it. The timeout can also be a float value. The keywords, values and results of the methods socket-setsockopt and socket-getsockopt are similar to those described in the socket(7) man page. For performance reason, a C structure containing buffers and flags is also bound to the property lfile of each instance of the class. Socket functions not implemented in the present class can be called directly with the FFI (see library class) using the socket descriptor which can be queried by the file-fileno function. see also the function select and the class file . |
| Function Type | subr |
| Arguments | a socket object |
| Return Value | a socket object or nil |
| Description | once a socket of type stream, seqpacket or rdm has been put in listening mode with socket-listen , socket-accept extracts the first connection request on the queue of pending connections, creates a new connected socket with mostly the same properties as the argument, and allocates a new socket object which is returned; the newly created socket is no longer in the listening state; |
| Example | (accept mysock) |
| Function Type | subr |
| Arguments | a socket object, optional non-nil or nil |
| Return Value | t or nil |
| Description | returns t if a character has been unread on the socket object given as first argument and nil otherwise; if a second argument is provided it sets the socket charInBuffer flag state for the next call; non-nil sets the socket charInBuffer flag to t and nil sets it to nil; the last read character is always stored internally anyway and must not be provided |
| Example | (char-in-buffer mysock t) |
| Function Type | subr |
| Arguments | a socket object |
| Return Value | nil |
| Description | invalidates the socket object input buffer so that the next socket-read-char, socket-read-line or socket-fread operation must require a real read on the socket descriptor |
| Example | (clear-input mysock) |
| Function Type | subr |
| Arguments | a socket object, a string, an optional integer or string or symbol |
| Return Value | t or nil |
| Description | connects the socket object to the remote target given as first argument, using optionnaly the port given as second argument; if the socket is of type unix, the first argument is a file name, on which the user must have read and write access; for such a socket, the second argument is not used; if the socket is of type inet, the first argument is either an ip-address or a server name, the second argument must be either an integer which is the port number, or a string or a symbolic atom which is the service name; in case of success, the method returns t and sets a series of supplementary properties of the object like the resolved remote address and port; if the second argument is not given or nil, it is assumed to be port 0 |
| Example | (setq google(make-instance socket 'inet 'stream 0 'port 9999)) (connect google "www.google.com" 'http) |
| Function Type | subr |
| Arguments | the symbol socket, a mandatory symbol, a mandatory symbol, a mandatory integer or string, a series of optional pairs of symbols and values |
| Return Value | a socket object |
| Description | never call socket-constructor directly but always through make-instance ;
the first argument gives the family of the socket: unix, local, inet, inet6, ipx, netlink, x25, ax25, atmpvc, appletalk, packet, of which only unix and inet are implemented as of today; the second argument gives the type of the socket: stream, dgram, seqpacket, raw, rdm, packet, and the third the protocol name or integer number; the following arguments are optional keywords, each followed by a value; the keyword 'maxstring followed by an integer gives the size of the input buffer; the default value is the same length as defined by the -t switch for the interpreter thread, or 4096; the keyword 'filename followed by a string gives the name of the file to create as unix socket; the keyword 'address followed by a string gives the local address or host name; the keyword 'port followed by an integer gives the local port to be used; all the keywords (including family and type values) must evaluate to the expected symbols or be quoted to prevent evaluation; socket-constructor calls the system functions socket() and bind(); |
| Example | (make-instance socket 'inet 'stream 0 'port 9999) |
| Function Type | subr |
| Arguments | a socket object |
| Return Value | t |
| Description | never call socket-destructor directly but always through destroy-instance ; the destructor closes the socket |
| Example | (destroy-instance mysock) |
| Function Type | subr |
| Arguments | a socket object |
| Return Value | t or nil |
| Description | returns t if the socket has encountered an irrecuperable network error or has been closed; returns nil is the socket is still operable |
| Example | (eof mysock) |
| Function Type | subr |
| Arguments | a socket object, a binary, an optional integer |
| Return Value | an integer or nil |
| Description | reads the socket given as first argument into the buffer given as second argument, up to the length of the buffer or the length given as third argument if it is smaller; if still unread data remain in the input buffer of the socket object, these data are returned first and no actual read occurs on the system socket descriptor; the next socket-read-char , socket-read-line or socket-fread will get the rest of the input buffer if still any and the system socket will be read only after input buffer exhaustion; use first socket-clear-input to invalidate the input buffer and force an actual read on the socket; the function returns the actual length read, which might be smaller than the buffer or the requested length if either it is what remained in the input buffer or it is only what the system socket could give at that moment |
| Example | (fread mysock buffer1) |
| Function Type | subr |
| Arguments | a socket object, a binary, an optional integer |
| Return Value | an integer or nil |
| Description | write the buffer given as second argument on the socket given as first argument, up to the length of the buffer or the length given as third argument if shorter; returns the length actually written |
| Example | (fwrite mysock buffer1) |
| Function Type | subr |
| Arguments | a socket object, an integer or a string or nil, a symbol |
| Return Value | an integer or a list or t or nil |
| Description | gets an option of the socket passed as first argument; the protocol or level number or name is given by the second argument which can be nil for the default SOL_SOCKET level; the third argument is the quoted socket option keyword; to see the options and the type of argument to receive depending on the option, refer to the UNIX man pages; to see those, do: man 7 socket; the struct arguments are received as lists of integers |
| Example | (getsockopt mysock nil 'SO_RVCTIMEO) => nil |
| Function Type | subr |
| Arguments | a socket object, an integer |
| Return Value | t or nil |
| Description | sets the socket in listening mode and with a waiting queue of which the length is given by the second argument; if the number of incoming connections waiting to be satisfied by a call to socket-accept reaches that maximum length, then further attemps to connecting will receive an error ECONNREFUSED on the client side |
| Example | (listen mysock 5) |
| Function Type | subr |
| Arguments | a socket object |
| Return Value | an integer or nil |
| Description | reads a UTF-8 character on the input buffer of the socket object given as argument; if the input buffer is empty, a read() is initiated on the socket eventually waiting data from the network; the UTF-8 sequences are interpreted by a finite state automaton until complete and returned as one Unicode integer; returns EOF if the input buffer is empty and the socket is closed; socket-read-char returns nil in case of socket error or if a receive timeout was set and has been reached; a timeout reached while reconstituting a UTF-8 causes the loss of the sequence and a nil result |
| Example | (read-char mysock) |
| Function Type | subr |
| Arguments | a socket object |
| Return Value | a string |
| Description | reads a string from the input buffer of the socket object given as argument and returns it; if the input buffer is empty, a read() is initiated on the socket eventually waiting data from the network; if the input buffer is empty and the socket is closed, socket-read-string returns nil and sets EOF to true; the function returns nil in case of socket error or if a receive timeout was set and has been reached; the string read goes from the current position in the input buffer to just after the last character in the buffer; newline characters or CR-LF sequences can be embedded in the string and are not deleted |
| Example | (read-string mysoc) |
| Function Type | subr |
| Arguments | a socket object, a binary, a series of optional pairs of symbols and values |
| Return Value | an integer of nil |
| Description | reads the socket given as first argument into the buffer given as second argument, up to the length of the buffer or the length given as keyword argument length if it is smaller; if still unread data remained in the input buffer of the socket object, those data are invalidated and forgotten; the next socket-read-char , socket-read-line or socket-fread will read from the network; socket-recv returns the actual length read, which might be smaller than the buffer or the requested length if it is only what the system socket could give at that moment; the keyword length followed by an integer gives the size to read into the binary buffer; the keyword flags followed by an integer gives the flags to apply, see man (2) recv(); socket-recv returns nil in case of socket error or if a receive timeout was set and has been reached; returns EOF if the socket is closed |
| Example | (recv mysock buffer1) |
| Function Type | subr |
| Arguments | a socket object, a binary, a series of optional pairs of symbols and values |
| Return Value | an integer of nil |
| Description | reads the socket given as first argument into the buffer given as second argument, up to the length of the buffer or the length given as keyword argument length if it is smaller; if still unread data remained in the input buffer of the socket object, those data are invalidated and forgotten; the next socket-read-char , socket-read-line or socket-fread will read from the network; socket-recv-from returns the actual length read, which might be smaller than the buffer or the requested length if it is only what the system socket could give at that moment; the keyword length followed by an integer gives the size to read into the binary buffer; the keyword flags followed by an integer gives the flags to apply, see man (2) recv-from(); socket-recv-from returns nil in case of socket error or if a receive timeout was set and has been reached; returns EOF if the socket is closed; the sending address and port are stored as the properties remoteaddress and remoteport of the socket object |
| Example | (recv-from mysock buffer1) |
| Function Type | subr |
| Arguments | a socket object, a binary, a series of optional pairs of symbols and values |
| Return Value | an integer of nil |
| Description | sends on the socket given as first argument the buffer given as second argument, up to the length of the buffer or the length given as keyword argument length if it is smaller; the input buffer is not invalidated; socket-send returns the actual length sent, which might be smaller than the buffer or the requested length if it is only what the system socket could accept at that moment; the keyword length followed by an integer gives the size to use into the binary buffer; the keyword flags followed by an integer gives the flags to apply, see man (2) send(); socket-send returns nil in case of socket error or if a send timeout was set and has been reached; returns EOF if the socket is closed |
| Example | (send mysock buffer1) |
| Function Type | subr |
| Arguments | a socket object, a binary, a string, an integer, a series of optional pairs of symbols and values |
| Return Value | an integer of nil |
| Description | sends on the socket given as first argument the buffer given as second argument, up to the length of the buffer or the length given as keyword argument length if it is smaller; the input buffer is not invalidated; the third and fourth argument must be the IP address, or name, and the port of the destination; socket-send-to returns the actual length sent, which might be smaller than the buffer or the requested length if it is only what the system socket could accept at that moment; the keyword length followed by an integer gives the size to use of the binary buffer; the keyword flags followed by an integer gives the flags to apply, see man (2) send(); socket-send-to returns nil in case of socket error or if a send timeout was set and has been reached; returns EOF if the socket is closed |
| Example | (send-to mysock buffer1 "192.168.2.1" 80) |
| Function Type | subr |
| Arguments | a socket object, an integer or a string or nil, a symbol, an optional float or integer or string or nil |
| Return Value | t or nil |
| Description | sets an option on the socket passed as first argument; the protocol or level number or name is given by the second argument which can be nil for the default SOL_SOCKET level; the third argument is the quoted socket option keyword; the fourth argument is an integer value, a string, or t, or nil, depending on the socket option keyword; to see the options and the type of argument to supply depending on the option, refer to the UNIX man pages; to see those, do: man 7 socket |
| Example | (setsockopt mysock nil 'SO_RCVTIMEO 10000) |
| Function Type | subr |
| Arguments | a socket (or subclass) object, a binary block, an integer |
| Return Value | t or nil |
| Description | prints a formatted view of the C structure containing buffers and flags which is bound as a binary block to the property lsocket of the object; this method is not intended to be used directly but it is called by the class-show method; a showbin method must return t to signal a succesful print |
| Example | none |
| Function Type | subr |
| Arguments | a socket object |
| Return Value | nil |
| Description | sets the flag char-in-buffer of the socket object to t so that the last character read by socket-read-char again returned by the next call to socket-read-char or socket-read-line or socket-fread |
| Example | (unread-char mysock) |
| Function Type | subr |
| Arguments | a socket object, an integer |
| Return Value | an integer or nil |
| Description | writes a UTF-8 character on the socket object; if successful returns the second argument |
| Example | (write-char mysock 8364) |
| Function Type | subr |
| Arguments | a socket object, a string |
| Return Value | a string |
| Description | writes the string given as second argument on the socket object given as first argument; if successful returns the second argument; the string is appended with a UNIX newline, ie 0xa |
| Example | (write-line mysock "HEAD / HTTP/1.1" ) |
| Function Type | subr |
| Arguments | a socket object, a string |
| Return Value | a string |
| Description | writes the string given as second argument on the socket object given as first argument; if successful returns the second argument; no UNIX newline, ie 0xa is appended |
| Example | (write-string mysock "HEAD / HTTP/1.1" ) |