[apple/xnu.git] / bsd / man / man2 / send.2

.\"	$NetBSD: send.2,v 1.6 1996/01/15 01:17:18 thorpej Exp $
.\"
.\" Copyright (c) 1983, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)send.2	8.2 (Berkeley) 2/21/94
.\"
.Dd February 21, 1994
.Dt SEND 2
.Os BSD 4.2
.Sh NAME
.Nm send ,
.Nm sendmsg ,
.Nm sendto
.Nd send a message from a socket
.Sh SYNOPSIS
.Fd #include <sys/socket.h>
.Ft ssize_t
.Fo send
.Fa "int socket"
.Fa "const void *buffer"
.Fa "size_t length"
.Fa "int flags"
.Fc
.Ft ssize_t
.Fo sendmsg
.Fa "int socket"
.Fa "const struct msghdr *message"
.Fa "int flags"
.Fc
.Ft ssize_t
.Fo sendto
.Fa "int socket"
.Fa "const void *buffer"
.Fa "size_t length"
.Fa "int flags"
.Fa "const struct sockaddr *dest_addr"
.Fa "socklen_t dest_len"
.Fc
.Sh DESCRIPTION
.Fn send ,
.Fn sendto ,
and
.Fn sendmsg
are used to transmit a message to another socket.
.Fn send
may be used only when the socket is in a 
.Em connected
state, while 
.Fn sendto
and
.Fn sendmsg
may be used at any time.
.Pp
The address of the target is given by
.Fa dest_addr
with 
.Fa dest_len
specifying its size.
The length of the message is given by
.Fa length .
If the message is too long to pass atomically through the
underlying protocol, the error
.Er EMSGSIZE
is returned, and
the message is not transmitted.
.Pp
No indication of failure to deliver is implicit in a
.Fn send .
Locally detected errors are indicated by a return value of -1.
.Pp
If no messages space is available at the socket to hold
the message to be transmitted, then
.Fn send
normally blocks, unless the socket has been placed in
non-blocking I/O mode.
The
.Xr select 2
call may be used to determine when it is possible to
send more data.
.Pp
The
.Fa flags
parameter may include one or more of the following:
.Bd -literal
#define	MSG_OOB        0x1  /* process out-of-band data */
#define	MSG_DONTROUTE  0x4  /* bypass routing, use direct interface */
.Ed
.Pp
The flag
.Dv MSG_OOB
is used to send
.Dq out-of-band
data on sockets that support this notion (e.g.
.Dv SOCK_STREAM ) ;
the underlying protocol must also support
.Dq out-of-band
data.
.Dv MSG_DONTROUTE
is usually used only by diagnostic or routing programs.
.Pp
The
.Fn sendmsg
system call uses a
.Fa msghdr
structure to minimize the number of directly supplied arguments.
The 
.Fa msg_iov
and 
.Fa msg_iovlen 
fields of message specify zero or more buffers 
containing the data to be sent. 
.Fa msg_iov 
points to an array of iovec structures; 
.Fa msg_iovlen 
shall be set to the dimension of this array. 
In each iovec structure, the 
.Fa iov_base 
field specifies a storage area and 
the 
.Fa iov_len 
field gives its size in bytes. Some of these sizes can be zero. 
The data from each storage area indicated by 
.Fa msg_iov 
is sent in turn.
See 
.Xr recv 2
for a complete description of the
.Fa msghdr
structure.
.Sh RETURN VALUES
Upon successful completion,
the number of bytes which were sent is returned.
Otherwise, -1 is returned and the global variable
.Va errno
is set to indicate the error.
.Sh ERRORS
The
.Fn send ,
.Fn sendmsg ,
and
.Fn sendto
system calls will fail if:
.Bl -tag -width Er
.\" ===========
.It Bq Er EACCES
The SO_BROADCAST option is not set on the socket
and a broadcast address is given as the destination.
.\" ===========
.It Bq Er EAGAIN
The socket is marked non-blocking
and the requested operation would block.
.\" ===========
.It Bq Er EBADF
An invalid descriptor is specified.
.\" ===========
.It Bq Er ECONNRESET
A connection is forcibly closed by a peer.
.\" ===========
.It Bq Er EFAULT
An invalid user space address is specified for a parameter.
.\" ===========
.It Bq Er EHOSTUNREACH
The destination address specifies an unreachable host.
.\" ===========
.It Bq Er EINTR
A signal interrupts the system call
before any data is transmitted.
.\" ===========
.It Bq Er EMSGSIZE
The socket requires that message be sent atomically,
and the size of the message to be sent makes this impossible.
.Dv IOV_MAX .
.\" ===========
.It Bq Er ENETDOWN
The local network interface used to reach the destination is down.
.\" ===========
.It Bq Er ENETUNREACH
No route to the network is present.
.\" ===========
.It Bq Er ENOBUFS
The system is unable to allocate an internal buffer.
The operation may succeed when buffers become available.
.\" ===========
.It Bq Er ENOBUFS
The output queue for a network interface is full.
This generally indicates that the interface has stopped sending,
but may be caused by transient congestion.
.\" ===========
.It Bq Er ENOTSOCK
The argument
.Fa socket
is not a socket.
.\" ===========
.It Bq Er EOPNOTSUPP
.Fa socket
does not support (some of) the option(s) specified in
.Fa flags . 
.\" ===========
.It Bq Er EPIPE
The socket is shut down for writing
or the socket is connection-mode and is no longer connected.
In the latter case, and if the socket is of type SOCK_STREAM,
the SIGPIPE signal is generated to the calling thread.
.\" ==========
.It Bq Er EADDRNOTAVAIL
The specified address is not available or no longer available on this machine.
.El
.Pp
The
.Fn sendmsg
and
.Fn sendto
system calls will fail if:
.Bl -tag -width Er
.\" ===========
.It Bq Er EAFNOSUPPORT
Addresses in the specified address family cannot be used
with this socket.
.\" ===========
.It Bq Er EDESTADDRREQ
The socket is not connection-mode and does not have its peer address set,
and no destination address is specified.
.\" ===========
.It Bq Er EISCONN
A destination address was specified and the socket is already connected.
.\" ===========
.It Bq Er ENOENT
A component of the pathname does not name an existing file
or the path name is an empty string.
.\" ===========
.It Bq Er ENOMEM
Insufficient memory is available to fulfill the request.
.\" ===========
.It Bq Er ENOTCONN
The socket is connection-mode, but is not connected.
.\" ===========
.It Bq Er ENOTDIR
A component of the path prefix of the pathname in the socket address
is not a directory.
.El
.Pp
The
.Fn send
system call will fail if:
.Bl -tag -width Er
.\" ===========
.It Bq Er EDESTADDRREQ
The socket is not connection-mode and no peer address is set.
.\" ===========
.It Bq Er ENOTCONN
The socket is not connected or otherwise has not had the peer pre-specified.
.El
.Pp
The
.Fn sendmsg
system call will fail if:
.Bl -tag -width Er
.\" ===========
.It Bq Er EINVAL
The sum of the iov_len values overflows an ssize_t.
.\" ===========
.It Bq Er EMSGSIZE
The socket requires that message be sent atomically,
and the size of the message to be sent makes this impossible, 
or the msg_iovlen member of the msghdr structure pointed to by message 
is less than or equal to 0 or is greater than 
.Dv IOV_MAX .
.El
.Sh LEGACY SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Pp
The include file
.In sys/types.h is necessary.
.Sh SEE ALSO
.Xr fcntl 2 ,
.Xr getsockopt 2 ,
.Xr recv 2 ,
.Xr select 2 ,
.Xr socket 2 ,
.Xr write 2 ,
.Xr compat 5
.Sh HISTORY
The
.Fn send
function call appeared in
.Bx 4.2 .
Commit	Line	Data
9bccf70c A	1	.\" $NetBSD: send.2,v 1.6 1996/01/15 01:17:18 thorpej Exp $
	2	.\"
	3	.\" Copyright (c) 1983, 1991, 1993
	4	.\" The Regents of the University of California. All rights reserved.
	5	.\"
	6	.\" Redistribution and use in source and binary forms, with or without
	7	.\" modification, are permitted provided that the following conditions
	8	.\" are met:
	9	.\" 1. Redistributions of source code must retain the above copyright
	10	.\" notice, this list of conditions and the following disclaimer.
	11	.\" 2. Redistributions in binary form must reproduce the above copyright
	12	.\" notice, this list of conditions and the following disclaimer in the
	13	.\" documentation and/or other materials provided with the distribution.
	14	.\" 3. All advertising materials mentioning features or use of this software
	15	.\" must display the following acknowledgement:
	16	.\" This product includes software developed by the University of
	17	.\" California, Berkeley and its contributors.
	18	.\" 4. Neither the name of the University nor the names of its contributors
	19	.\" may be used to endorse or promote products derived from this software
	20	.\" without specific prior written permission.
	21	.\"
	22	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	23	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	24	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	25	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	26	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	27	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	28	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	29	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	30	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	31	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	32	.\" SUCH DAMAGE.
	33	.\"
	34	.\" @(#)send.2 8.2 (Berkeley) 2/21/94
	35	.\"
	36	.Dd February 21, 1994
	37	.Dt SEND 2
	38	.Os BSD 4.2
	39	.Sh NAME
	40	.Nm send ,
