SEND

C Interface

        #include <sys/types.h>

        #include <sys/socket.h>



        send(s, msg, len, flags)

        int s;

        char *msg;

        int len, flags;



        sendmsg(s, msg, flags)

        int s;

        struct msghdr msg[];

        int flags;



   AF_UNIX only:



        #include <sys/types.h>

        #include <sys/socket.h>

        #include <sys/un.h>



        sendto(s, msg, len, flags, to, tolen)

        int s;

        char *msg;

        int len, flags;

        struct sockaddr_un *to;

        int tolen;



   AF_INET only:



        #include <sys/types.h>

        #include <sys/socket.h>

        #include <netinet/in.h>



        sendto(s, msg, len, flags, to, tolen)

        int s;

        char *msg;

        int len, flags;

        struct sockaddr_in *to;

        int tolen;

Description

The send, sendto, and sendmsg calls are used to transmit a message to another socket.

The argument s is a socket descriptor that specifies the socket on which the message is sent. The msg parameter points to the buffer that contains the message.

If the socket uses connection-based communications (for example, a SOCK_STREAM socket), then these calls can be used only after the connection has been established. (Refer to connect.) In this case, any destination specified by the to parameter is ignored. For connection-less sockets (for example, SOCK_DGRAM), the to parameter must be used.

The address of the target is contained in a socket address structure pointed at by to, with the tolen parameter specifying the size of the structure. If the address specified in the argument is a broadcast address, the SO_BROADCAST option must be set for broadcasting to succeed.

If a sendto is attempted on a SOCK_DGRAM socket before any local address has been bound to it, the system automatically selects a local address to be used for the message (AF_INET only). In this case, there is no guarantee that the same local address is used for successive sendto requests on the same socket.

The length of the message is given by len. The length of data actually sent is returned. If the message is too long to pass atomically through the underlying protocol, the message is not transmitted, -1 is returned, and errno is set to EMSGSIZE. For SOCK_DGRAM and SOCK_STREAM sockets, this size is fixed by the implementation. (Refer to "MPE/iX Specific" section below.)

No indication of failure to deliver is implicit in a send, sendto, or sendmsg. Return values of -1 indicate some locally detected errors.

If no buffer space is available to hold the data to be transmitted, send blocks unless non-blocking mode is enabled. There are two ways to enable non-blocking mode: with the O_NONBLOCK fcntl flag and with the O_NDELAY fcntl flag.

If O_NONBLOCK is set using fcntl (defined in <fcntl.h.sys>and explained in the fcntl section), POSIX-style non-blocking I/O is enabled. In this case, the send request completes in one of three ways:

If there is enough space available in the system to buffer all of the data, the send completes successfully, having written out all of the data and returns the number of bytes written.
If there is not enough space in the buffer to write out the entire request, the send completes successfully, having written as much data as possible, and returns the number of bytes that it was able to write.
If there is no space in the system to buffer any of the data, the send completes successfully, having written no data, and returns a -1 with errno set to EAGAIN.
If O_NDELAY is set using fcntl (defined in <fcntl.h.sys> and explained in the fcntl section), non-blocking I/O is enabled. In this case, the send request completes in one of three ways:
If there is enough space available in the system to buffer all of the data, the send completes successfully, having written out all of the data, and returns the number of bytes written.
If there is not enough space in the buffer to write out the entire request, the send completes successfully, having written as much data as possible, and returns the number of bytes that it was able to write.
If there is no space in the system to buffer any of the data, the send completes successfully, having written no data, and returns 0.

If the O_NDELAY and O_NONBLOCK flags are cleared using fcntl, non-blocking I/O is disabled. In this case, the send always executes completely (blocking as necessary) and returns the number of bytes written.

If the available buffer space is not large enough for the entire message, the EWOULDBLOCK error is returned.

To summarize, both behave the same if there is enough space to write all of the data or even some of the data. They differ in the third case, where there is not enough space to write any of the data.

The select call can be used to determine when it is possible to send more data.

The supported values for flags are zero. A write() call made to a socket behaves the same way as send with flags set to zero.

See recv for a description of the msghdr structure for sendmsg.

Return Value

If successful, the call returns the number of characters sent. If the call fails, a -1 is returned, and an error code is stored in errno.

Errors

The following errors are returned by send, sendto, or sendmsg:

[EACCES]: Process doing a send of a broadcast packet is not privileged.
[EBADF]: An invalid descriptor was specified.
[ENOTSOCK]: The argument s is not a socket.
[EFAULT]: The msg or to parameter is not a valid pointer.
[EMSGSIZE]: The socket requires that messages be sent atomically, and the size of the message to be sent made this impossible.
[EWOULDBLOCK]: The socket is in non-blocking mode, and the requested operation would block.
[ENOBUFS]: Insufficient resources were available in the system to perform the operation.
[EINVAL]: The len or tolen parameter contains a bad value.
[EDESTADDRREQ]: The to parameter needs to specify a destination address for the message. This is also given if the specified address contains unspecified fields. (Refer to the inet section.)
[ENOTCONN]: The send on a socket has not connected, or a send on a socket did not complete the connect sequence with its peer or is no longer connected to its peer.
[EAFNOSUPPORT]: Requested address does not match the address family of this socket.
[EPIPE]: An attempt was made to send on a socket that was connected, but the connection has been shut down either by the remote peer or by this side of the connection.
[EOPNOTSUPP]: The MSG_OOB flag was specified; it is not supported for AF_UNIX sockets.
[EINTR]: The call was interrupted by a signal before a valid connection arrived.

MPE/iX Specific

The maximum udp message size that can be sent on a SOCK_DGRAM socket is 30,000 bytes on MPE/iX, as opposed to 9,216 bytes on HP-UX. For SOCK_STREAM, there is also a maximum message size of 30,000 bytes on MPE/iX. For AF_UNIX, there is a maximum window size of 30,000 bytes.

The sendto call can be used only with SOCK_DGRAM sockets.

The send call can be used only with SOCK_STREAM sockets.

The flags parameter must be zero.

Author

UCB (University of California at Berkeley)