This section describes low level socket API on Sagittarius. The following example is simple echo server, it receives input from a client and just returns it to the client.
The example program is from example/socket/echo.scm.
(import (rnrs) (sagittarius socket))
;; creates echo server socket with port number 5000
(define echo-server-socket (make-server-socket "5000"))
;; addr is client socket
(let loop ((addr (socket-accept echo-server-socket)))
(call-with-socket addr
(lambda (sock)
;; socket-port creates binary input/output port
;; make it transcoded port for convenience.
(let ((p (transcoded-port (socket-port sock)
;; on Sagittarius Scheme native-transcoder
;; uses utf8 codec for ASCII compatibility.
;; For socket programming it might be better
;; to specify eol-style with crlf.
;; But this sample just shows how it goes.
(native-transcoder))))
(call-with-port p
(lambda (p)
(put-string p "please type something\n\r")
(put-string p "> ")
;; gets line from client.
(let lp2 ((r (get-line p)))
(unless (eof-object? r)
(print "received: " r)
;; just returns message from client.
;; NB: If client type nothing, it'll throw assertion-violation.
(put-string p r)
(put-string p "\r\n> ")
;; waits for next input.
(lp2 (get-line p)))))))))
;; echo server waits next connection.
(loop (socket-accept echo-server-socket)))
This library provides procedures for socket programming.
Node and service must be string or #f. Other optional arguments must be exact integer.
Returns a client socket connected to an Internet address. The Internet
address is identified by node and service. The
make-client-socket uses getaddrinfo(3) to look it up. The
arguments node, service, ai-family, ai-socktype, ai-flags
and ai-protocol are passed to getaddrinfo(3) as corresponding
parameters. For more detail, see reference of getaddrinfo(3).
Node is a network address, ex) "www.w3.org", "localhost", "192.168.1.1".
Service is a network service, ex) "http", "ssh", "80", "22".
Ai-family is an address family specifier. Predefined specifiers are listed below.
AF_INET
AF_INET6
AF_UNSPEC
Ai-sockettype is a socket type specifier. Predefined specifiers are listed below.
SOCK_STREAM
SOCK_DGRAM
SOCK_RAW
Ai-flags is an additional options specifier. Predefined specifiers are listed below.
AI_ADDRCONFIG
AI_ALL
AI_CANONNAME
AI_NUMERICHOST
AI_NUMERICSERV
AI_PASSIVE
AI_V4MAPPED
Ai-protocol is a protocol specifier. Predefined specifiers are listed below.
IPPROTO_TCP
IPPROTO_UDP
IPPROTO_RAW
Service must be string or #f. Other optional arguments must be exact
integer. Returns a server socket waiting for connections. The argument details
are the same as the make-client-socket.
Returns #t if obj is socket object, otherwise #f.
Socket must be a socket object. Returns a binary input/output port associated with socket.
If optional argument close? is #f then the port won't close socket when port is closing or being GCed.
[SRFI-106] Socket must be a socket object. Returns a binary input and output port associated with socket, respectively.
Socket must be a socket object. Proc must accept one argument.
The call-with-socket calls a procedure with socket as an argument.
This procedure is analogy with call-with-port.
Port must be associated with a socket.
Shutdowns associated port according to how.
Port must be associated with a socket.
The shutdown-output-port and shutdown-input-port shutdown
output or input connection of a socket associated with port respectively.
Socket must be a socket object created by
make-server-socket.
Wait for an incoming connection request and returns a fresh connected client socket.
This procedures is a thin wrapper of POSIX's accept(2).
If the calling thread is interrupted by thread-interrupt!, then
the procedure returns #f.
Socket must be a socket object.
Receives a binary data block from given socket. If zero length bytevector is returned, it means the peer connection is closed.
This procedures is a thin wrapper of POSIX's recv(2).
Socket must be a socket object.
Sends a binary data block to given socket and returns the sent data size.
This procedures is a thin wrapper of POSIX's send(2).
Socket must be a socket object. How must be one of the
SHUT_RD, SHUT_WR or SHUT_RDWR.
The socket-shutdown shutdowns socket.
shutdowns input.
shutdowns output.
shutdowns input and output.
Socket must be a socket object. Closes socket.
The socket information immutable class. This class has 3 slots
This slot has string value represents own or peer socket host.
This slot has ip-address object of own or peer socket.
This slot has integer value of own or peer socket port number.
Socket must be a socket object.
Returns socket info object or #f. The socket info object contains hostname, IP address and port number. These information is retrieved from getpeername(2).
Socket must be a socket object.
Returns the name string of socket or #f if the socket doesn't have name.
Socket must be a socket object.
Returns the node string of socket. Returns #f for server socket.
Socket must be a socket object.
Returns the service string of socket.
Socket must be a socket object.
Returns socket info object or #f. The socket info object contains hostname, IP address and port number. These information is retrieved from getsockname(2).
Socket must be a socket object.
Returns 3 values; hostname, IP address and port number. This procedures is for convenience to handle socket info object.
The keyword argument specifies which socket info it should retrieve. If the
type is peer then it uses socket-peer. If it is info,
then it uses socket-info
ip must be an IP address object returned from the second value
of socket-info-values.
Converts given IP address object to human readable string.
ip must be an IP address object returned from the second value
of socket-info-values.
Converts given IP address object to bytevector.
The low level socket APIs are almost compatible with BSD socket.
Sends a binary data block to given sockaddr and returns the sent data size.
This procedures is a thin wrapper of POSIX's sendto (2).
Receives a binary data block from given sockaddr. If zero length bytevector is returned, it means the peer connection is closed.
This procedures is a thin wrapper of POSIX's recvfrom (2).
Creates socket object. The procedure returns #f if it couldn't create
a socket. SO_NOSIGPIPE socket option is set to the created socket.
This procedure is a thin wrapper of socket (2).
Initiate connection on the given socket with given addrinfo addrinfo.
If the second form is used, then argument timeout represents a
connection timeout. The value must be a timeout value of socket-select.
This procedure is a thin wrapper of connect (2).
Binds a name to the given socket socket with given addrinfo addrinfo.
This procedure is a thin wrapper of bind (2).
Listen for connections on the given socket socket.
This procedure is a thin wrapper of listen (2).
Sets socket option on the given socket socket.
level must be an integer and should be one of the followings:
SOL_SOCKET
SOL_TCP
SOL_IP
name must be an integer and should be one of the followings:
SO_ACCEPTCONN
SO_BINDTODEVICE
SO_BROADCAST
SO_DEBUG
SO_DONTROUTE
SO_ERROR
SO_KEEPALIVE
SO_LINGER
SO_OOBINLINE
SO_PASSCRED
SO_PEERCRED
SO_PRIORITY
SO_RCVBUF
SO_RCVLOWAT
SO_RCVTIMEO
SO_REUSEADDR
SO_REUSEPORT
SO_SNDBUF
SO_SNDLOWAT
SO_SNDTIMEO
SO_TIMESTAMP
SO_TYPE
TCP_NODELAY
TCP_MAXSEG
TCP_CORK
IP_OPTIONS
IP_PKTINFO
IP_RECVTOS
IP_RECVTTL
IP_RECVOPTS
IP_TOS
IP_TTL
IP_HDRINCL
IP_RECVERR
IP_MTU_DISCOVER
IP_MTU
IP_ROUTER_ALERT
IP_MULTICAST_TTL
IP_MULTICAST_LOOP
IP_ADD_MEMBERSHIP
IP_DROP_MEMBERSHIP
IP_MULTICAST_IF
The value must be either bytevector or integer.
This procedure is a thin wrapper of setsockopt (2).
Gets socket option on the given socket socket.
The level and name are the same as socket-setsockopt!.
size must be an integer. If the value is positive number, then the returning value is a bytevector whose element count is size and contains the socket option converted to byte array. Otherwise it returns an integer value.
Converts given socket to nonblocking socket and blocking socket, respectively.
Sets read timeout of timeout to the given socket.
The timeout must be either an exact integer represents milliseconds, or a time object.
Monitor given fdset.
rfds, wfds and efds must be fdset object.
timeout must be #f, integer, time object or pair of integers. If this value is not #f, then the procedure waits only specified amount of time or something interesting happens. Otherwise infinite time or something interesting happens.
This procedure blocks the calling thread, and it can be interrupted by
thread-interrupt!.
This procedure is a thin wrapper of select (2).
Waits until the given sockets sockets have something interesting.
This is the convenient procedure for socket-select.
timeout is the same as socket-select.
socket-read-select can be used to detect if the given sockets have
readable data.
socket-write-select can be used to detect if the given sockets are
still active.
socket-error-select can be used to detect if the given sockets are
readable data. This procedure might not be so interesting since it can be
done by socket-read-select.
Returns #t if given obj is an addrinfo, otherwise #f.
Creates empty addrinfo object.
The object has the following slots:
family
socktype
flags
protocol
sockaddr
next
Creates an addrinfo with given flags. This can be used as hint for
get-addrinfo.
Gets addrinfo of given hint addrinfo.
When the procedure fails, then &i/o is raised.
This procedure is a thin wrapper of getaddrinfo (3).
Retrieves next addrinfo of given addrinfo if availalbe, otherwise returns #f.
Retrieves sockaddr slot of given addrinfo.
The returning value can be used socket-recvfrom and socket-sendto.
Returns #t if given obj is an sockaddr object, otherwise #f.
Returns #t if given obj is a fdset object, otherwise #f.
Creates a empty fdset object.
Creates a fdset from given socket list sockets.
Returns #t if the given socket is set to fdset, otherwise #f.
Sets/unsets the given socket socket on fdset.
If the flags is #f, then the procedure unsets the socket.
If the flags is #t, then the procedure sets the socket.
Returns a list of socket which are set on fdset.
Above APIs may raise either &socket or &host-not-found. The first
condition is raised when socket related operation failed, for example
socket-send. The latter condition is raised when get-addrinfo is
failed.
NOTE: make-client-socket and make-server-socket may raise
&host-not-found when the given node or service is not a
valid value.
The condition hierarchy is the following:
&i/o
+ &host-not-found (node service)
+ &socket (socket)
+ &socket-connection
+ &socket-closed
+ &socket-read-timeout
+ &socket-port (port)
This condition describes the combination of node and _service_does not exist.
This condition describes general socket operation error.
This condition describes socket connection error.
This condition describes socket closed error.
This condition describes socket read timeout error.
This condition describes error of socket port operation. Particularly,
when port-ready procedure is called on socket port and
select (2) failed.
NOTE: Read or write failure of socket port raises &i/o-read or
&i/o-write the same as other ports for compatibility.
NOTE2: This condition may be signalled when get-bytevector-all is
called on socket port since it checks whether or not the given port is ready.