2d21ac55 A	41	.Nm sendmsg ,
2d21ac55 A	42	.Nm sendto
9bccf70c A	43	.Nd send a message from a socket
9bccf70c A	44	.Sh SYNOPSIS
9bccf70c A	45	.Fd #include <sys/socket.h>
9bccf70c A	46	.Ft ssize_t
2d21ac55 A	47	.Fo send
	48	.Fa "int socket"
	49	.Fa "const void *buffer"
	50	.Fa "size_t length"
	51	.Fa "int flags"
	52	.Fc
9bccf70c	53	.Ft ssize_t
2d21ac55 A	54	.Fo sendmsg
2d21ac55 A	55	.Fa "int socket"
b0d623f7	56	.Fa "const struct msghdr *message"
2d21ac55 A	57	.Fa "int flags"
2d21ac55 A	58	.Fc
9bccf70c	59	.Ft ssize_t
2d21ac55 A	60	.Fo sendto
	61	.Fa "int socket"
	62	.Fa "const void *buffer"
	63	.Fa "size_t length"
	64	.Fa "int flags"
	65	.Fa "const struct sockaddr *dest_addr"
	66	.Fa "socklen_t dest_len"
	67	.Fc
9bccf70c	68	.Sh DESCRIPTION
39037602	69	.Fn send ,
9bccf70c A	70	.Fn sendto ,
	71	and
	72	.Fn sendmsg
	73	are used to transmit a message to another socket.
