SRFI 106 - Basic socket interface

The (srfi 106) library provides a basic socket interface.

See the SRFI document for more information.

Constructors and predicate

make-client-socket make-server-socket socket?

Socket operations

socket-accept socket-send socket-recv socket-shutdown socket-close

Port conversion

socket-input-port socket-output-port

Control feature

call-with-socket

Flag operations

address-family address-info socket-domain ip-protocol message-type shutdown-method socket-merge-flags socket-purge-flags

Constant values

*af-unspec* *af-inet* *af-inet6* *sock-stream* *sock-dgram* *ai-canonname* *ai-numerichost* *ai-v4mapped* *ai-all* *ai-addrconfig* *ipproto-ip* *ipproto-tcp* *ipproto-udp* *msg-peek* *msg-oob* *msg-waitall* *shut-rd* *shut-wr* *shut-rdwr*

make-client-socket

(make-client-socket node service [ai-family [ai-socktype [ai-flags [ai-protocol]]]]) -> socket

Returns a client socket connected to an Internet address. The Internet address is identified by node and service. node and service must be string. Example value of node: "localhost" "127.0.0.1" Example value of service: "http" "80" The optional parameter may specify the created socket’s behaviour. If the optional argument(s) is omitted, then following flags should be used as default:

ai-family
  *af-inet*
ai-socktype
  *sock-stream*
ai-flags
  (socket-merge-flags *ai-v4mapped* *ai-addrconfig*)
ai-protocol
  *ipproto-ip*

The created socket may not be closed automatically so it is users’ responsibility to close it explicitly.

make-server-socket

(make-server-socket service [ai-family [ai-socktype [ai-protocol]]]) -> socket

Returns a server socket waiting for connection. The description of node argument is the same as make-client-socket. The optional parameter may specify the created socket’s behaviour.

If the optional argument(s) is omitted, then following flags should be used as default.

ai-family
  *af-inet*
ai-socktype
  *sock-stream*
ai-protocol
  *ipproto-ip*

The created socket may not be closed automatically so it is users’ responsibility to close it explicitly.

socket?

(socket? object) -> boolean

Returns #t if given object is socket object. Otherwise #f.

socket-accept

(socket-accept socket) -> socket

Wait for an incoming connection request, and returns a fresh connected client socket.

socket-send

(socket-send socket bv [flags]) -> size

Sends a binary data block to a socket and returns the sent data size. flags may specify the procedure’s behaviour.

If the flags is omitted, the default value must be the result of following form:

(message-type none)

socket-recv

(socket-recv socket size [flags]) -> bv

Receives a binary data block from a socket. If zero length bytevector is returned, it means the peer connection is closed. flags may specify the procedure’s behaviour.

If the flags is omitted, the default value must be the result of following form:

(message-type none)

socket-shutdown

(socket-shutdown socket how) -> (unspecified)

Shutdowns a socket. how must be one of the following constants:

*shut-rd*
*shut-wr*
*shut-rdwr*

socket-close

(socket-close socket) -> (unspecified)

Closes a socket. The procedure does not shutdown the given socket. To shutdown a socket, socket-shutdown should be called explicitly.

socket-input-port

(socket-input-port socket) -> binary-input-port

Returns a fresh binary input port associated with a socket, respectively. The port should not close underlying socket when it’s closing.

socket-output-port

(socket-output-port socket) -> binary-output-port

Returns a fresh binary output port associated with a socket, respectively. The port should not close underlying socket when it’s closing.

call-with-socket

(call-with-socket socket proc) -> object

Calls a given procedure with a given socket as an argument.

If given proc returns then it returns the result of proc and socket will be automatically closed. If proc doesn’t return then given socket won’t be closed automatically. It’s analogy of call-with-port.

address-family

Syntax

(address-family name) -> address-family

Returns proper address family from given name.

inet

Returns *af-inet*

inet6

Returns *af-inet6*

unspec

Returns *af-unspec*

address-info

Syntax

(address-info names ...) -> address-info

Returns merged address info flags from given names.

canoname

Returns *ai-canonname*

numerichost

Returns *ai-numerichost*

v4mapped

Returns *ai-v4mapped*

all

Returns *ai-all*

addrconfig

Returns *ai-addrconfig*

socket-domain

Syntax

(socket-domain name) -> socket-domain

Returns socket domain flags from given name.

stream

Returns *sock-stream*

datagram

Returns *sock-dgram*

ip-protocol

Syntax

(ip-protocol name) -> ip-protocol

Returns ip-protocol flag from given name.

Returns *ipproto-ip*

tcp

Returns *ipproto-tcp*

udp

Returns *ipproto-udp*

message-type

Syntax

(message-type names ...) -> message-type

Returns message type flag from given name.

The flag can be used both socket-recv and socket-send.

none

Returns no flag.

peek

Returns *msg-peek*

oob

Returns *msg-oob*

wait-all

Returns *msg-waitall*

shutdown-method

Syntax

(shutdown-method names ...) -> shutdown-method

Returns shutdown method flags from given names.

read

Returns *shut-rd*

write

Returns *shut-wr*

If shutdown-method is given both read and write, then it must return *shut-rdwr*

socket-merge-flags

(socket-merge-flags flags ...) -> new-flags

Merges given flags and returns a new flag.

socket-purge-flags

(socket-purge-flags base-flag flags ...) -> new-flags

Removes flags from base-flag if exists and returns a new flag.

af-unspec

This must behave the same as POSIX’s AF_UNSPEC.

af-inet

Internet domain sockets for use with IPv4 addresses. This must behave the same as POSIX’s AF_INET.

af-inet6

Internet domain sockets for use with IPv6 addresses. This must behave the same as POSIX’s AF_INET6.

sock-stream

Byte-stream socket. This must behave the same as POSIX’s SOCK_STREAM.

sock-dgram

Datagram socket. This must behave the same as POSIX’s SOCK_DGRAM.

ai-canonname

This must behave the same as POSIX’s AI_CANONNAME.

ai-numerichost

This must behave the same as POSIX’s AI_NUMERICHOST.

ai-v4mapped

This must behave the same as POSIX’s AI_V4MAPPED.

ai-all

This must behave the same as POSIX’s AI_ALL.

ai-addrconfig

This must behave the same as POSIX’s AI_ADDRCONFIG.

ipproto-ip

Internet protocol. This must behave the same as POSIX’s IPPROTO_IP.

ipproto-tcp

Transmission control protocol. This must behave the same as POSIX’s IPPROTO_TCP.

ipproto-udp

User datagram protocol. This must behave the same as POSIX’s IPPROTO_UDP.

msg-peek

For socket-recv. Peeks at an incoming message. The data is treated as unread and the next socket-recv shall still return this data. This must behave the same as POSIX's MSG_PEEK.

msg-oob

For both socket-recv and socket-send. Requests/sends out-of-band data. This must behave the same as POSIX’s MSG_OOB.

msg-waitall

For socket-recv. On sockets created with *sock-stream* flag, this requests the procedure block until the full amount of data ban be returned. This must behave the same as POSIX’s MSG_WAITALL.

shut-rd

Disables further receive operation. This must behave the same as POSIX’s SHUT_RD.

shut-wr

Disables further send operations. This must behave the same as POSIX’s SHUT_WR.

shut-rdwr

Disables further send and receive operations. This must behave the same as POSIX’s SHUT_RDWR.