]> git.saurik.com Git - apple/xnu.git/blobdiff - bsd/man/man2/send.2
xnu-6153.11.26.tar.gz
[apple/xnu.git] / bsd / man / man2 / send.2
index 2d9daca688fe847dc0dd8f3307db598abe3d434f..acadd27b245e9d12603a4a9c64d6b807b472a021 100644 (file)
 .Os BSD 4.2
 .Sh NAME
 .Nm send ,
-.Nm sendto ,
-.Nm sendmsg
+.Nm sendmsg ,
+.Nm sendto
 .Nd send a message from a socket
 .Sh SYNOPSIS
-.Fd #include <sys/types.h>
 .Fd #include <sys/socket.h>
 .Ft ssize_t
-.Fn send "int s" "const void *msg" "size_t len" "int flags"
+.Fo send
+.Fa "int socket"
+.Fa "const void *buffer"
+.Fa "size_t length"
+.Fa "int flags"
+.Fc
 .Ft ssize_t
-.Fn sendto "int s" "const void *msg" "size_t len" "int flags" "const struct sockaddr *to" "int tolen"
+.Fo sendmsg
+.Fa "int socket"
+.Fa "const struct msghdr *message"
+.Fa "int flags"
+.Fc
 .Ft ssize_t
-.Fn sendmsg "int s" "const struct msghdr *msg" "int flags"
+.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 send ,
 .Fn sendto ,
 and
 .Fn sendmsg
 are used to transmit a message to another socket.
-.Fn Send
+.Fn send
 may be used only when the socket is in a 
 .Em connected
 state, while 
@@ -66,12 +81,12 @@ and
 may be used at any time.
 .Pp
 The address of the target is given by
-.Fa to
+.Fa dest_addr
 with 
-.Fa tolen
+.Fa dest_len
 specifying its size.
 The length of the message is given by
-.Fa len .
+.Fa length .
 If the message is too long to pass atomically through the
 underlying protocol, the error
 .Er EMSGSIZE
@@ -112,55 +127,188 @@ 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 description of the
+for a complete description of the
 .Fa msghdr
 structure.
 .Sh RETURN VALUES
-The call returns the number of characters sent, or -1
-if an error occurred.
+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
-.Fn Send ,
-.Fn sendto ,
+The
+.Fn send ,
+.Fn sendmsg ,
 and
-.Fn sendmsg
-fail if:
+.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 was specified.
-.It Bq Er ENOTSOCK
-The argument
-.Fa s
-is not a socket.
+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 was specified for a parameter.
+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 made this impossible.
-.It Bq Er EAGAIN
-The socket is marked non-blocking and the requested operation
-would block.
+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 was unable to allocate an internal buffer.
+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 was full.
+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 EACCES
-The SO_BROADCAST option is not set on the socket, and a broadcast address
-was given as the destination.
-.It Bq Er EHOSTUNREACH
-The destination address specified an unreachable host.
+.\" ===========
+.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 getsockopt 2 ,
 .Xr socket 2 ,
-.Xr write 2
+.Xr write 2 ,
+.Xr compat 5
 .Sh HISTORY
 The
 .Fn send