39037602	74	.Fn send
9bccf70c A	75	may be used only when the socket is in a
	76	.Em connected
	77	state, while
	78	.Fn sendto
	79	and
	80	.Fn sendmsg
	81	may be used at any time.
	82	.Pp
	83	The address of the target is given by
2d21ac55	84	.Fa dest_addr
9bccf70c	85	with
2d21ac55	86	.Fa dest_len
9bccf70c A	87	specifying its size.
9bccf70c A	88	The length of the message is given by
2d21ac55	89	.Fa length .
9bccf70c A	90	If the message is too long to pass atomically through the
	91	underlying protocol, the error
	92	.Er EMSGSIZE
	93	is returned, and
	94	the message is not transmitted.
	95	.Pp
	96	No indication of failure to deliver is implicit in a
	97	.Fn send .
	98	Locally detected errors are indicated by a return value of -1.
	99	.Pp
	100	If no messages space is available at the socket to hold
	101	the message to be transmitted, then
	102	.Fn send
	103	normally blocks, unless the socket has been placed in
	104	non-blocking I/O mode.
	105	The
	106	.Xr select 2
	107	call may be used to determine when it is possible to
	108	send more data.
	109	.Pp
	110	The
	111	.Fa flags
	112	parameter may include one or more of the following:
	113	.Bd -literal
	114	#define MSG_OOB 0x1 /* process out-of-band data */
	115	#define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */
	116	.Ed
	117	.Pp
	118	The flag
	119	.Dv MSG_OOB
	120	is used to send
	121	.Dq out-of-band
	122	data on sockets that support this notion (e.g.
	123	.Dv SOCK_STREAM ) ;
	124	the underlying protocol must also support
	125	.Dq out-of-band
	126	data.
	127	.Dv MSG_DONTROUTE
	128	is usually used only by diagnostic or routing programs.
	129	.Pp
