For Gauche 0.9.5


Next: , Previous: , Up: Library modules - SRFIs   [Contents][Index]

11.18 srfi-106 - Basic socket interface

Module: srfi-106

A portable basic socket interface.

Although comprehensive network API is provided by gauche.net (see 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.

Socket object

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

[SRFI-106] 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. A service name solely consists of decimal digits is interpreted as a port number.

The default value of optional arguments are as follows: *af-net* 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] Creates and resturns 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-net* 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] Equivalent to (is-a? obj <socket>).

Communication

Function: socket-accept socket
Function: socket-shutdown socket how
Function: socket-input-port socket
Function: socket-output-port socket
Function: socket-close socket

[SRFI-106] Same as the procedures provided in gauche.net. See Networking.

Function: socket-send socket u8vector :optional flags

[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] 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] Merge bitwise flags. This is simply logior in Gauche.

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

[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

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

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 …

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

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 …

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 …

Maps combination of names read and write to the combination of corresponding flags.

An error is signaled if other symbols are passed.


Next: , Previous: , Up: Library modules - SRFIs   [Contents][Index]