diff options
Diffstat (limited to 'man0p/sys_socket.h.0p')
| -rw-r--r-- | man0p/sys_socket.h.0p | 446 |
1 files changed, 446 insertions, 0 deletions
diff --git a/man0p/sys_socket.h.0p b/man0p/sys_socket.h.0p new file mode 100644 index 000000000..12cca0b6b --- /dev/null +++ b/man0p/sys_socket.h.0p @@ -0,0 +1,446 @@ +.\" 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 . |