GNU Info

(guile.info)Network Sockets and Communication

---

Prev: Network Databases and Address Conversion Up: Networking

---

Enter node , (file) or (file)node

Network Sockets and Communication
---------------------------------

Socket ports can be created using `socket' and `socketpair'.  The ports
are initially unbuffered, to makes reading and writing to the same port
more reliable.  A buffer can be added to the port using `setvbuf',
Note: Ports and File Descriptors.

The convention used for "host" vs "network" addresses is that addresses
are always held in host order at the Scheme level.  The procedures in
this section automatically convert between host and network order when
required.  The arguments and return values are thus in host order.

 - primitive: socket family style proto
     Returns a new socket port of the type specified by FAMILY, STYLE
     and PROTOCOL.  All three parameters are integers.  Typical values
     for FAMILY are the values of `AF_UNIX' and `AF_INET'.  Typical
     values for STYLE are the values of `SOCK_STREAM', `SOCK_DGRAM' and
     `SOCK_RAW'.

     PROTOCOL can be obtained from a protocol name using
     `getprotobyname'.  A value of zero specifies the default protocol,
     which is usually right.

     A single socket port cannot by used for communication until it has
     been connected to another socket.

 - primitive: socketpair family style proto
     Returns a pair of connected (but unnamed) socket ports of the type
     specified by FAMILY, STYLE and PROTOCOL.  Many systems support only
     socket pairs of the `AF_UNIX' family.  Zero is likely to be the
     only meaningful value for PROTOCOL.

 - primitive: getsockopt sock level optname
     Returns the value of a particular socket option for the socket
     port SOCKET.  LEVEL is an integer code for type of option being
     requested, e.g., `SOL_SOCKET' for socket-level options.  OPTNAME
     is an integer code for the option required and should be specified
     using one of the symbols `SO_DEBUG', `SO_REUSEADDR' etc.

     The returned value is typically an integer but `SO_LINGER' returns
     a pair of integers.

 - primitive: setsockopt sock level optname value
     Sets the value of a particular socket option for the socket port
     SOCKET.  LEVEL is an integer code for type of option being set,
     e.g., `SOL_SOCKET' for socket-level options.  OPTNAME is an
     integer code for the option to set and should be specified using
     one of the symbols `SO_DEBUG', `SO_REUSEADDR' etc.  VALUE is the
     value to which the option should be set.  For most options this
     must be an integer, but for `SO_LINGER' it must be a pair.

     The return value is unspecified.

 - primitive: shutdown sock how
     Sockets can be closed simply by using `close-port'. The `shutdown'
     procedure allows reception or tranmission on a connection to be
     shut down individually, according to the parameter HOW:

    0
          Stop receiving data for this socket.  If further data
          arrives,  reject it.

    1
          Stop trying to transmit data from this socket.  Discard any
          data waiting to be sent.  Stop looking for acknowledgement of
          data already sent; don't retransmit it if it is lost.

    2
          Stop both reception and transmission.

     The return value is unspecified.

 - primitive: connect sock fam address . args
     Initiates a connection from SOCKET to the address specified by
     ADDRESS and possibly ARG ....  The format required for ADDRESS and
     ARG ... depends on the family of the socket.

     For a socket of family `AF_UNIX', only `address' is specified and
     must be a string with the filename where the socket is to be
     created.

     For a socket of family `AF_INET', `address' must be an integer
     Internet host address and ARG ...  must be a single integer port
     number.

     The return value is unspecified.

 - primitive: bind sock fam address . args
     Assigns an address to the socket port SOCKET.  Generally this only
     needs to be done for server sockets, so they know where to look
     for incoming connections.  A socket without an address will be
     assigned one automatically when it starts communicating.

     The format of ADDRESS and ARG ... depends on the family of the
     socket.

     For a socket of family `AF_UNIX', only ADDRESS is specified and
     must be a string with the filename where the socket is to be
     created.

     For a socket of family `AF_INET', ADDRESS must be an integer
     Internet host address and ARG ... must be a single integer port
     number.

     The values of the following variables can also be used for ADDRESS:

      - Variable: INADDR_ANY
          Allow connections from any address.

      - Variable: INADDR_LOOPBACK
          The address of the local host using the loopback device.

      - Variable: INADDR_BROADCAST
          The broadcast address on the local network.

      - Variable: INADDR_NONE
          No address.

     The return value is unspecified.

 - primitive: listen sock backlog
     This procedure enables SOCKET to accept connection requests.
     BACKLOG is an integer specifying the maximum length of the queue
     for pending connections.  If the queue fills, new clients will
     fail to connect until the server calls `accept' to accept a
     connection from the queue.

     The return value is unspecified.

 - primitive: accept sock
     Accepts a connection on a bound, listening socket SOCKET.  If there
     are no pending connections in the queue, it waits until one is
     available unless the non-blocking option has been set on the
     socket.

     The return value is a pair in which the CAR is a new socket port
     for the connection and the CDR is an object with address
     information about the client which initiated the connection.

     If the address is not available then the CDR will be an empty
     vector.

     SOCKET does not become part of the connection and will continue to
     accept new requests.

The following functions take a socket address object, as returned by
`accept' and other procedures, and return a selected component.

