hpux sendto man page on unix.com

send(2) System Calls Manual send(2)

NAME
send(), sendmsg(), sendto() - send a message from a socket

SYNOPSIS
UNIX 03 Only (X/Open Sockets)
Obsolescent UNIX 95 Only (X/Open Sockets)
DESCRIPTION
The and system calls transmit a message to another socket. can be used only when the socket is in a connected state, whereas and can be
used at any time. allows the send data to be gathered from several buffers specified in the structure.

s is a socket descriptor that specifies the socket on which the message will be sent.

msg points to the buffer containing the message.

If the socket uses connection-based communications, such as a SOCK_STREAM socket, these calls can only be used after the connection has
been established (see connect(2)). In this case, any destination specified by to is ignored. For connectionless sockets, such as
SOCK_DGRAM, must be used unless the destination address has already been specified by If the destination address has been specified and is
used, an error results if any address is specified by to.

The address of the target socket is contained in a socket address structure pointed to by to, with tolen specifying the size of the struc-
ture.

If a 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. In this case, there is no guarantee that the same local address will be used for successive requests on the same
socket.

The length of the message is given by len in bytes. 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, is returned, and is set to For SOCK_DGRAM sockets, this size is
fixed by the implementation (see the section). Otherwise there is no size limit.

When or returns a positive value, it only indicates this number of bytes have been sent to the local transport provider. It does not mean
this number of bytes have been delivered to the peer socket application. A SOCK_DGRAM socket does not guarantee end-to-end delivery. A
SOCK_STREAM socket guarantees eventual end-to-end delivery, however its underlying transport provider may later detect an irrecoverable
error and returns a value of at another socket function call.

When or returns a value of , it indicates a locally detected error. is set to indicate the error.

performs the same action as but it gathers the output data from the buffers specified in the structure (see below). This structure is
defined in and has the following form

msg_name points to a structure in which the address of the destination socket should be stored, if the socket is connectionless; msg_name
may be a null pointer if no name is specified. msg_iov specifies the locations of the character arrays for storing the outbound data.
msg_accrights specifies a buffer that contains any access rights to be sent along with the message. Access rights are limited to file
descriptors of size int. If access rights are not being transferred, set the msg_accrights field to NULL. Access rights are supported
only for AF_UNIX.

If no buffer space is available to hold the data to be transmitted, blocks unless nonblocking mode is enabled. The three ways to enable
nonblocking mode are:

o with the request,

o with the flag, and

o with the flag.

If nonblocking I/O is enabled using or the equivalent request (defined in and explained in ioctl(2), ioctl(5), and socket(7)), although the
use of is not recommended, the request completes in one of three ways:

o If there is enough space available in the system to buffer all of the data, completes successfully, having written out all of the
data, and returns the number of bytes written.

o If there is not enough space in the buffer to write out the entire request, completes successfully, having written as much data as
possible, and returns the number of bytes it was able to write.

o If there is no space in the system to buffer any of the data, fails, having written no data, and is set to

If nonblocking I/O is disabled using always executes completely (blocking as necessary) and returns the number of bytes written.

If the flag is set using (defined in and explained in fcntl(2) and fcntl(5)), POSIX-style nonblocking I/O is enabled. In this case, the
request completes in one of three ways:

o If there is enough space available in the system to buffer all of the data, completes successfully, having written out all of the
data, and returns the number of bytes written.

o If there is not enough space in the buffer to write out the entire request, completes successfully, having written as much data as
possible, and returns the number of bytes it was able to write.

o If there is no space in the system to buffer any of the data, completes, having written no data, and returns -1, with set to

If the flag is set using (defined in and explained in fcntl(2) and fcntl(5)), nonblocking I/O is enabled. In this case, the request com-
pletes in one of three ways:

o If there is enough space available in the system to buffer all of the data, completes successfully, having written out all of the
data, and returns the number of bytes written.

o If there is not enough space in the buffer to write out the entire request, completes successfully, having written as much data as
possible, and returns the number of bytes it was able to write.

o If there is no space in the system to buffer any of the data, completes successfully, having written no data, and returns 0.

