sendmsg(3xnet)

1sendmsg(3XNET)   X/Open Networking Services Library Functions   sendmsg(3XNET)
2
3
4

NAME

6       sendmsg - send a message on a socket using a message structure
7

SYNOPSIS

9       cc [ flag ... ] file ... -lxnet [ library ... ]
10       #include <sys/socket.h>
11
12       ssize_t sendmsg(int socket, const struct msghdr *message, int flags);
13
14

PARAMETERS

16       The function takes the following arguments:
17
18       socket     Specifies the socket file descriptor.
19
20
21       message    Points  to  a msghdr structure, containing both the destina‐
22                  tion address and the buffers for the outgoing  message.  The
23                  length  and format of the address depend on the address fam‐
24                  ily of the socket.  The msg_flags member is ignored.
25
26
27       flags      Specifies the type of message transmission. The  application
28                  may specify 0 or the following flag:
29
30                  MSG_EOR    Terminates  a  record (if supported by the proto‐
31                             col)
32
33
34                  MSG_OOB    Sends out-of-band data on  sockets  that  support
35                             out-of-bound data. The significance and semantics
36                             of out-of-band data are protocol-specific.
37
38
39

DESCRIPTION

41       The sendmsg() function sends a message  through  a  connection-mode  or
42       connectionless-mode  socket.  If the socket is connectionless-mode, the
43       message will be sent to the address specified by msghdr.  If the socket
44       is connection-mode, the destination address in msghdr is ignored.
45
46
47       The   msg_iov  and   msg_iovlen  fields of message specify zero or more
48       buffers containing the data to be sent. msg_iov points to an  array  of
49       iovec  structures;   msg_iovlen  must  be  set to the dimension of this
50       array. In each  iovec structure, the  iov_base field specifies  a stor‐
51       age area and the  iov_len field gives its size  in bytes. Some of these
52       sizes can be zero.  The  data  from  each  storage  area  indicated  by
53       msg_iov is sent in turn.
54
55
56       Successful  completion of a call to sendmsg() does not guarantee deliv‐
57       ery of the message. A  return  value  of  −1  indicates  only  locally-
58       detected errors.
59
60
61       If  space is not available at the sending socket to hold the message to
62       be transmitted and the socket file descriptor does not have  O_NONBLOCK
63       set,  sendmsg()  function blocks until space is available.  If space is
64       not available at the sending socket to hold the message to be transmit‐
65       ted  and the socket file descriptor does have O_NONBLOCK set, sendmsg()
66       function will fail.
67
68
69       If the socket protocol supports broadcast and the specified address  is
70       a broadcast address for the socket protocol, sendmsg() will fail if the
71       SO_BROADCAST option is not set for the socket.
72
73
74       The socket in use may require the process to  have  appropriate  privi‐
75       leges to use the sendmsg() function.
76

USAGE

78       The  select(3C)  and poll(2) functions can be used to determine when it
79       is possible to send more data.
80

RETURN VALUES

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

ERRORS

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

ATTRIBUTES

217       See attributes(5) for descriptions of the following attributes:
218
219
220
221
222       ┌─────────────────────────────┬─────────────────────────────┐
223       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
224       ├─────────────────────────────┼─────────────────────────────┤
225       │Interface Stability          │Standard                     │
226       ├─────────────────────────────┼─────────────────────────────┤
227       │MT-Level                     │MT-Safe                      │
228       └─────────────────────────────┴─────────────────────────────┘
229