`sockaddr:fam'
     The socket family, typically equal to the value of `AF_UNIX' or
     `AF_INET'.

`sockaddr:path'
     If the socket family is `AF_UNIX', returns the path of the
     filename the socket is based on.

`sockaddr:addr'
     If the socket family is `AF_INET', returns the Internet host
     address.

`sockaddr:port'
     If the socket family is `AF_INET', returns the Internet port
     number.

 - primitive: getsockname sock
     Returns the address of SOCKET, in the same form as the object
     returned by `accept'.  On many systems the address of a socket in
     the `AF_FILE' namespace cannot be read.

 - primitive: getpeername sock
     Returns the address of the socket that the socket SOCKET is
     connected to, in the same form as the object returned by `accept'.
     On many systems the address of a socket in the `AF_FILE'
     namespace cannot be read.

 - primitive: recv! sock buf [flags]
     Receives data from the socket port SOCKET.  SOCKET must already be
     bound to the address from which data is to be received.  BUF is a
     string into which the data will be written.  The size of BUF
     limits the amount of data which can be received: in the case of
     packet protocols, if a packet larger than this limit is
     encountered then some data will be irrevocably lost.

     The optional FLAGS argument is a value or bitwise OR of MSG_OOB,
     MSG_PEEK, MSG_DONTROUTE etc.

     The value returned is the number of bytes read from the socket.

     Note that the data is read directly from the socket file
     descriptor: any unread buffered port data is ignored.

 - primitive: send sock message [flags]
     Transmits the string MESSAGE on the socket port SOCKET.  SOCKET
     must already be bound to a destination address.  The value
     returned is the number of bytes transmitted - it's possible for
     this to be less than the length of MESSAGE if the socket is set to
     be non-blocking.  The optional FLAGS argument is a value or
     bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.

     Note that the data is written directly to the socket file
     descriptor: any unflushed buffered port data is ignored.

 - primitive: recvfrom! sock buf [flags [start [end]]]
     Returns data from the socket port SOCKET and also information about
     where the data was received from.  SOCKET must already be bound to
     the address from which data is to be received.  `buf', is a string
     into which the data will be written.  The size of BUF limits the
     amount of data which can be received: in the case of packet
     protocols, if a packet larger than this limit is encountered then
     some data will be irrevocably lost.

     The optional FLAGS argument is a value or bitwise OR of MSG_OOB,
     MSG_PEEK, MSG_DONTROUTE etc.

     The value returned is a pair: the CAR is the number of bytes read
     from the socket and the CDR an address object in the same form as
     returned by `accept'.

     The START and END arguments specify a substring of BUF to which
     the data should be written.

     Note that the data is read directly from the socket file
     descriptor: any unread buffered port data is ignored.

 - primitive: sendto sock message fam address . args_and_flags
     Transmits the string MESSAGE on the socket port SOCKET.  The
     destination address is specified using the FAMILY, ADDRESS and ARG
     arguments, in a similar way to the `connect' procedure.  The value
     returned is the number of bytes transmitted - it's possible for
     this to be less than the length of MESSAGE if the socket is set to
     be non-blocking.  The optional FLAGS argument is a value or
     bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.

     Note that the data is written directly to the socket file
     descriptor: any unflushed buffered port data is ignored.

The following functions can be used to convert short and long integers
between "host" and "network" order.  Although the procedures above do
this automatically for addresses, the conversion will still need to be
done when sending or receiving encoded integer data from the network.

 - primitive: htons in
     Returns a new integer from VALUE by converting from host to
     network order. VALUE must be within the range of a C unsigned
     short integer.

 - primitive: ntohs in
     Returns a new integer from VALUE by converting from network to
     host order.  VALUE must be within the range of a C unsigned short
     integer.

 - primitive: htonl in
     Returns a new integer from VALUE by converting from host to
     network order. VALUE must be within the range of a C unsigned long
     integer.

 - primitive: ntohl in
     Returns a new integer from VALUE by converting from network to
     host order. VALUE must be within the range of a C unsigned long
     integer.

These procedures are inconvenient to use at present, but consider:

     (define write-network-long
       (lambda (value port)
         (let ((v (make-uniform-vector 1 1 0)))
           (uniform-vector-set! v 0 (htonl value))
           (uniform-vector-write v port))))
     
     (define read-network-long
       (lambda (port)
         (let ((v (make-uniform-vector 1 1 0)))
           (uniform-vector-read! v port)
           (ntohl (uniform-vector-ref v 0)))))