If the flag is cleared using nonblocking I/O is disabled. In this case, the always executes completely (blocking as necessary) and returns
the number of bytes written.

Since the and flags and requests are supported, the following clarifies on how these features interact. If the or flag has been set,
requests behave accordingly, regardless of any requests. If neither the flag nor the flag has been set, requests control the behavior of

By default nonblocking I/O is disabled.

The supported values for flags are zero or any combination of and

The flag is used to send out-of-band data.

The flag is used to initiate a write-side shutdown along with the send operation. Use of the flag is semantically equivalent to a followed
immediately (if the send is successful) by a If the data send operation fails then the shutdown operation is not performed. Once this flag
is used in a successful call, no further data may be sent on the socket.

A call made to a socket behaves in exactly the same way as with flags set to zero.

is not supported for AF_UNIX or AF_VME_LINK sockets.

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

AF_CCITT Only
Sockets of the address family AF_CCITT operate in message mode. Although they are specified as connection-based (SOCK_STREAM) sockets, the
X.25 subsystem communicates via messages. They require that a connection be established with the or calls.

The flag is not supported. Use requests to control nonblocking I/O. If the available buffer space is not large enough for the entire mes-
sage and the socket is in nonblocking mode, is set to If the amount of data in the exceeds the maximum outbound message size, is set to

The call is not supported.

Each call sends either a complete or a partial X.25 message. This is controlled by the setting of the More-Data-To-Follow (MDTF) bit. If
the user wants to send a partial message, MDTF should be set to 1 before the call. The MDTF bit should be cleared to 0 before sending the
final message fragment.

Message fragment length may range from 0 bytes up to the size of the socket's send buffer. The MDTF bit and multiple calls can be combined
to transmit complete X.25 packet sequences (zero or more DATA packets in which the More Data bit is set, followed by one DATA packet in
which the More Data bit is clear) of arbitrary length. Note that a 0-byte message is not actually sent, but may be necessary to flush a
complete X.25 message if the user is controlling the MDTF bit.

Sockets of the AF_CCITT address family can send 1 byte of out-of-band data (known as an INTERRUPT data packet in X.25 terminology), or up
to 32 bytes if the X.25 interface is configured for 1984 CCITT X.25 recommendations. INTERRUPT data packets sent in blocking mode cause
the process to block until confirmation is received. INTERRUPT data packets sent with the socket in nonblocking mode do not cause the
process to block; instead, an out-of-band message is queued to the socket when the INTERRUPT confirmation packet is received (see recv(2)).

X/Open Sockets Only
For the structure has the following form:

msg_control specifies a buffer of ancillary data to send along with the message. Ancillary data consists of a sequence of pairs, each con-
sisting of a cmsghdr structure followed by a data array. The data array contains the ancillary data message, and the cmsghdr structure
contains descriptive information that allows an application to correctly parse the data. cmsghdr has the following structure:

If the cmsg_level is and cmsg_type is then it indicates that the data array contains the access rights to be sent. Access rights are sup-
ported only for AF_UNIX. Access rights are limited to file descriptors of size int.

If the cmsg_level is then cmsg_type must be one of the supported types: or (See description in ip6(7P)).

If ancillary data are not being transferred, set the msg_control field to NULL, and set the msg_controllen field to 0.

The msg_flags member is ignored.

X/Open Sockets Compilation Environment
See xopen_networking(7).

RETURN VALUE
and return the following values:

Successful completion.
n is the number of bytes sent.
Failure.
is set to indicate the error.

ERRORS
If or fails, is set to one of the following values.

Process doing a of a broadcast packet does not have broadcast capability enabled for the socket. Use to enable broadcast capa-
bility.

The specified address is not a valid address for the
address family of this socket.

Nonblocking I/O is enabled using the
flag with and the requested operation would block, or the socket has an error that was set asynchronously. An
asynchronous error can be caused by a gateway failing to forward a datagram from this socket because the data-
gram exceeds the MTU of the next-hop network and the "Don't Fragment" (DF) bit in the datagram is set. (See in
getsockopt(2)).

s is not a valid file descriptor.

