1SENDMSG(3P)                POSIX Programmer's Manual               SENDMSG(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       sendmsg — send a message on a socket using a message structure
14

SYNOPSIS

16       #include <sys/socket.h>
17
18       ssize_t sendmsg(int socket, const struct msghdr *message, int flags);
19

DESCRIPTION

21       The sendmsg() function shall send a message through  a  connection-mode
22       or  connectionless-mode  socket. If the socket is a connectionless-mode
23       socket, the message shall be sent to the address specified by msghdr if
24       no  pre-specified peer address has been set. If a peer address has been
25       pre-specified, either the message shall be sent to the  address  speci‐
26       fied  in  msghdr  (overriding  the  pre-specified peer address), or the
27       function shall return −1 and set errno to [EISCONN].  If the socket  is
28       connection-mode, the destination address in msghdr shall be ignored.
29
30       The sendmsg() function takes the following arguments:
31
32       socket      Specifies the socket file descriptor.
33
34       message     Points  to a msghdr structure, containing both the destina‐
35                   tion address and the buffers for the outgoing message.  The
36                   length and format of the address depend on the address fam‐
37                   ily of the socket. The msg_flags member is ignored.
38
39       flags       Specifies the type of message transmission. The application
40                   may specify 0 or the following flag:
41
42                   MSG_EOR       Terminates a record (if supported by the pro‐
43                                 tocol).
44
45                   MSG_OOB       Sends out-of-band data on sockets  that  sup‐
46                                 port  out-of-bound data. The significance and
47                                 semantics of out-of-band data  are  protocol-
48                                 specific.
49
50                   MSG_NOSIGNAL  Requests not to send the SIGPIPE signal if an
51                                 attempt to send is made on a  stream-oriented
52                                 socket  that  is  no  longer  connected.  The
53                                 [EPIPE] error shall still be returned.
54
55       The msg_iov and msg_iovlen fields of message specify zero or more  buf‐
56       fers  containing  the  data  to be sent.  msg_iov points to an array of
57       iovec structures; msg_iovlen shall be set  to  the  dimension  of  this
58       array.  In each iovec structure, the iov_base field specifies a storage
59       area and the iov_len field gives its size in bytes. Some of these sizes
60       can  be  zero.  The data from each storage area indicated by msg_iov is
61       sent in turn.
62
63       Successful completion of a call to sendmsg() does not guarantee  deliv‐
64       ery  of  the  message.  A  return  value  of −1 indicates only locally-
65       detected errors.
66
67       If space is not available at the sending socket to hold the message  to
68       be  transmitted and the socket file descriptor does not have O_NONBLOCK
69       set, the sendmsg() function shall block until space  is  available.  If
70       space  is not available at the sending socket to hold the message to be
71       transmitted and the socket file descriptor does  have  O_NONBLOCK  set,
72       the sendmsg() function shall fail.
73
74       If  the socket protocol supports broadcast and the specified address is
75       a broadcast address for the socket protocol, sendmsg()  shall  fail  if
76       the SO_BROADCAST option is not set for the socket.
77
78       The  socket  in  use may require the process to have appropriate privi‐
79       leges to use the sendmsg() function.
80

RETURN VALUE

82       Upon successful completion, sendmsg() shall return the number of  bytes
83       sent.  Otherwise,  −1  shall  be returned and errno set to indicate the
84       error.
85

ERRORS

