11.22 srfi.106 - Basic socket interface

Module: srfi.106 ¶

A portable basic socket interface.

Although comprehensive network API is provided by gauche.net (see gauche.net - Networking), it is Gauche-specific. This srfi provides a small subset of socket operations, but it offers a portable way to create applications that needs simple networking.

Note that some procedures have the same name as the ones in gauche.net, but the interface may differ.

A socket object created by this srfi’s API is an instance of Gauche’s <socket>, so it can be passed to the API in gauche.net and vice versa.

The following procedures are exactly the same as defined in gauche.net. See gauche.net - Networking, for the details.

socket-accept        socket-shutdown       socket-close
socket-input-port    socket-output-port

Socket object

Function: make-client-socket node service :optional ai-family ai-socktype ai-flags ai-protocol ¶

[SRFI-106]{srfi.106} Creates and returns a socket to communicate with the node node and service. If the socket type is connection-oriented (that is, ai-socktype is *sock-stream*, which is the default), the returned socket is already connected.

Both node and service must be strings. The node argument is passed to getaddrinfo(3) to resolve to the server IP address(es). A service name solely consists of decimal digits is interpreted as a port number.

The default value of optional arguments are as follows: *af-inet* for ai-family, *sock-stream* for ai-socktype, (socket-merge-flags *ai-v4mapped* *ai-addrconfig*) for ai-flags, and *ipproto-ip* for ai-protocol. See below for valid flag values.

This API differs from make-client-socket in gauche.net.

(make-client-socket "127.0.0.1" "80")
 ⇒ a <socket> connected to port 80 of localhost

Function: make-server-socket service :optional ai-family ai-socktype ai-protocol ¶

[SRFI-106]{srfi.106} Creates and returns a server socket that binds and listens at the port specified by service, which must be a string. A service name solely consists of decimal digits is interpreted as a port number.

The default value of optional arguments are as follows: *af-inet* for ai-family, *sock-stream* for ai-socktype, and *ipproto-ip* for ai-protocol. See below for valid flag values.

This API differs from make-server-socket in gauche.net.

Function: socket? obj ¶

[SRFI-106]{srfi.106} Equivalent to (is-a? obj <socket>).

Communication

Function: socket-send socket u8vector :optional flags ¶

[SRFI-106]{srfi.106} Almost same as socket-send in gauche.net, except that this procedure only accepts a u8vector as the message. (The one in gauche.net can take a string as well.)

Returns the number of octets that are actually sent.

Function: socket-recv socket size :optional flags ¶

[SRFI-106]{srfi.106} This is like socket-recv in gauche.net, except that this procedure returns the received data in u8vector, instead of a string. If the peer has shut down the connection, this procedure returns an empty u8vector, #u8().

The size argument specifies the maximum size of the receiving data. The returned vector may be shorter if that much data is received.

Flags

The srfi provides common names for constants of typical socket flags, as well as macros that map symbolic name(s) to the flags.

Function: socket-merge-flags flag … ¶

[SRFI-106]{srfi.106} Merge bitwise flags. This is simply logior in Gauche.

Function: socket-purge-flags base-flag flag … ¶

[SRFI-106]{srfi.106} Drop the bitwise flags in base-flag that are set in flag ….

Address family

*af-inet*	AF_INET
*af-inet6*	AF_INET6
*af-unspec*	AF_UNSPEC

Macro: address-family name ¶

[SRFI-106]{srfi.106} Name can be either one of symbols inet, inet6, or unspec, and the macro expands into the value of *af-inet*, *af-inet6* or *af-unspec*, respectively.

If name is other object, an error is signaled.

Socket domain

*sock-stream*	SOCK_STREAM
*sock-dgram*	SOCK_DGRAM

Macro: socket-domain name ¶

[SRFI-106]{srfi.106} Name can be either one of symbols stream or datagram, and the macro expands into the value of *sock-stream* and *sock-dgram*, respectively.

If name is other object, an error is signaled.

Address info

*ai-canonname*	AI_CANONNAME
*ai-numerichost*	AI_NUMERICHOST
*ai-v4mapped*	AI_V4MAPPED
*ai-all*	AI_ALL
*ai-addrconfig*	AI_ADDRCONFIG

Macro: address-info name … ¶

[SRFI-106]{srfi.106} Maps combination of names canoname, numerichost, v4mapped, all and addrconfig to the combination of corresponding flags.

An error is signaled if other symbols are passed. (Note: canoname for *ai-canonname*).

Protocol

*ipproto-ip*	IPPROTO_IP
*ipproto-tcp*	IPPROTO_TCP
*ipproto-udp*	IPPROTO_UDP

Macro: ip-protocol name ¶

[SRFI-106]{srfi.106} Maps one of names ip, tcp, and udp to the corresponding flag value. An error is signaled if other symbol is passed.

Message type

*msg-none*	0
*msg-peek*	MSG_PEEK
*msg-oob*	MSG_OOB
*msg-waitall*	MSG_WAITALL

Macro: message-type name … ¶

[SRFI-106]{srfi.106} Maps combination of names none, peek, oob and wait-all to the combination of corresponding flags.

An error is signaled if other symbols are passed. (Note: wait-all for *msg-waitall*).

Shutdown method

*shut-rd*	SHUT_RD
*shut-wr*	SHUT_WR
*shut-rdwr*	SHUT_RDWR

Macro: shutdown-method name … ¶

[SRFI-106]{srfi.106} Maps combination of names read and write to the combination of corresponding flags.

An error is signaled if other symbols are passed.