A connection was forcibly closed by a peer.

The to parameter needs to specify a destination address for the message. This is also given if the specified
address contains unspecified fields (see inet(7F)).

An invalid pointer was specified in the
msg or to parameter, or in the structure.

The operation was interrupted by a signal before any data was sent.
(If some data was sent, returns the number of bytes sent before the signal, and is not set).

The len or tolen parameter, or a length in the structure is invalid. A system call was issued on an X.25 socket, or
the connection is in its reset sequence and cannot accept data.

A timeout occurred.

An address was specified by
to for a SOCK_DGRAM socket which is already connected.

A length in the structure is invalid. The socket requires that messages be sent atomically, and the size of the message to be
sent made this impossible.

SOCK_DGRAM/AF_INET or SOCK_STREAM/AF_CCITT: The message size exceeded the outbound buffer size.

The interface used for the specified address is "down" (see
ifconfig(1M)), no interface for the specified address can be found (SO_DONTROUTE socket option in use), or the
X.25 Level 2 is down.

The destination host is not reachable.

The destination network is not reachable.
Some of the possible causes for this error are:

(LAN) All encapsulations (for example, Ethernet, IEEE) have been turned off (see also ifconfig(1M)).

(X.25) The X.25 Level 2 is down. The X.25 link layer is not working (wires might be broken, connections are
loose on the interface hoods at the modem, the modem failed, the packet switch at the remote end lost power or
failed for some reason, or electrical noise interfered with the line for an extremely long period of time).

No buffer space is available in the system to perform the operation.

No memory is available in the system to perform the operation.

The remote system or an intermediate system in the communications path
does not support a protocol option sent by the local system. This option may have been set using a or call, or
set as a system parameter.

A on a socket that is not connected, or a on a socket that has not completed the connect sequence with its peer,
or is no longer connected to its peer.

s is a valid file descriptor, but it is not a socket.

The flag was specified; it is not supported for AF_UNIX or AF_VME_LINK sockets.

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. Note that
the default action for unless the process has established a signal handler for this signal, is to terminate the
process.

Nonblocking I/O is enabled using
request and the requested operation would block.

DEPENDENCIES
UDP messages are fragmented at the IP level into Maximum Transmission Unit (MTU) sized pieces; MTU varies for different link types. These
pieces, called IP fragments, can be transmitted, but IP does not guarantee delivery. Sending large messages may cause too many fragments
and overrun a receiver's ability to receive them. If this happens the complete message cannot be reassembled. This affects the apparent
reliability and throughput of the network as viewed by the end user.

The default and maximum buffer sizes are protocol-specific. Refer to the appropriate entries in Sections 7F and 7P for details. The buf-
fer size can be set by calling with

OBSOLESCENCE
Currently, the and types are the same size. This is compatible with the UNIX 95 and UNIX 03 profiles. However, in a future release, might
be a different size. In that case, the size of the and structures and the relative position of their members will be different, which
might affect application behavior. Applications that use now, where appropriate, will avoid such migration problems. On the other hand,
applications that need to be portable to the UNIX 95 profile should follow the X/Open specification (see xopen_networking(7)).

WARNINGS
Linking binary objects compiled to specification and binary objects compiled to specification to the same executable may result in unex-
pected behavior, including application abnormal termination and unexpected socket errors. See xopen_networking(7) for details and remedy.

FUTURE DIRECTION
Currently, the default behavior is the however, it might be changed to in a future release. At that time, any behavior that is incompati-
ble with might be obsoleted. Applications that conform to the X/Open specification now will avoid migration problems (see xopen_network-
ing(7)).

AUTHOR
and were developed by HP and the University of California, Berkeley.

The feature is an HP-specific extension to the socket API.

SEE ALSO
ifconfig(1M), getsockopt(2), recv(2), select(2), setsockopt(2), shutdown(2), socket(2), thread_safety(5), socket(7), xopen_networking(7),
inet(7F), IPv6(7P), sctp(7), TCP(7P), UDP(7P), UNIX(7P).

STANDARDS CONFORMANCE
send(2)

hpux man page for sendto