87       The sendmsg() function shall fail if:
88
89       EAGAIN or EWOULDBLOCK
90              The socket's  file  descriptor  is  marked  O_NONBLOCK  and  the
91              requested operation would block.
92
93       EAFNOSUPPORT
94              Addresses  in  the  specified address family cannot be used with
95              this socket.
96
97       EBADF  The socket argument is not a valid file descriptor.
98
99       ECONNRESET
100              A connection was forcibly closed by a peer.
101
102       EINTR  A signal interrupted sendmsg() before any data was transmitted.
103
104       EINVAL The sum of the iov_len values overflows an ssize_t.
105
106       EMSGSIZE
107              The message is too large to be sent all at once (as  the  socket
108              requires),  or  the  msg_iovlen  member  of the msghdr structure
109              pointed to by message is less than or equal to 0 or  is  greater
110              than {IOV_MAX}.
111
112       ENOTCONN
113              The socket is connection-mode but is not connected.
114
115       ENOTSOCK
116              The socket argument does not refer to a socket.
117
118       EOPNOTSUPP
119              The  socket  argument  is associated with a socket that does not
120              support one or more of the values set in flags.
121
122       EPIPE  The socket is shut down for writing, or the  socket  is  connec‐
123              tion-mode and is no longer connected. In the latter case, and if
124              the socket is of type  SOCK_STREAM  or  SOCK_SEQPACKET  and  the
125              MSG_NOSIGNAL flag is not set, the SIGPIPE signal is generated to
126              the calling thread.
127
128       If the address family of the socket is AF_UNIX,  then  sendmsg()  shall
129       fail if:
130
131       EIO    An  I/O error occurred while reading from or writing to the file
132              system.
133
134       ELOOP  A loop exists in symbolic links encountered during resolution of
135              the pathname in the socket address.
136
137       ENAMETOOLONG
138              The  length  of  a  component  of  a  pathname  is  longer  than
139              {NAME_MAX}.
140
141       ENOENT A component of the pathname does not name an  existing  file  or
142              the path name is an empty string.
143
144       ENOTDIR
145              A  component  of  the  path prefix of the pathname in the socket
146              address names an existing file that is neither a directory nor a
147              symbolic  link  to  a  directory,  or the pathname in the socket
148              address contains at least one  non-<slash>  character  and  ends
149              with  one or more trailing <slash> characters and the last path‐
150              name component names an existing file that is neither  a  direc‐
151              tory nor a symbolic link to a directory.
152
153       The sendmsg() function may fail if:
154
155       EACCES Search  permission is denied for a component of the path prefix;
156              or write access to the named socket is denied.
157
158       EDESTADDRREQ
159              The socket is not connection-mode and does  not  have  its  peer
160              address set, and no destination address was specified.
161
162       EHOSTUNREACH
163              The  destination  host  cannot  be reached (probably because the
164              host is down or a remote router cannot reach it).
165
166       EIO    An I/O error occurred while reading from or writing to the  file
167              system.
168
169       EISCONN
170              A  destination  address  was specified and the socket is already
171              connected.
172
173       ENETDOWN
174              The local network interface used to  reach  the  destination  is
175              down.
176
177       ENETUNREACH
178              No route to the network is present.
179
180       ENOBUFS
181              Insufficient  resources  were available in the system to perform
182              the operation.
183
184       ENOMEM Insufficient memory was available to fulfill the request.
185
186       If the address family of the socket is AF_UNIX, then sendmsg() may fail
187       if:
188
189       ELOOP  More  than  {SYMLOOP_MAX} symbolic links were encountered during
190              resolution of the pathname in the socket address.
191
192       ENAMETOOLONG
193              The length of a pathname exceeds {PATH_MAX}, or pathname resolu‐
194              tion  of  a symbolic link produced an intermediate result with a
195              length that exceeds {PATH_MAX}.
196
197       The following sections are informative.
198

EXAMPLES

200       Done.
201

APPLICATION USAGE

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

RATIONALE

207       None.
208

FUTURE DIRECTIONS

210       None.
211

SEE ALSO

213       getsockopt(), poll(), pselect(), recv(), recvfrom(), recvmsg(), send(),
214       sendto(), setsockopt(), shutdown(), socket()
215
216       The Base Definitions volume of POSIX.1‐2008, <sys_socket.h>
217
219       Portions of this text are reprinted and reproduced in  electronic  form
220       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
221       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
222       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
223       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
224       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
225       event of any discrepancy between this version and the original IEEE and
226       The  Open Group Standard, the original IEEE and The Open Group Standard
227       is the referee document. The original Standard can be  obtained  online
228       at http://www.unix.org/online.html .
229
230       Any  typographical  or  formatting  errors that appear in this page are
231       most likely to have been introduced during the conversion of the source
232       files  to  man page format. To report such errors, see https://www.ker
233       nel.org/doc/man-pages/reporting_bugs.html .
234
235
236
237IEEE/The Open Group                  2013                          SENDMSG(3P)
Impressum