Node:Network Sockets and Communication, Next:Internet Socket Examples, Previous:Network Databases, Up:Networking
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.
| socket family style proto | Scheme Procedure |
| scm_socket (family, style, proto) | C Function |
Return a new socket port of the type specified by family,
style and proto. All three parameters are
integers. Supported values for family are
AF_UNIX, AF_INET and AF_INET6.
Typical values for style are SOCK_STREAM,
SOCK_DGRAM and SOCK_RAW.
proto can be obtained from a protocol name using
A single socket port cannot by used for communication until it has been connected to another socket. |
| socketpair family style proto | Scheme Procedure |
| scm_socketpair (family, style, proto) | C Function |
Return a pair of connected (but unnamed) socket ports of the
type specified by family, style and proto.
Many systems support only socket pairs of the AF_UNIX
family. Zero is likely to be the only meaningful value for
proto.
|
| getsockopt sock level optname | Scheme Procedure |
| scm_getsockopt (sock, level, optname) | C Function |
Return the value of a particular socket option for the socket
port sock. 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 |
| setsockopt sock level optname value | Scheme Procedure |
| scm_setsockopt (sock, level, optname, value) | C Function |
Set the value of a particular socket option for the socket
port sock. 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. |
| shutdown sock how | Scheme Procedure |
| scm_shutdown (sock, how) | C Function |
Sockets can be closed simply by using close-port. The
shutdown procedure allows reception or transmission on a
connection to be shut down individually, according to the parameter
how:
The return value is unspecified. |
| connect sock fam address . args | Scheme Procedure |
| scm_connect (sock, fam, address, args) | C Function |
|
Initiate a connection from a socket using a specified address
family to the address
specified by address and possibly args.
The format required for address
and args depends on the family of the socket.
For a socket of family For a socket of family For a socket of family The return value is unspecified. |
| bind sock fam address . args | Scheme Procedure |
| scm_bind (sock, fam, address, args) | C Function |
|
Assign an address to the socket port sock.
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 args depends on the family of the socket. For a socket of family For a socket of family The values of the following variables can also be used for address:
For a socket of family The return value is unspecified. |
| listen sock backlog | Scheme Procedure |
| scm_listen (sock, backlog) | C Function |
Enable sock 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. |
| accept sock | Scheme Procedure |
| scm_accept (sock) | C Function |
|
Accept a connection on a bound, listening 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. sock 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
AF_UNIX or
AF_INET.
sockaddr:path
AF_UNIX, returns the path of the
filename the socket is based on.
sockaddr:addr
AF_INET, returns the Internet host
address.
sockaddr:port
AF_INET, returns the Internet port
number.
| getsockname sock | Scheme Procedure |
| scm_getsockname (sock) | C Function |
Return the address of sock, 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.
|
| getpeername sock | Scheme Procedure |
| scm_getpeername (sock) | C Function |
Return the address that sock
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.
|
| recv! sock buf [flags] | Scheme Procedure |
| scm_recv (sock, buf, flags) | C Function |
|
Receive data from a socket port.
sock 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. |
| send sock message [flags] | Scheme Procedure |
| scm_send (sock, message, flags) | C Function |
|
Transmit the string message on a socket port sock.
sock 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. |
| recvfrom! sock str [flags [start [end]]] | Scheme Procedure |
| scm_recvfrom (sock, str, flags, start, end) | C Function |
Return data from the socket port sock and also
information about where the data was received from.
sock must already be bound to the address from which
data is to be received. str, is a string into which the
data will be written. The size of str 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
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 The start and end arguments specify a substring of str 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. |
| sendto sock message fam address . args_and_flags | Scheme Procedure |
| scm_sendto (sock, message, fam, address, args_and_flags) | C Function |
Transmit the string message on the socket port
sock. The
destination address is specified using the fam,
address and
args_and_flags arguments, in a similar way to the
connect procedure. args_and_flags contains
the usual connection arguments optionally followed by
a flags argument, which is a value or
bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
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. 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.
| htons value | Scheme Procedure |
| scm_htons (value) | C Function |
| Convert a 16 bit quantity from host to network byte ordering. value is packed into 2 bytes, which are then converted and returned as a new integer. |
| ntohs value | Scheme Procedure |
| scm_ntohs (value) | C Function |
| Convert a 16 bit quantity from network to host byte ordering. value is packed into 2 bytes, which are then converted and returned as a new integer. |
| htonl value | Scheme Procedure |
| scm_htonl (value) | C Function |
| Convert a 32 bit quantity from host to network byte ordering. value is packed into 4 bytes, which are then converted and returned as a new integer. |
| ntohl value | Scheme Procedure |
| scm_ntohl (value) | C Function |
| Convert a 32 bit quantity from network to host byte ordering. value is packed into 4 bytes, which are then converted and returned as a new 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)))))