@c Generated by the sb-manual contrib. Do not edit.

@node networking
@chapter Networking

@menu
* Sockets Overview: sockets overview.
* General Sockets: general sockets.
* Socket Options: socket options.
* INET Domain Sockets: inet domain sockets.
* Local Domain Sockets: local domain sockets.
* Name Service: name service.
@end menu

The @code{sb-bsd-sockets} module provides a thinly disguised BSD
socket API for SBCL. Ideas have been stolen from the BSD socket API
for C and Graham Barr's @code{IO::Socket} classes for Perl.

Sockets are represented as CLOS objects, and the API naming
conventions attempt to balance between the BSD names and good lisp
style.

@node sockets overview
@section Sockets Overview

Most of the functions are modelled on the BSD socket API. BSD sockets
are widely supported, portably (by Unix standards, at least)
available on a variety of systems, and documented. There are some
differences in approach where we have taken advantage of some of the
more useful features of Common Lisp -- briefly:

@itemize
@item Where the C API would typically return -1 and set @code{errno},
  @code{sb-bsd-sockets} signals an error. All the errors are subclasses
  of @code{sb-bsd-sockets:socket-error} and generally correspond one for
  one with possible @code{errno} values.

@item We use multiple return values in many places where the C API would
  use pass-by-reference values.

@item We can often avoid supplying an explicit length argument to
  functions because we already know how long the argument is.

@item IP addresses and ports are represented in slightly friendlier
  fashion than "network-endian integers".
@end itemize

@node general sockets
@section General Sockets

