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
19

DESCRIPTION

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

RETURN VALUE

77       Upon successful completion, sendmsg() shall return the number of  bytes
78       sent.  Otherwise,  -1  shall  be returned and errno set to indicate the
79       error.
80

ERRORS

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

EXAMPLES

192       Done.
193

APPLICATION USAGE

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

RATIONALE

199       None.
200

FUTURE DIRECTIONS

202       None.
203

SEE ALSO

205       getsockopt(), poll(), recv(), recvfrom(), recvmsg(), select(),  send(),
206       sendto(), setsockopt(), shutdown(), socket(), the Base Definitions vol‐
207       ume of IEEE Std 1003.1-2001, <sys/socket.h>
208
210       Portions of this text are reprinted and reproduced in  electronic  form
211       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
212       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
213       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
214       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
215       event of any discrepancy between this version and the original IEEE and
216       The Open Group Standard, the original IEEE and The Open Group  Standard
217       is  the  referee document. The original Standard can be obtained online
218       at http://www.opengroup.org/unix/online.html .
219
220
221
222IEEE/The Open Group                  2003                          SENDMSG(3P)
Impressum