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

NAME

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

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

199       Done.
200

APPLICATION USAGE

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

RATIONALE

206       None.
207

FUTURE DIRECTIONS

209       None.
210

SEE ALSO

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