Man Linux: Main Page and Category List

NAME

       sys/socket.h - main sockets header

SYNOPSIS

       #include <sys/socket.h>

DESCRIPTION

       The  <sys/socket.h> header shall define the type socklen_t, which is an
       integer type of width of at least 32 bits; see APPLICATION USAGE.

       The <sys/socket.h>  header  shall  define  the  unsigned  integer  type
       sa_family_t.

       The  <sys/socket.h>  header  shall  define  the sockaddr structure that
       includes at least the following members:

              sa_family_t  sa_family  Address family.
              char         sa_data[]  Socket address (variable-length data).

       The sockaddr structure is used to define a socket address which is used
       in the bind(), connect(), getpeername(), getsockname(), recvfrom(), and
       sendto() functions.

       The <sys/socket.h> header shall define the sockaddr_storage  structure.
       This structure shall be:

        * Large  enough to accommodate all supported protocol-specific address
          structures

        * 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

       The sockaddr_storage structure shall contain  at  least  the  following
       members:

              sa_family_t   ss_family

       When  a sockaddr_storage structure is cast as a sockaddr structure, the
       ss_family field of the sockaddr_storage structure shall  map  onto  the
       sa_family  field  of  the  sockaddr  structure. When a sockaddr_storage
       structure  is  cast  as  a  protocol-specific  address  structure,  the
       ss_family  field  shall  map  onto a field of that structure that is of
       type sa_family_t and that identifies the protocol’s address family.

       The <sys/socket.h>  header  shall  define  the  msghdr  structure  that
       includes at least the following members:

              void          *msg_name        Optional address.
              socklen_t      msg_namelen     Size of address.
              struct iovec  *msg_iov         Scatter/gather array.
              int            msg_iovlen      Members in msg_iov.
              void          *msg_control     Ancillary data; see below.
              socklen_t      msg_controllen  Ancillary data buffer len.
              int            msg_flags       Flags on received message.

       The  msghdr  structure  is  used  to  minimize  the  number of directly
       supplied parameters to the recvmsg()  and  sendmsg()  functions.   This
       structure  is  used  as  a  value-  result  parameter  in the recvmsg()
       function and value only for the sendmsg() function.

       The iovec structure shall be defined as described in <sys/uio.h> .

       The <sys/socket.h> header  shall  define  the  cmsghdr  structure  that
       includes at least the following members:

              socklen_t  cmsg_len    Data byte count, including the cmsghdr.
              int        cmsg_level  Originating protocol.
              int        cmsg_type   Protocol-specific type.

       The  cmsghdr  structure  is  used  for storage of ancillary data object
       information.

       Ancillary data consists of a sequence of pairs, each  consisting  of  a
       cmsghdr structure followed by a data array. The data array contains the
       ancillary data message, and the cmsghdr structure contains  descriptive
       information that allows an application to correctly parse the data.

       The  values for cmsg_level shall be legal values for the level argument
       to  the   getsockopt()   and   setsockopt()   functions.   The   system
       documentation shall specify the cmsg_type definitions for the supported
       protocols.

       Ancillary data is also possible at the socket level. The <sys/socket.h>
       header  defines the following macro for use as the cmsg_type value when
       cmsg_level is SOL_SOCKET:

       SCM_RIGHTS
              Indicates that the data array contains the access rights  to  be
              sent or received.

       The  <sys/socket.h>  header defines the following macros to gain access
       to the data arrays in the ancillary  data  associated  with  a  message
       header:

       CMSG_DATA(cmsg)

              If  the argument is a pointer to a cmsghdr structure, this macro
              shall return an unsigned character pointer  to  the  data  array
              associated with the cmsghdr structure.

       CMSG_NXTHDR(mhdr,cmsg)

              If the first argument is a pointer to a msghdr structure and the
              second argument is a pointer  to  a  cmsghdr  structure  in  the
              ancillary  data  pointed  to  by  the  msg_control field of that
              msghdr structure, this macro shall return a pointer to the  next
              cmsghdr  structure,  or  a null pointer if this structure is the
              last cmsghdr in the ancillary data.

       CMSG_FIRSTHDR(mhdr)

              If the argument is a pointer to a msghdr structure,  this  macro
              shall  return  a  pointer  to the first cmsghdr structure in the
              ancillary data associated with this msghdr structure, or a  null
              pointer if there is no ancillary data associated with the msghdr
              structure.

       The <sys/socket.h>  header  shall  define  the  linger  structure  that
       includes at least the following members:

              int  l_onoff   Indicates whether linger option is enabled.
              int  l_linger  Linger time, in seconds.

       The  <sys/socket.h>  header  shall  define  the  following macros, with
       distinct integer values:

       SOCK_DGRAM
              Datagram socket.

       SOCK_RAW
              Raw Protocol Interface.

       SOCK_SEQPACKET
              Sequenced-packet socket.

       SOCK_STREAM
              Byte-stream socket.

       The <sys/socket.h> header shall define the following macro for  use  as
       the level argument of setsockopt() and getsockopt().

       SOL_SOCKET
              Options to be accessed at socket level, not protocol level.

       The  <sys/socket.h>  header  shall  define  the  following macros, with
       distinct integer  values,  for  use  as  the  option_name  argument  in
       getsockopt() or setsockopt() calls:

       SO_ACCEPTCONN
              Socket is accepting connections.

       SO_BROADCAST
              Transmission of broadcast messages is supported.

       SO_DEBUG
              Debugging information is being recorded.

       SO_DONTROUTE
              Bypass normal routing.

       SO_ERROR
              Socket error status.

       SO_KEEPALIVE
              Connections are kept alive with periodic messages.

       SO_LINGER
              Socket lingers on close.

       SO_OOBINLINE
              Out-of-band data is transmitted in line.

       SO_RCVBUF
              Receive buffer size.

       SO_RCVLOWAT
              Receive ‘‘low water mark’’.

       SO_RCVTIMEO
              Receive timeout.

       SO_REUSEADDR
              Reuse of local addresses is supported.

       SO_SNDBUF
              Send buffer size.

       SO_SNDLOWAT
              Send ‘‘low water mark’’.

       SO_SNDTIMEO
              Send timeout.

       SO_TYPE
              Socket type.

       The  <sys/socket.h>  header  shall  define  the  following macro as the
       maximum backlog queue length which may  be  specified  by  the  backlog
       field of the listen() function:

       SOMAXCONN
              The maximum backlog queue length.

       The  <sys/socket.h>  header  shall  define  the  following macros, with
       distinct integer values, for use as the valid values for the  msg_flags
       field  in  the  msghdr structure, or the flags parameter in recvfrom(),
       recvmsg(), sendmsg(), or sendto() calls:

       MSG_CTRUNC
              Control data truncated.

       MSG_DONTROUTE
              Send without using routing tables.

       MSG_EOR
              Terminates a record (if supported by the protocol).

       MSG_OOB
              Out-of-band data.

       MSG_PEEK
              Leave received data in queue.

       MSG_TRUNC
              Normal data truncated.

       MSG_WAITALL
              Attempt to fill the read buffer.

       The <sys/socket.h> header  shall  define  the  following  macros,  with
       distinct integer values:

       AF_INET
              Internet domain sockets for use with IPv4 addresses.

       AF_INET6
              Internet domain sockets for use with IPv6 addresses.

       AF_UNIX
              UNIX domain sockets.

       AF_UNSPEC
              Unspecified.

       The  <sys/socket.h>  header  shall  define  the  following macros, with
       distinct integer values:

       SHUT_RD
              Disables further receive operations.

       SHUT_RDWR
              Disables further send and receive operations.

       SHUT_WR
              Disables further send operations.

       The following shall be declared as functions and may also be defined as
       macros. Function prototypes shall be provided.

              int     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]);

       Inclusion  of  <sys/socket.h>  may  also  make visible all symbols from
       <sys/uio.h>.

       The following sections are informative.

APPLICATION USAGE

       To forestall portability problems, it is recommended that  applications
       not use values larger than 2**31 -1 for the socklen_t type.

       The  sockaddr_storage 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
       getpeername(),  and  determine  the  address  family  by  accessing the
       received content after the call.

       The example below illustrates a data structure which aligns on a 64-bit
       boundary.  An implementation-defined field _ss_align following _ss_pad1
       is used to force a 64-bit alignment which covers proper alignment  good
       enough for needs of at least sockaddr_in6 (IPv6) and sockaddr_in (IPv4)
       address data structures. The size of padding field _ss_pad1 depends  on
       the  chosen  alignment  boundary.  The  size  of padding field _ss_pad2
       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.

              /*
               *  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. */

              /*
               *  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. */
              };

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       <sys/uio.h> , the System  Interfaces  volume  of  IEEE Std 1003.1-2001,
       accept(),     bind(),    connect(),    getpeername(),    getsockname(),
       getsockopt(),  listen(),   recv(),   recvfrom(),   recvmsg(),   send(),
       sendmsg(), sendto(), setsockopt(), shutdown(), socket(), socketpair()

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 .