[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.11.3 Low-level socket interface

These functions provide APIs similar to the system calls. Those who are familiar to programming with socket APIs will find these functions useful since you can have more detailed control over the sockets.

Function: make-socket domain type &optional protocol
Returns a socket with specified parameters.

Variable: PF_UNIX
Variable: PF_INET
These variables are bound to PF_UNIX and PF_INET.

Variable: AF_UNIX
Variable: AF_INET
These variables are bound to AF_UNIX and AF_INET.

Variable: SOCK_DGRAM
Variable: SOCK_RAW
These variables are bound to SOCK_STREAM, SOCK_DGRAM and SOCK_RAW.

Function: socket-fd socket
Returns an integer system file descriptor of the underlying socket.

Function: socket-status socket
Returns a internal status of socket, by one of the following symbols.
none The socket is just created.
bound The socket is bound to an address by socket-bind
listening The socket is listening a connection by socket-listen
connected The socket is connected by socket-connect or socket-accept.
shutdown The socket is shutdown by socket-shutdown
closed The socket is closed by socket-close.

Function: socket-bind socket address
Binds socket to the local network address address. It is usually used to associate specific address to the server port. If binding failed, an error is signalled (most likely the address is already in use).

For the inet domain address, you can pass address with port=0; the system assigns the port number and sets the actual address to the address slot of socket.

Function: socket-listen socket backlog
Listens socket. The socket must be already bound to some address. backlog specifies maximum number of connection requests to be queued.

Function: socket-accept socket
Accepts a connection request coming to socket. Returns a new socket that is connected to the remote entity. The original socket keeps waiting for further connections. If there's no connection requests, this call waits for one to come.

You can use sys-select to check if there's a pending connection request.

Function: socket-connect socket address
Connects socket to the remote address address. This is the way for a client socket to connect to the remote entity.

Function: socket-shutdown socket how
Shuts down connection of socket. If how is 0, the receive channel of socket is disallowed. If how is 1, the send channel of socket is disallowed. If how is 2, both receive and send channels are disallowed. It is an error to call this function on a non-connected socket.

If you shut down the send channel of the socket, the remote peer sees EOF from its receive channel. This is useful if the remote peer expects EOF before sending something back to you.

Other than this kind of special cases, you don't usually need to call socket-shutdown explicitly; socket-close calls it anyway.

Further control over sockets and protocol layers is possible by getsockopt/setsockopt interface, as described below.

Function: socket-setsockopt socket level option value
Function: socket-getsockopt socket level option rsize
These are the interface to setsockopt() and getsockopt() calls. The interface is a bit clumsy, in order to allow full access to those low-level calls.

socket must be a non-closed socket object. level and option is an exact integer to specify the level of protocol stack and the option you want to deal with. There are several variables pre-bound to system constants listed below.

To set the socket option, you can pass either an exact integer or a string to value. If it is an integer, the value is passed to setsockopt(2) as C int value. If it is a string, the byte sequence is passed as is. The required type of value depends on the option, and Gauche can't know if the value you passed is expected by setsockopt(2); it is your responsibility to pass the correct values.

To get the socket option, you need to tell the maximum length of expected result by rsize parameter, for Gauche doesn't know the amount of data each option returns. socket-getsockopt returns the option value as a byte string. If you know the option value is an integer, you can pass 0 to rsize; in that case socket-getsockopt returns the value as an exact integer.

Note about the name: I tempted to name these function socket-{set|get}opt or socket-{set|get}-option, but I rather took the naming consistency. Hence duplicated "sock"s.

The following predefined variables are provided. Note that some of them are not available on all platforms. See manpages socket(7), tcp(7) or ip(7) of your system to find out exact specification of those values.

For "level" argument:

Variable: SOL_SOCKET
Variable: SOL_TCP
Variable: SOL_IP
These variables are bound to SOL_SOCKET, SOL_TCP and SOL_IP, respectively.

For "option" argument:

Expects integer value. If it is not zero, enables sending of keep-alive messages on connection-oriented sockets.

Expects integer value. If it is not zero, out-of-band data is directly placed into the receive data stream. Otherwise out-of-band data is only passed when the MSG_OOB flag is set during receiving.

Expects integer value. If it is not zero, socket-bind allows to reuse local addresses, unless an active listening socket bound to the address.

Variable: SO_TYPE
Gets the socket type as an integer (like sock_stream). Can be only used with socket-getsockopt.

Expects integer value. If it is not zero, datagram sockets are allowed to send/receive broadcast packets.

Expects integer value, specifying the protocol-defined priority for all packets to be sent on this socket.

Variable: SO_ERROR
Gets and clears the pending socket error as an integer. Can be only used with socket-getsockopt.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated by Ken Dickey on November, 28 2002 using texi2html