Previous: Network Databases, Up: Networking

38.11.3 Network Sockets and Communication

Socket ports can be created using socket and socketpair. The ports are initially unbuffered, to make reading and writing to the same port more reliable. A buffer can be added to the port using setvbuf, See 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.

— Scheme Procedure: socket family style protocol
— C Function: scm_socket (family, style, protocol)

Return 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.

— Scheme Procedure: socketpair family style protocol
— C Function: scm_socketpair (family, style, protocol)

Return 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.

— Scheme Procedure: getsockopt socket level optname
— C Function: scm_getsockopt (socket, level, optname)

Return 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.

— Scheme Procedure: setsockopt sock level optname value
— C Function: scm_setsockopt (sock, level, optname, value)

Set 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.

— Scheme Procedure: shutdown sock how
— C Function: scm_shutdown (sock, how)

Sockets can be closed simply by using close-port. The shutdown procedure allows reception or tranmission on the socket port sock 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.

— Scheme Procedure: connect socket family address [arg ...]
— C Function: scm_connect (socket, family, address, arg)

Initiate a connection from socket to the address specified by family, 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.

— Scheme Procedure: bind socket family address [arg ...]
— C Function: scm_bind (socket, family, address, arg)

Assign 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.

— Scheme Procedure: listen socket backlog
— C Function: scm_listen (socket, backlog)

Enable 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.

— Scheme Procedure: accept socket
— C Function: scm_accept (socket)

Accept a connection on a bound, listening socket socket. If there are no pending connections in the queue, wait 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.
— Scheme Procedure: getsockname socket
— C Function: scm_getsockname (socket)

Return 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.

— Scheme Procedure: getpeername socket
— C Function: scm_getpeername (socket)

Return 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.

— Scheme Procedure: recv! socket buf [flags]
— C Function: scm_recv (socket, buf, flags)

Receive 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.

Return 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.

— Scheme Procedure: send socket message [flags]
— C Function: scm_send (socket, message, flags)

Transmit the string message on the socket port socket. socket must already be bound to a destination address. Return 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.

— Scheme Procedure: recvfrom! socket buf [flags [start [end]]]
— C Function: scm_recvfrom (socket, buf, flags, start, end)

Return 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.

Return 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.

— Scheme Procedure: sendto socket message family address [args/flags ...]
— C Function: scm_sendto (socket, message, family, address, args/flags)

Transmit 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. Return 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.

— Scheme Procedure: htons value
— C Function: scm_htons (value)

Return a new integer from value by converting from host to network order. value must be within the range of a C unsigned short integer.

— Scheme Procedure: ntohs value
— C Function: scm_ntohs (value)

Return a new integer from value by converting from network to host order. value must be within the range of a C unsigned short integer.

— Scheme Procedure: htonl value
— C Function: scm_htonl (value)

Return a new integer from value by converting from host to network order. value must be within the range of a C unsigned long integer.

— Scheme Procedure: ntohl value
— C Function: scm_ntohl (value)

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