b0d623f7 A	130	The
	131	.Fn sendmsg
	132	system call uses a
	133	.Fa msghdr
	134	structure to minimize the number of directly supplied arguments.
	135	The
	136	.Fa msg_iov
	137	and
	138	.Fa msg_iovlen
	139	fields of message specify zero or more buffers
	140	containing the data to be sent.
	141	.Fa msg_iov
	142	points to an array of iovec structures;
	143	.Fa msg_iovlen
	144	shall be set to the dimension of this array.
	145	In each iovec structure, the
	146	.Fa iov_base
	147	field specifies a storage area and
	148	the
	149	.Fa iov_len
	150	field gives its size in bytes. Some of these sizes can be zero.
	151	The data from each storage area indicated by
	152	.Fa msg_iov
	153	is sent in turn.
9bccf70c A	154	See
9bccf70c A	155	.Xr recv 2
b0d623f7	156	for a complete description of the
9bccf70c A	157	.Fa msghdr
	158	structure.
	159	.Sh RETURN VALUES
2d21ac55 A	160	Upon successful completion,
	161	the number of bytes which were sent is returned.
	162	Otherwise, -1 is returned and the global variable
	163	.Va errno
	164	is set to indicate the error.
9bccf70c	165	.Sh ERRORS
2d21ac55 A	166	The
	167	.Fn send ,
	168	.Fn sendmsg ,
9bccf70c	169	and
2d21ac55 A	170	.Fn sendto
2d21ac55 A	171	system calls will fail if:
9bccf70c	172	.Bl -tag -width Er
2d21ac55 A	173	.\" ===========
	174	.It Bq Er EACCES
	175	The SO_BROADCAST option is not set on the socket
	176	and a broadcast address is given as the destination.
	177	.\" ===========
	178	.It Bq Er EAGAIN
	179	The socket is marked non-blocking
	180	and the requested operation would block.
	181	.\" ===========
9bccf70c	182	.It Bq Er EBADF
2d21ac55 A	183	An invalid descriptor is specified.
	184	.\" ===========
	185	.It Bq Er ECONNRESET
	186	A connection is forcibly closed by a peer.
	187	.\" ===========
9bccf70c	188	.It Bq Er EFAULT
2d21ac55 A	189	An invalid user space address is specified for a parameter.
	190	.\" ===========
	191	.It Bq Er EHOSTUNREACH
	192	The destination address specifies an unreachable host.
	193	.\" ===========
	194	.It Bq Er EINTR
	195	A signal interrupts the system call
	196	before any data is transmitted.
	197	.\" ===========
9bccf70c A	198	.It Bq Er EMSGSIZE
9bccf70c A	199	The socket requires that message be sent atomically,
2d21ac55	200	and the size of the message to be sent makes this impossible.
b0d623f7	201	.Dv IOV_MAX .
2d21ac55 A	202	.\" ===========
	203	.It Bq Er ENETDOWN
	204	The local network interface used to reach the destination is down.
	205	.\" ===========
	206	.It Bq Er ENETUNREACH
	207	No route to the network is present.
	208	.\" ===========
