sendmsg Subroutine

Purpose

Sends a message from a socket using a message structure.

Library

Standard C Library (libc.a)

Syntax

#include <sys/types.h>
#include <sys/socketvar.h>
#include <sys/socket.h>

int sendmsg ( Socket, Message, Flags) int Socket; const struct msghdr Message [ ]; int Flags;

Description

The sendmsg subroutine sends messages through connected or unconnected sockets using the msghdr message structure. The /usr/include/sys/socket.h file contains the msghdr structure and defines the structure members. In BSD 4.4, the size and members of the msghdr message structure have been modified. Applications wanting to start the old structure need to compile with COMPAT_43 defined. The default behaviour is that of BSD 4.4.

To broadcast on a socket, the application program must first issue a setsockopt subroutine using the SO_BROADCAST option to gain broadcast permissions.

The sendmsg subroutine supports only 15 message elements.

All applications containing the sendmsg subroutine must be compiled with the _BSD macro set to a specific value. Acceptable values are 43 and 44. In addition, all socket applications must include the BSD libbsd.a library.

The sendmsg routine supports IPv6 ancillary data elements as defined in the Advanced Sockets API for IPv6.

Parameters

Item	Description
Socket	Specifies the socket descriptor.
Message	Points to the msghdr message structure containing the message to be sent.
Flags	Allows the sender to control the message transmission. The sys/socket.h file contains the Flags parameter. The Flags parameter used to send a call is formed by logically ORing one or both of the following values: MSG_OOB Processes out-of-band data on sockets that support SOCK_STREAM. Note: The following value is not for general use. It is an administrative tool used for debugging or for routing programs. MSG_DONTROUTE Sends without using routing tables. MSG_MPEG2 Indicates that this block is a MPEG2 block. It only applies to SOCK_CONN_DGRAM types of sockets only.

Item

Description

Socket

Specifies the socket descriptor.

Message

Points to the msghdr message structure containing the message to be sent.

Flags

Allows the sender to control the message transmission. The sys/socket.h file contains the Flags parameter. The Flags parameter used to send a call is formed by logically ORing one or both of the following values:

MSG_OOB: Processes out-of-band data on sockets that support SOCK_STREAM.

Note: The following value is not for general use. It is an administrative tool used for debugging or for routing programs.

MSG_DONTROUTE: Sends without using routing tables.
MSG_MPEG2: Indicates that this block is a MPEG2 block. It only applies to SOCK_CONN_DGRAM types of sockets only.

Return Values

Upon successful completion, the sendmsg subroutine returns the number of characters sent.

If the sendmsg subroutine is unsuccessful, the system handler performs the following functions:

Returns a value of -1 to the calling program.
Moves an error code, indicating the specific error, into the errno global variable.

Error Codes

The sendmsg subroutine is unsuccessful if any of the following errors occurs:

Error	Description
EACCES	Write access to the named socket is denied, or the socket trying to send a broadcast packet does not have broadcast capability.
EADDRNOTAVAIL	The specified address is not a valid address.
EAFNOSUPPORT	The specified address is not a valid address for the address family of this socket.
EBADF	The Socket parameter is not valid.
ECONNRESET	A connection was forcibly closed by a peer.
EDESTADDRREQ	The socket is not in connection-mode and does not have its peer address set.
EFAULT	The Address parameter is not in a writable part of the user address space.
EHOSTUNREACH	The destination host cannot be reached.
EINTR	A signal interrupted sendmsg before any data was transmitted.
EINVAL	The length of the msghdr structure is invalid.
EISCONN	A SOCK_DGRAM socket is already connected.
EMSGSIZE	The message is too large to be sent all at once (as the socket requires), or the msg_iovlen member of the msghdr structure pointed to by Message is less than or equal to 0 or is greater than IOV_MAX.
ENOENT	The path name does not name an existing file, or the path name is an empty string.
ENETUNREACH	The destination network is not reachable.
ENOBUFS	The system ran out of memory for an internal data structure.
ENOMEM	The available data space in memory is not large enough to hold group/ACL information.
ENOPROTOOPT	The protocol is not 64-bit supported.
ENOTCONN	The socket is in connection-mode but is not connected.
ENOTSOCK	The Socket parameter refers to a file, not a socket.
EOPNOTSUPP	The socket argument is associated with a socket that does not support one or more of the values set in flags.
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. If the socket is of type SOCK_STREAM, the SIGPIPE signal is generated to the calling process.
EWOULDBLOCK	The socket is marked nonblocking, and no connections are present to be accepted.