@anchor{Class sb-bsd-sockets socket}
@ttindex @sortas{socket sb-bsd-sockets} socket [sb-bsd-sockets]
@deffn{Class} sb-bsd-sockets:socket
Common superclass of all sockets, not meant to be
directly instantiated.
@end deffn
@anchor{Function sb-bsd-sockets socket-bind}
@ffindex @sortas{socket-bind sb-bsd-sockets} socket-bind [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:socket-bind socket &rest address
Bind @code{socket} to @code{address}, which may vary according to socket family.
For the INET family, pass @code{address} and @code{port} as two arguments; for local
address family sockets, pass the filename string. See also @code{bind(2)}.
@end deffn
@anchor{Function sb-bsd-sockets socket-accept}
@ffindex @sortas{socket-accept sb-bsd-sockets} socket-accept [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:socket-accept socket
Perform the @code{accept(2)} call, returning a newly-created connected
socket and the peer address as multiple values
@end deffn
@anchor{Function sb-bsd-sockets socket-connect}
@ffindex @sortas{socket-connect sb-bsd-sockets} socket-connect [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:socket-connect socket &rest address
Perform the @code{connect(2)} call to connect @code{socket} to a remote @code{peer}.
No useful return value.
@end deffn
@anchor{Function sb-bsd-sockets socket-peername}
@ffindex @sortas{socket-peername sb-bsd-sockets} socket-peername [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:socket-peername socket
Return @code{socket}'s peer; depending on the address family this may
return multiple values
@end deffn
@anchor{Function sb-bsd-sockets socket-name}
@ffindex @sortas{socket-name sb-bsd-sockets} socket-name [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:socket-name socket
Return the address (as vector of bytes) and port that @code{socket} is
bound to, as multiple values.
@end deffn
@anchor{Function sb-bsd-sockets socket-receive}
@ffindex @sortas{socket-receive sb-bsd-sockets} socket-receive [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:socket-receive socket buffer length &key oob peek waitall dontwait element-type
Read @code{length} octets from @code{socket} into @code{buffer} (or a freshly-consed
buffer if @code{nil}), using @code{recvfrom(2)}. If @code{length} is @code{nil}, the length of
@code{buffer} is used, so at least one of these two arguments must be
non-@code{nil}. If @code{buffer} is supplied, it had better be of an element type
one octet wide. Returns the buffer, its length, and the address of the
peer that sent it, as multiple values. On datagram sockets, sets
@code{MSG_TRUNC} so that the actual packet length is returned even if
the buffer was too small.
@end deffn
@anchor{Function sb-bsd-sockets socket-send}
@ffindex @sortas{socket-send sb-bsd-sockets} socket-send [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:socket-send socket buffer length &key address external-format oob eor dontroute dontwait nosignal confirm more
Send @code{length} octets from @code{buffer} into @code{socket}, using @code{sendto(2)}. If
@code{buffer} is a string, it will converted to octets according to
@code{external-format}. If @code{length} is @code{nil}, the length of the octet buffer is
used. The format of @code{address} depends on the socket type (for example
for INET domain sockets it would be a list of an IP address and a
port). If no socket address is provided, @code{send(2)} will be called
instead. Returns the number of octets written.
@end deffn
@anchor{Function sb-bsd-sockets socket-listen}
@ffindex @sortas{socket-listen sb-bsd-sockets} socket-listen [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:socket-listen socket backlog
Mark @code{socket} as willing to accept incoming connections.  The
integer @code{backlog} defines the maximum length that the queue of pending
connections may grow to before new connection attempts are refused.
See also @code{listen(2)}.
@end deffn
@anchor{Function sb-bsd-sockets socket-open-p}
@ffindex @sortas{socket-open-p sb-bsd-sockets} socket-open-p [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:socket-open-p socket
Return true if @code{socket} is open; otherwise, return false.
@end deffn
@anchor{Function sb-bsd-sockets socket-close}
@ffindex @sortas{socket-close sb-bsd-sockets} socket-close [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:socket-close socket &key abort
Close @code{socket}, unless it was already closed.

If @code{socket-make-stream} has been called, calls @code{close} using @code{abort} on that
stream. Otherwise closes the socket file descriptor using @code{close(2)}.
@end deffn
@anchor{Function sb-bsd-sockets socket-shutdown}
@ffindex @sortas{socket-shutdown sb-bsd-sockets} socket-shutdown [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:socket-shutdown socket &key direction
Indicate that no communication in @code{direction} will be performed on
@code{socket}.

@code{direction} has to be one of @code{:input}, @code{:output} or @code{:io}.

After a shutdown, no input and/or output of the indicated @code{direction}
can be performed on @code{socket}.
@end deffn
@anchor{Function sb-bsd-sockets socket-make-stream}
@ffindex @sortas{socket-make-stream sb-bsd-sockets} socket-make-stream [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:socket-make-stream socket &key input output element-type external-format buffering timeout auto-close serve-events
Find or create a @code{stream} that can be used for IO on @code{socket} (which
must be connected).  Specify whether the stream is for @code{input}, @code{output},
or both (it is an error to specify neither).

@code{element-type} and @code{external-format} are as per @code{open}.

@code{timeout} specifies a read timeout for the stream.
@end deffn
@anchor{Function sb-bsd-sockets socket-error}
@ffindex @sortas{socket-error sb-bsd-sockets} socket-error [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:socket-error where &optional errno
Signal an appropriate error for syscall @code{where} and @code{errno}.

@code{where} should be a string naming the failed function.

When supplied, @code{errno} should be the UNIX error number associated to the
failed call. The default behavior is to use the current value of the
errno variable.
@end deffn
@anchor{Function sb-bsd-sockets non-blocking-mode}
@ffindex @sortas{non-blocking-mode sb-bsd-sockets} non-blocking-mode [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:non-blocking-mode socket
Is @code{socket} in non-blocking mode?
@end deffn
@node socket options
@section Socket Options

A subset of socket options are supported, using a fairly general
framework which should make it simple to add more as required -- see
@code{SYS:CONTRIB;SB-BSD-SOCKETS:SOCKOPT.LISP} for details. The name
mapping from C is fairly straightforward: @code{SO_RCVLOWAT} becomes
@code{sb-bsd-sockets:sockopt-receive-low-water} and @code{(setf
sb-bsd-sockets:sockopt-receive-low-water)}.

@anchor{Function sb-bsd-sockets sockopt-reuse-address}
@ffindex @sortas{sockopt-reuse-address sb-bsd-sockets} sockopt-reuse-address [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:sockopt-reuse-address socket
Return the value of the SO-REUSEADDR socket option for @code{socket}. This can also be
updated with @code{setf}.
@end deffn
@anchor{Function sb-bsd-sockets sockopt-keep-alive}
@ffindex @sortas{sockopt-keep-alive sb-bsd-sockets} sockopt-keep-alive [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:sockopt-keep-alive socket
Return the value of the SO-KEEPALIVE socket option for @code{socket}. This can also be
updated with @code{setf}.
@end deffn
@anchor{Function sb-bsd-sockets sockopt-oob-inline}
@ffindex @sortas{sockopt-oob-inline sb-bsd-sockets} sockopt-oob-inline [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:sockopt-oob-inline socket
Return the value of the SO-OOBINLINE socket option for @code{socket}. This can also be
updated with @code{setf}.
@end deffn
@anchor{Function sb-bsd-sockets sockopt-bsd-compatible}
@ffindex @sortas{sockopt-bsd-compatible sb-bsd-sockets} sockopt-bsd-compatible [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:sockopt-bsd-compatible socket
Return the value of the SO-BSDCOMPAT socket option for @code{socket}. This can also be
updated with @code{setf}. Available only on Linux.
@end deffn
@anchor{Function sb-bsd-sockets sockopt-pass-credentials}
@ffindex @sortas{sockopt-pass-credentials sb-bsd-sockets} sockopt-pass-credentials [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:sockopt-pass-credentials socket
Return the value of the SO-PASSCRED socket option for @code{socket}. This can also be
updated with @code{setf}. Available only on Linux.
@end deffn
@anchor{Function sb-bsd-sockets sockopt-debug}
@ffindex @sortas{sockopt-debug sb-bsd-sockets} sockopt-debug [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:sockopt-debug socket
Return the value of the SO-DEBUG socket option for @code{socket}. This can also be
updated with @code{setf}.
@end deffn
@anchor{Function sb-bsd-sockets sockopt-dont-route}
@ffindex @sortas{sockopt-dont-route sb-bsd-sockets} sockopt-dont-route [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:sockopt-dont-route socket
Return the value of the SO-DONTROUTE socket option for @code{socket}. This can also be
updated with @code{setf}.
@end deffn
@anchor{Function sb-bsd-sockets sockopt-broadcast}
@ffindex @sortas{sockopt-broadcast sb-bsd-sockets} sockopt-broadcast [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:sockopt-broadcast socket
Return the value of the SO-BROADCAST socket option for @code{socket}. This can also be
updated with @code{setf}.
@end deffn
@anchor{Function sb-bsd-sockets sockopt-tcp-nodelay}
@ffindex @sortas{sockopt-tcp-nodelay sb-bsd-sockets} sockopt-tcp-nodelay [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:sockopt-tcp-nodelay socket
Return the value of the TCP-NODELAY socket option for @code{socket}. This can also be
updated with @code{setf}.
@end deffn
@node inet domain sockets
@section INET Domain Sockets

The TCP and UDP sockets that you know and love. Some representation
issues:

@itemize
@item IPv4 Internet addresses are represented by vectors of
  @code{(unsigned-byte 8)} (e.g. @code{#(127 0 0 1)}). Ports are just
  integers. No conversion between network- and host-order data is
  needed from the user of this package.

@item IPv6 Internet addresses are represented by length 16 vectors of
  @code{(unsigned-byte 8)} (e.g. @code{#(0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1)}.
  Ports are just integers. As for IPv4 addresses, no conversion
  between network- and host-order data is needed from the user of
  this package.

@item Socket addresses are represented by the two values for address and
  port, so for example, @code{(sb-bsd-sockets:socket-connect socket #(192
  168 1 1) 80)} for IPv4 and @code{(sb-bsd-sockets:socket-connect socket
  #(0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1) 80)} for IPv6.
@end itemize

@anchor{Class sb-bsd-sockets inet-socket}
@ttindex @sortas{inet-socket sb-bsd-sockets} inet-socket [sb-bsd-sockets]
@deffn{Class} sb-bsd-sockets:inet-socket
Class representing TCP and UDP over IPv4 sockets.

Examples:

@example
(make-instance 'sb-bsd-sockets:inet-socket :type :stream :protocol :tcp)

(make-instance 'sb-bsd-sockets:inet-socket :type :datagram :protocol :udp)
@end example
@end deffn
@anchor{Class sb-bsd-sockets inet6-socket}
@ttindex @sortas{inet6-socket sb-bsd-sockets} inet6-socket [sb-bsd-sockets]
@deffn{Class} sb-bsd-sockets:inet6-socket
Class representing TCP and UDP over IPv6 sockets.

Examples:

@example
(make-instance 'sb-bsd-sockets:inet6-socket :type :stream :protocol :tcp)

(make-instance 'sb-bsd-sockets:inet6-socket :type :datagram :protocol :udp)
@end example
@end deffn
@anchor{Function sb-bsd-sockets make-inet-address}
@ffindex @sortas{make-inet-address sb-bsd-sockets} make-inet-address [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:make-inet-address dotted-quads
Return a vector of octets given a string @code{dotted-quads} in the format
"127.0.0.1". Signals an error if the string is malformed.
@end deffn
@anchor{Function sb-bsd-sockets make-inet6-address}
@ffindex @sortas{make-inet6-address sb-bsd-sockets} make-inet6-address [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:make-inet6-address colon-separated-integers
Return a vector of octets given a string representation of an IPv6
address @code{colon-separated-integers}. Signal an error if the string is
malformed.
@end deffn
@anchor{Function sb-bsd-sockets get-protocol-by-name}
@ffindex @sortas{get-protocol-by-name sb-bsd-sockets} get-protocol-by-name [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:get-protocol-by-name name
Given a protocol name, return the protocol number, the protocol name, and
a list of protocol aliases.
@end deffn
@node local domain sockets
@section Local Domain Sockets

Local domain (@code{AF_LOCAL}) sockets are also known as Unix-domain
sockets but were renamed by POSIX presumably on the basis that they
may be available on other systems too.

A local socket address is a string, which is used to create a node
in the local filesystem. This means of course that they cannot be
used across a network.

@anchor{Class sb-bsd-sockets local-socket}
@ttindex @sortas{local-socket sb-bsd-sockets} local-socket [sb-bsd-sockets]
@deffn{Class} sb-bsd-sockets:local-socket
Class representing local domain (@code{AF_LOCAL}) sockets,
also known as Unix-domain sockets.
@end deffn
A local abstract socket address is also a string the scope of which is
the local machine. However, in contrast to a local socket address, there
is no corresponding filesystem node.

@anchor{Class sb-bsd-sockets local-abstract-socket}
@ttindex @sortas{local-abstract-socket sb-bsd-sockets} local-abstract-socket [sb-bsd-sockets]
@deffn{Class} sb-bsd-sockets:local-abstract-socket
Class representing local domain (@code{AF_LOCAL}) sockets with
addresses in the abstract namespace.
@end deffn
@node name service
@section Name Service

Presently name service is implemented by calling out to the
@code{getaddrinfo(3)} and @code{gethostinfo(3)}, or to @code{gethostbyname(3)} and
@code{gethostbyaddr(3)} on platforms where the preferred functions are
not available. The exact details of the name resolving process (for
example the choice of whether DNS or a hosts file is used for
lookup) are platform dependent.

@anchor{Class sb-bsd-sockets host-ent}
@ttindex @sortas{host-ent sb-bsd-sockets} host-ent [sb-bsd-sockets]
@deffn{Class} sb-bsd-sockets:host-ent
This class represents the results of an address lookup.
@end deffn
@anchor{Function sb-bsd-sockets get-host-by-name}
@ffindex @sortas{get-host-by-name sb-bsd-sockets} get-host-by-name [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:get-host-by-name host-name
Returns a @code{host-ent} instance for @code{host-name} or signals a @code{name-service-error}.

Another @code{host-ent} instance containing zero, one or more IPv6 addresses
may be returned as a second return value.

@code{host-name} may also be an IP address in dotted quad notation or some other
weird stuff - see getaddrinfo(3) for the details.
@end deffn
@anchor{Function sb-bsd-sockets get-host-by-address}
@ffindex @sortas{get-host-by-address sb-bsd-sockets} get-host-by-address [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:get-host-by-address address
Returns a @code{host-ent} instance for @code{address}, which should be a vector of
(integer 0 255) with 4 elements in case of an IPv4 address and 16
elements in case of an IPv6 address, or signals a @code{name-service-error}.
See gethostbyaddr(3) for details.
@end deffn
@anchor{Function sb-bsd-sockets host-ent-address}
@ffindex @sortas{host-ent-address sb-bsd-sockets} host-ent-address [sb-bsd-sockets]
@deffn{Function} sb-bsd-sockets:host-ent-address host-ent
Return some valid address for @code{host-ent}.
@end deffn
