sendmsg

SYNOPSIS
       #include <sys/socket.h>

       ssize_t sendmsg(int socket, const struct msghdr *message, int flags);


DESCRIPTION
       The  sendmsg()  function shall send a message through a connection-mode
       or connectionless-mode socket. If the  socket  is  connectionless-mode,
       the  message  shall  be sent to the address specified by msghdr. If the
       socket is connection-mode, the destination address in msghdr  shall  be
       ignored.

       The sendmsg() function takes the following arguments:

       socket Specifies the socket file descriptor.

       message
              Points  to  a  msghdr structure, containing both the destination
              address and the buffers for the outgoing message. The length and
              format  of  the  address  depend  on  the  address family of the
              socket. The msg_flags member is ignored.

       flags  Specifies the type of message transmission. The application  may
              specify 0 or the following flag:

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

       MSG_OOB
              Sends  out-of-band  data  on  sockets  that support out-of-bound
              data.  The significance and semantics of  out-of-band  data  are
              protocol-specific.



       The  msg_iov and msg_iovlen fields of message specify zero or more buf-
       fers containing the data to be sent.  msg_iov points  to  an  array  of
       iovec  structures;  msg_iovlen  shall  be  set to the dimension of this
       array. In each iovec structure, the iov_base field specifies a  storage
       area and the iov_len field gives its size in bytes. Some of these sizes
       can be zero. The data from each storage area indicated  by  msg_iov  is
       sent in turn.

       Successful  completion of a call to sendmsg() does not guarantee deliv-
       ery of the message. A  return  value  of  -1  indicates  only  locally-
       detected errors.

       If  space is not available at the sending socket to hold the message to
       be transmitted and the socket file descriptor does not have  O_NONBLOCK
       set,  the  sendmsg()  function shall block until space is available. If
       space is not available at the sending socket to hold the message to  be
       transmitted  and  the  socket file descriptor does have O_NONBLOCK set,
       error.

ERRORS
       The sendmsg() function shall fail if:

       EAGAIN or EWOULDBLOCK
              The  socket's  file  descriptor  is  marked  O_NONBLOCK  and the
              requested operation would block.

       EAFNOSUPPORT
              Addresses in the specified address family cannot  be  used  with
              this socket.

       EBADF  The socket argument is not a valid file descriptor.

       ECONNRESET
              A connection was forcibly closed by a peer.

       EINTR  A signal interrupted sendmsg() before any data was transmitted.

       EINVAL The sum of the iov_len values overflows an ssize_t.

       EMSGSIZE
              The  message  is too large to be sent all at once (as the socket
              requires), or the msg_iovlen  member  of  the  msghdr  structure
              pointed  to  by message is less than or equal to 0 or is greater
              than {IOV_MAX}.

       ENOTCONN
              The socket is connection-mode but is not connected.

       ENOTSOCK
              The socket argument does not refer to a socket.

       EOPNOTSUPP
              The socket argument is associated with a socket  that  does  not
              support one or more of the values set in flags.

       EPIPE  The  socket  is  shut down for writing, or the socket is connec-
              tion-mode and is no longer connected. In the latter case, and if
              the  socket is of type SOCK_STREAM, the SIGPIPE signal is gener-
              ated to the calling thread.


       If the address family of the socket is AF_UNIX,  then  sendmsg()  shall
       fail if:

       EIO    An  I/O error occurred while reading from or writing to the file
              system.

       ELOOP  A loop exists in symbolic links encountered during resolution of
              the pathname in the socket address.

       ENAMETOOLONG

       EACCES Search permission is denied for a component of the path  prefix;
              or write access to the named socket is denied.

       EDESTADDRREQ
              The  socket  is  not  connection-mode and does not have its peer
              address set, and no destination address was specified.

       EHOSTUNREACH
              The destination host cannot be  reached  (probably  because  the
              host is down or a remote router cannot reach it).

       EIO    An  I/O error occurred while reading from or writing to the file
              system.

       EISCONN
              A destination address was specified and the  socket  is  already
              connected.

       ENETDOWN
              The  local  network  interface  used to reach the destination is
              down.

       ENETUNREACH
              No route to the network is present.

       ENOBUFS
              Insufficient resources were available in the system  to  perform
              the operation.

       ENOMEM Insufficient memory was available to fulfill the request.


       If the address family of the socket is AF_UNIX, then sendmsg() may fail
       if:

       ELOOP  More than {SYMLOOP_MAX} symbolic links were  encountered  during
              resolution of the pathname in the socket address.

       ENAMETOOLONG
              Pathname  resolution of a symbolic link produced an intermediate
              result whose length exceeds {PATH_MAX}.


       The following sections are informative.

EXAMPLES
       Done.

APPLICATION USAGE
       The select() and poll() functions can be used to determine when  it  is
       possible to send more data.

RATIONALE
       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 .



IEEE/The Open Group                  2003                           SENDMSG(P)