X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/9bccf70c0258c7cac2dcb80011b2a964d884c552..0a7de7458d150b5d4dffc935ba399be265ef0a1a:/bsd/man/man2/send.2 diff --git a/bsd/man/man2/send.2 b/bsd/man/man2/send.2 index 2d9daca68..acadd27b2 100644 --- a/bsd/man/man2/send.2 +++ b/bsd/man/man2/send.2 @@ -38,25 +38,40 @@ .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 .Fd #include .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 +.Fd #include +.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