mirror of https://github.com/mkerrisk/man-pages
447 lines
13 KiB
Plaintext
447 lines
13 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "<sys/socket.h>" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" <sys/socket.h>
|
|
.SH NAME
|
|
sys/socket.h \- main sockets header
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <sys/socket.h>\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fI<sys/socket.h>\fP header shall define the type \fBsocklen_t\fP,
|
|
which is an integer type of width of at least 32
|
|
bits; see APPLICATION USAGE.
|
|
.LP
|
|
The \fI<sys/socket.h>\fP header shall define the unsigned integer
|
|
type \fBsa_family_t\fP.
|
|
.LP
|
|
The \fI<sys/socket.h>\fP header shall define the \fBsockaddr\fP structure
|
|
that includes at least the following
|
|
members:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBsa_family_t sa_family \fP Address family. \fB
|
|
char sa_data[] \fP Socket address (variable-length data). \fB
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The \fBsockaddr\fP structure is used to define a socket address which
|
|
is used in the \fIbind\fP(), \fIconnect\fP(), \fIgetpeername\fP(),
|
|
\fIgetsockname\fP(),
|
|
\fIrecvfrom\fP(), and \fIsendto\fP()
|
|
functions.
|
|
.LP
|
|
The \fI<sys/socket.h>\fP header shall define the \fBsockaddr_storage\fP
|
|
structure. This structure shall be:
|
|
.IP " *" 3
|
|
Large enough to accommodate all supported protocol-specific address
|
|
structures
|
|
.LP
|
|
.IP " *" 3
|
|
Aligned at an appropriate boundary so that pointers to it can be cast
|
|
as pointers to protocol-specific address structures and
|
|
used to access the fields of those structures without alignment problems
|
|
.LP
|
|
.LP
|
|
The \fBsockaddr_storage\fP structure shall contain at least the following
|
|
members:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBsa_family_t ss_family
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
When a \fBsockaddr_storage\fP structure is cast as a \fBsockaddr\fP
|
|
structure, the \fIss_family\fP field of the
|
|
\fBsockaddr_storage\fP structure shall map onto the \fIsa_family\fP
|
|
field of the \fBsockaddr\fP structure. When a
|
|
\fBsockaddr_storage\fP structure is cast as a protocol-specific address
|
|
structure, the \fIss_family\fP field shall map onto a
|
|
field of that structure that is of type \fBsa_family_t\fP and that
|
|
identifies the protocol's address family.
|
|
.LP
|
|
The \fI<sys/socket.h>\fP header shall define the \fBmsghdr\fP structure
|
|
that includes at least the following
|
|
members:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBvoid *msg_name \fP Optional address. \fB
|
|
socklen_t msg_namelen \fP Size of address. \fB
|
|
struct iovec *msg_iov \fP Scatter/gather array. \fB
|
|
int msg_iovlen \fP Members in \fImsg_iov\fP. \fB
|
|
void *msg_control \fP Ancillary data; see below. \fB
|
|
socklen_t msg_controllen \fP Ancillary data buffer \fIlen\fP. \fB
|
|
int msg_flags \fP Flags on received message. \fB
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The \fBmsghdr\fP structure is used to minimize the number of directly
|
|
supplied parameters to the \fIrecvmsg\fP() and \fIsendmsg\fP() functions.
|
|
This
|
|
structure is used as a \fIvalue\fP- \fIresult\fP parameter in the
|
|
\fIrecvmsg\fP()
|
|
function and \fIvalue\fP only for the \fIsendmsg\fP() function.
|
|
.LP
|
|
The \fBiovec\fP structure shall be defined as described in \fI<sys/uio.h>\fP
|
|
\&.
|
|
.LP
|
|
The \fI<sys/socket.h>\fP header shall define the \fBcmsghdr\fP structure
|
|
that includes at least the following
|
|
members:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBsocklen_t cmsg_len \fP Data byte count, including the \fBcmsghdr\fP. \fB
|
|
int cmsg_level \fP Originating protocol. \fB
|
|
int cmsg_type \fP Protocol-specific type. \fB
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The \fBcmsghdr\fP structure is used for storage of ancillary data
|
|
object information.
|
|
.LP
|
|
Ancillary data consists of a sequence of pairs, each consisting of
|
|
a \fBcmsghdr\fP structure followed by a data array. The data
|
|
array contains the ancillary data message, and the \fBcmsghdr\fP structure
|
|
contains descriptive information that allows an
|
|
application to correctly parse the data.
|
|
.LP
|
|
The values for \fIcmsg_level\fP shall be legal values for the \fIlevel\fP
|
|
argument to the \fIgetsockopt\fP() and \fIsetsockopt\fP()
|
|
functions. The system documentation shall specify the \fIcmsg_type\fP
|
|
definitions for the supported protocols.
|
|
.LP
|
|
Ancillary data is also possible at the socket level. The \fI<sys/socket.h>\fP
|
|
header defines the following macro for use
|
|
as the \fIcmsg_type\fP value when \fIcmsg_level\fP is SOL_SOCKET:
|
|
.TP 7
|
|
SCM_RIGHTS
|
|
Indicates that the data array contains the access rights to be sent
|
|
or received.
|
|
.sp
|
|
.LP
|
|
The \fI<sys/socket.h>\fP header defines the following macros to gain
|
|
access to the data arrays in the ancillary data
|
|
associated with a message header:
|
|
.TP 7
|
|
CMSG_DATA(\fIcmsg\fP)
|
|
.sp
|
|
If the argument is a pointer to a \fBcmsghdr\fP structure, this macro
|
|
shall return an unsigned character pointer to the data array
|
|
associated with the \fBcmsghdr\fP structure.
|
|
.TP 7
|
|
CMSG_NXTHDR(\fImhdr,cmsg\fP)
|
|
.sp
|
|
If the first argument is a pointer to a \fBmsghdr\fP structure and
|
|
the second argument is a pointer to a \fBcmsghdr\fP structure
|
|
in the ancillary data pointed to by the \fImsg_control\fP field of
|
|
that \fBmsghdr\fP structure, this macro shall return a pointer
|
|
to the next \fBcmsghdr\fP structure, or a null pointer if this structure
|
|
is the last \fBcmsghdr\fP in the ancillary data.
|
|
.TP 7
|
|
CMSG_FIRSTHDR(\fImhdr\fP)
|
|
.sp
|
|
If the argument is a pointer to a \fBmsghdr\fP structure, this macro
|
|
shall return a pointer to the first \fBcmsghdr\fP structure
|
|
in the ancillary data associated with this \fBmsghdr\fP structure,
|
|
or a null pointer if there is no ancillary data associated with
|
|
the \fBmsghdr\fP structure.
|
|
.sp
|
|
.LP
|
|
The \fI<sys/socket.h>\fP header shall define the \fBlinger\fP structure
|
|
that includes at least the following
|
|
members:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBint l_onoff \fP Indicates whether linger option is enabled. \fB
|
|
int l_linger \fP Linger time, in seconds. \fB
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The \fI<sys/socket.h>\fP header shall define the following macros,
|
|
with distinct integer values:
|
|
.TP 7
|
|
SOCK_DGRAM
|
|
Datagram socket.
|
|
.TP 7
|
|
SOCK_RAW
|
|
Raw Protocol Interface.
|
|
.TP 7
|
|
SOCK_SEQPACKET
|
|
Sequenced-packet socket.
|
|
.TP 7
|
|
SOCK_STREAM
|
|
Byte-stream socket.
|
|
.sp
|
|
.LP
|
|
The \fI<sys/socket.h>\fP header shall define the following macro for
|
|
use as the \fIlevel\fP argument of \fIsetsockopt\fP() and \fIgetsockopt\fP().
|
|
.TP 7
|
|
SOL_SOCKET
|
|
Options to be accessed at socket level, not protocol level.
|
|
.sp
|
|
.LP
|
|
The \fI<sys/socket.h>\fP header shall define the following macros,
|
|
with distinct integer values, for use as the
|
|
\fIoption_name\fP argument in \fIgetsockopt\fP() or \fIsetsockopt\fP()
|
|
calls:
|
|
.TP 7
|
|
SO_ACCEPTCONN
|
|
Socket is accepting connections.
|
|
.TP 7
|
|
SO_BROADCAST
|
|
Transmission of broadcast messages is supported.
|
|
.TP 7
|
|
SO_DEBUG
|
|
Debugging information is being recorded.
|
|
.TP 7
|
|
SO_DONTROUTE
|
|
Bypass normal routing.
|
|
.TP 7
|
|
SO_ERROR
|
|
Socket error status.
|
|
.TP 7
|
|
SO_KEEPALIVE
|
|
Connections are kept alive with periodic messages.
|
|
.TP 7
|
|
SO_LINGER
|
|
Socket lingers on close.
|
|
.TP 7
|
|
SO_OOBINLINE
|
|
Out-of-band data is transmitted in line.
|
|
.TP 7
|
|
SO_RCVBUF
|
|
Receive buffer size.
|
|
.TP 7
|
|
SO_RCVLOWAT
|
|
Receive ``low water mark''.
|
|
.TP 7
|
|
SO_RCVTIMEO
|
|
Receive timeout.
|
|
.TP 7
|
|
SO_REUSEADDR
|
|
Reuse of local addresses is supported.
|
|
.TP 7
|
|
SO_SNDBUF
|
|
Send buffer size.
|
|
.TP 7
|
|
SO_SNDLOWAT
|
|
Send ``low water mark''.
|
|
.TP 7
|
|
SO_SNDTIMEO
|
|
Send timeout.
|
|
.TP 7
|
|
SO_TYPE
|
|
Socket type.
|
|
.sp
|
|
.LP
|
|
The \fI<sys/socket.h>\fP header shall define the following macro as
|
|
the maximum \fIbacklog\fP queue length which may be
|
|
specified by the \fIbacklog\fP field of the \fIlisten\fP() function:
|
|
.TP 7
|
|
SOMAXCONN
|
|
The maximum \fIbacklog\fP queue length.
|
|
.sp
|
|
.LP
|
|
The \fI<sys/socket.h>\fP header shall define the following macros,
|
|
with distinct integer values, for use as the valid
|
|
values for the \fImsg_flags\fP field in the \fBmsghdr\fP structure,
|
|
or the \fIflags\fP parameter in \fIrecvfrom\fP(), \fIrecvmsg\fP(),
|
|
\fIsendmsg\fP(), or \fIsendto\fP() calls:
|
|
.TP 7
|
|
MSG_CTRUNC
|
|
Control data truncated.
|
|
.TP 7
|
|
MSG_DONTROUTE
|
|
Send without using routing tables.
|
|
.TP 7
|
|
MSG_EOR
|
|
Terminates a record (if supported by the protocol).
|
|
.TP 7
|
|
MSG_OOB
|
|
Out-of-band data.
|
|
.TP 7
|
|
MSG_PEEK
|
|
Leave received data in queue.
|
|
.TP 7
|
|
MSG_TRUNC
|
|
Normal data truncated.
|
|
.TP 7
|
|
MSG_WAITALL
|
|
Attempt to fill the read buffer.
|
|
.sp
|
|
.LP
|
|
The \fI<sys/socket.h>\fP header shall define the following macros,
|
|
with distinct integer values:
|
|
.TP 7
|
|
AF_INET
|
|
Internet domain sockets for use with IPv4 addresses.
|
|
.TP 7
|
|
AF_INET6
|
|
Internet domain sockets for use with IPv6 addresses.
|
|
.TP 7
|
|
AF_UNIX
|
|
UNIX domain sockets.
|
|
.TP 7
|
|
AF_UNSPEC
|
|
Unspecified.
|
|
.sp
|
|
.LP
|
|
The \fI<sys/socket.h>\fP header shall define the following macros,
|
|
with distinct integer values:
|
|
.TP 7
|
|
SHUT_RD
|
|
Disables further receive operations.
|
|
.TP 7
|
|
SHUT_RDWR
|
|
Disables further send and receive operations.
|
|
.TP 7
|
|
SHUT_WR
|
|
Disables further send operations.
|
|
.sp
|
|
.LP
|
|
The following shall be declared as functions and may also be defined
|
|
as macros. Function prototypes shall be provided.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBint accept(int, struct sockaddr *restrict, socklen_t *restrict);
|
|
int bind(int, const struct sockaddr *, socklen_t);
|
|
int connect(int, const struct sockaddr *, socklen_t);
|
|
int getpeername(int, struct sockaddr *restrict, socklen_t *restrict);
|
|
int getsockname(int, struct sockaddr *restrict, socklen_t *restrict);
|
|
int getsockopt(int, int, int, void *restrict, socklen_t *restrict);
|
|
int listen(int, int);
|
|
ssize_t recv(int, void *, size_t, int);
|
|
ssize_t recvfrom(int, void *restrict, size_t, int,
|
|
struct sockaddr *restrict, socklen_t *restrict);
|
|
ssize_t recvmsg(int, struct msghdr *, int);
|
|
ssize_t send(int, const void *, size_t, int);
|
|
ssize_t sendmsg(int, const struct msghdr *, int);
|
|
ssize_t sendto(int, const void *, size_t, int, const struct sockaddr *,
|
|
socklen_t);
|
|
int setsockopt(int, int, int, const void *, socklen_t);
|
|
int shutdown(int, int);
|
|
int socket(int, int, int);
|
|
int sockatmark(int);
|
|
int socketpair(int, int, int, int[2]);
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
Inclusion of \fI<sys/socket.h>\fP may also make visible all symbols
|
|
from \fI<sys/uio.h>\fP.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
To forestall portability problems, it is recommended that applications
|
|
not use values larger than 2**31
|
|
-1 for the \fBsocklen_t\fP type.
|
|
.LP
|
|
The \fBsockaddr_storage\fP structure solves the problem of declaring
|
|
storage for automatic variables which is both large enough
|
|
and aligned enough for storing the socket address data structure of
|
|
any family. For example, code with a file descriptor and
|
|
without the context of the address family can pass a pointer to a
|
|
variable of this type, where a pointer to a socket address
|
|
structure is expected in calls such as \fIgetpeername\fP(), and determine
|
|
the
|
|
address family by accessing the received content after the call.
|
|
.LP
|
|
The example below illustrates a data structure which aligns on a 64-bit
|
|
boundary. An implementation-defined field
|
|
\fI_ss_align\fP following \fI_ss_pad1\fP is used to force a 64-bit
|
|
alignment which covers proper alignment good enough for needs
|
|
of at least \fBsockaddr_in6\fP (IPv6) and \fBsockaddr_in\fP (IPv4)
|
|
address data structures. The size of padding field
|
|
\fI_ss_pad1\fP depends on the chosen alignment boundary. The size
|
|
of padding field \fI_ss_pad2\fP depends on the value of overall
|
|
size chosen for the total size of the structure. This size and alignment
|
|
are represented in the above example by
|
|
implementation-defined (not required) constants _SS_MAXSIZE (chosen
|
|
value 128) and _SS_ALIGNMENT (with chosen value 8). Constants
|
|
_SS_PAD1SIZE (derived value 6) and _SS_PAD2SIZE (derived value 112)
|
|
are also for illustration and not required. The
|
|
implementation-defined definitions and structure field names above
|
|
start with an underscore to denote implementation private name
|
|
space. Portable code is not expected to access or reference those
|
|
fields or constants.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB/*
|
|
* Desired design of maximum size and alignment.
|
|
*/
|
|
#define _SS_MAXSIZE 128
|
|
/* Implementation-defined maximum size. */
|
|
#define _SS_ALIGNSIZE (sizeof(int64_t))
|
|
/* Implementation-defined desired alignment. */
|
|
.sp
|
|
|
|
/*
|
|
* Definitions used for sockaddr_storage structure paddings design.
|
|
*/
|
|
#define _SS_PAD1SIZE (_SS_ALIGNSIZE - sizeof(sa_family_t))
|
|
#define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof(sa_family_t)+ \\
|
|
_SS_PAD1SIZE + _SS_ALIGNSIZE))
|
|
struct sockaddr_storage {
|
|
sa_family_t ss_family; /* Address family. */
|
|
/*
|
|
* Following fields are implementation-defined.
|
|
*/
|
|
char _ss_pad1[_SS_PAD1SIZE];
|
|
/* 6-byte pad; this is to make implementation-defined
|
|
pad up to alignment field that follows explicit in
|
|
the data structure. */
|
|
int64_t _ss_align; /* Field to force desired structure
|
|
storage alignment. */
|
|
char _ss_pad2[_SS_PAD2SIZE];
|
|
/* 112-byte pad to achieve desired size,
|
|
_SS_MAXSIZE value minus size of ss_family
|
|
__ss_pad1, __ss_align fields is 112. */
|
|
};
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fI<sys/uio.h>\fP , the System Interfaces volume of
|
|
IEEE\ Std\ 1003.1-2001, \fIaccept\fP(), \fIbind\fP(), \fIconnect\fP(),
|
|
\fIgetpeername\fP(), \fIgetsockname\fP(),
|
|
\fIgetsockopt\fP(), \fIlisten\fP(), \fIrecv\fP(), \fIrecvfrom\fP(),
|
|
\fIrecvmsg\fP(), \fIsend\fP(), \fIsendmsg\fP(), \fIsendto\fP(), \fIsetsockopt\fP(),
|
|
\fIshutdown\fP(), \fIsocket\fP(), \fIsocketpair\fP()
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|