socket Class Reference


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 .


  • socket-accept
  • socket-char-in-buffer
  • socket-clear-input
  • socket-connect
  • socket-constructor
  • socket-destructor
  • socket-eof
  • socket-fread
  • socket-fwrite
  • socket-getsockopt
  • socket-listen
  • socket-read-char
  • socket-read-string
  • socket-recv
  • socket-recv-from
  • socket-send
  • socket-send-to
  • socket-setsockopt
  • socket-showbin
  • socket-unread-char
  • socket-write-char
  • socket-write-line
  • socket-write-string

  • List of all Inherited Classes

  • file
  • class

  • socket-accept

    (accept arg )

    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)

    socket-char-in-buffer

    (char-in-buffer arg1 arg2 )

    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)

    socket-clear-input

    (clear-input arg )

    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)

    socket-connect

    (connect arg1 arg2 arg3 )

    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)

    socket-constructor

    (make-instance socket arg1 arg2 arg3 ... argn )

    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)

    socket-destructor

    (destroy-instance arg )

    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)

    socket-eof

    (eof arg )

    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)

    socket-fread

    (fread arg1 arg2 arg3 )

    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)

    socket-fwrite

    (fwrite arg1 arg2 arg3 )

    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)

    socket-getsockopt

    (getsockopt arg1 arg2 arg3 )

    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

    socket-listen

    (listen arg1 arg2 )

    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)

    socket-read-char

    (read-char arg )

    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)

    socket-read-string

    (read-string arg )

    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)

    socket-recv

    (recv arg1 arg2 arg3 ... argn )

    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)

    socket-recv-from

    (recv-from arg1 arg2 arg3 ... argn )

    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)

    socket-send

    (send arg1 arg2 arg3 ... argn )

    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)

    socket-send-to

    (send-to arg1 arg2 arg3 ... argn )

    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)

    socket-setsockopt

    (setsockopt arg1 arg2 arg3 arg4 )

    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)

    socket-showbin

    (showbin arg1 arg2 arg3 )

    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

    socket-unread-char

    (unread-char arg )

    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)

    socket-write-char

    (write-char arg1 arg2 )

    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)

    socket-write-line

    (write-line arg1 arg2 )

    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" )

    socket-write-string

    (write-string arg1 arg2 )

    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" )

    Updated 29/11/2008 Copyright © 2008 Walther Waeles
    SourceForge.net Logo