9bccf70c	209	.It Bq Er ENOBUFS
2d21ac55	210	The system is unable to allocate an internal buffer.
9bccf70c	211	The operation may succeed when buffers become available.
2d21ac55	212	.\" ===========
9bccf70c	213	.It Bq Er ENOBUFS
2d21ac55	214	The output queue for a network interface is full.
9bccf70c A	215	This generally indicates that the interface has stopped sending,
9bccf70c A	216	but may be caused by transient congestion.
2d21ac55 A	217	.\" ===========
	218	.It Bq Er ENOTSOCK
	219	The argument
	220	.Fa socket
	221	is not a socket.
	222	.\" ===========
	223	.It Bq Er EOPNOTSUPP
	224	.Fa socket
	225	does not support (some of) the option(s) specified in
	226	.Fa flags .
	227	.\" ===========
	228	.It Bq Er EPIPE
	229	The socket is shut down for writing
	230	or the socket is connection-mode and is no longer connected.
	231	In the latter case, and if the socket is of type SOCK_STREAM,
	232	the SIGPIPE signal is generated to the calling thread.
d9a64523 A	233	.\" ==========
	234	.It Bq Er EADDRNOTAVAIL
	235	The specified address is not available or no longer available on this machine.
2d21ac55 A	236	.El
	237	.Pp
	238	The
	239	.Fn sendmsg
	240	and
	241	.Fn sendto
	242	system calls will fail if:
	243	.Bl -tag -width Er
	244	.\" ===========
	245	.It Bq Er EAFNOSUPPORT
	246	Addresses in the specified address family cannot be used
	247	with this socket.
	248	.\" ===========
	249	.It Bq Er EDESTADDRREQ
	250	The socket is not connection-mode and does not have its peer address set,
	251	and no destination address is specified.
	252	.\" ===========
	253	.It Bq Er EISCONN
	254	A destination address was specified and the socket is already connected.
	255	.\" ===========
	256	.It Bq Er ENOENT
	257	A component of the pathname does not name an existing file
	258	or the path name is an empty string.
	259	.\" ===========
	260	.It Bq Er ENOMEM
	261	Insufficient memory is available to fulfill the request.
	262	.\" ===========
	263	.It Bq Er ENOTCONN
	264	The socket is connection-mode, but is not connected.
	265	.\" ===========
	266	.It Bq Er ENOTDIR
	267	A component of the path prefix of the pathname in the socket address
	268	is not a directory.
	269	.El
	270	.Pp
	271	The
	272	.Fn send
	273	system call will fail if:
	274	.Bl -tag -width Er
	275	.\" ===========
	276	.It Bq Er EDESTADDRREQ
	277	The socket is not connection-mode and no peer address is set.
	278	.\" ===========
	279	.It Bq Er ENOTCONN
	280	The socket is not connected or otherwise has not had the peer pre-specified.
9bccf70c	281	.El
2d21ac55 A	282	.Pp
	283	The
	284	.Fn sendmsg
	285	system call will fail if:
	286	.Bl -tag -width Er
	287	.\" ===========
	288	.It Bq Er EINVAL
	289	The sum of the iov_len values overflows an ssize_t.
b0d623f7 A	290	.\" ===========
	291	.It Bq Er EMSGSIZE
	292	The socket requires that message be sent atomically,
	293	and the size of the message to be sent makes this impossible,
	294	or the msg_iovlen member of the msghdr structure pointed to by message
	295	is less than or equal to 0 or is greater than
	296	.Dv IOV_MAX .
2d21ac55 A	297	.El
	298	.Sh LEGACY SYNOPSIS
	299	.Fd #include <sys/types.h>
	300	.Fd #include <sys/socket.h>
	301	.Pp
	302	The include file
	303	.In sys/types.h is necessary.
9bccf70c A	304	.Sh SEE ALSO
9bccf70c A	305	.Xr fcntl 2 ,
2d21ac55	306	.Xr getsockopt 2 ,
9bccf70c A	307	.Xr recv 2 ,
9bccf70c A	308	.Xr select 2 ,
9bccf70c	309	.Xr socket 2 ,
2d21ac55 A	310	.Xr write 2 ,
2d21ac55 A	311	.Xr compat 5
9bccf70c A	312	.Sh HISTORY
	313	The
	314	.Fn send
	315	function call appeared in
	316	.Bx 4.2 .