sendto()--Send Data
BSD 4.3 Syntax
#include <sys/types.h> #include <sys/socket.h> int sendto(int socket_descriptor, char *buffer, int buffer_length, int flags, struct sockaddr *destination_address, int address_length)
Service Program Name: QSOSRV1
Default Public Authority: *USE
Threadsafe: Yes
UNIX® 98 Compatible Syntax
#define _XOPEN_SOURCE 520 #include <sys/socket.h> ssize_t sendto(int socket_descriptor, const void *buffer, size_t buffer_length, int flags, const struct sockaddr *destination_address, socklen_t address_length)
Service Program Name: QSOSRV1
Default Public Authority: *USE
Threadsafe: Yes
The sendto() function is used to send data through a connected or unconnected socket.
There are two versions of the API, as shown above. The base IBM® i API uses BSD 4.3 structures and syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro.
Parameters
- socket_descriptor
- (Input) The socket descriptor that is to be written to.
- buffer
- (Input) The pointer to the buffer in which the data that is to be written
is stored.
- buffer_length
- (Input) The length of the buffer.
- flags
- (Input) A flag value that controls the transmission of the data. The
flags value is either zero, or is obtained by performing an OR
operation on one or more of the following constants:
MSG_EOR Terminate a record, if supported by the protocol.
MSG_OOB Send data as out-of-band data. Valid only for sockets with an address family of AF_INET or AF_INET6 and type SOCK_STREAM.
MSG_DONTROUTE Bypass routing. Valid only for sockets with address family of AF_INET or AF_INET6. It is ignored for other address families.
- destination_address
- (Input) A pointer to a buffer of type struct sockaddr that
contains the destination address to which the data is to be sent. The structure
sockaddr is defined in <sys/socket.h>.
The BSD 4.3 structure is:
struct sockaddr { u_short sa_family; char sa_data[14]; };
The BSD 4.4/UNIX 98 compatible structure is:
typedef uchar sa_family_t; struct sockaddr { uint8_t sa_len; sa_family_t sa_family; char sa_data[14]; };
The BSD 4.4 sa_len field is the length of the address. The sa_family field identifies the address family to which the address belongs, and sa_data is the address whose format is dependent on the address family.
- address_length
- (Input) The length of the destination_address.
Authorities
When the address family of the socket identified by the socket_descriptor is AF_INET and is running IP over SNA, the thread must have retrieve, insert, delete, and update authority to the APPC device. When the thread does not have this level of authority, an errno of EACCES is returned.
Return Value
sendto() returns an integer. Possible values are:
- -1 (unsuccessful)
- n (successful), where n is the number of bytes sent.
Error Conditions
When sendto() fails, errno can be set to one of the following:
[EACCES] | Permission denied.
The process does not have the appropriate privileges to the destination address. |
[EADDRNOTAVAIL] | Address not available.
A socket with an address family of AF_INET or AF_INET6, is using a connectionless transport service, and the socket was not bound. The system tried to bind the socket but could not because a port was not available. |
[EBADF] | Descriptor not valid. |
[ECONNREFUSED] | The destination socket refused an attempted
connect operation.
This error code can only be returned on sockets that use a connectionless transport service. |
[EDESTADDRREQ] | Operation requires destination address.
A destination address has not been associated with the socket pointed to by the socket_descriptor parameter and a destination address was not passed in as an argument on the sendto(). This error code can only be returned on sockets that use a connectionless transport service. |
[EFAULT] | Bad address.
The system detected an address which was not valid while attempting to access the buffer or destination_address parameter. |
[EHOSTDOWN] | A remote host is not available.
This error code can only be returned on sockets that use a connectionless transport service. |
[EHOSTUNREACH] | A route to the remote host is not available.
This error code can only be returned on sockets that use a connectionless transport service. |
[EINTR] | Interrupted function call. |
[EINVAL] | Parameter not valid.
This error code indicates one of the following:
|
[EIO] | Input/output error. |
[EISCONN] | A connection has already been established.
A destination address was set, but the socket pointed to by the socket_descriptor parameter already has a destination address associated with it. |
[ELOOP] | A loop exists in symbolic links encountered
during pathname resolution.
This error code refers to the destination address, and can only be returned on sockets that use the AF_UNIX or AF_UNIX_CCSID address family. |
[EMSGSIZE] | Message size out of range.
The data to be sent could not be sent atomically because the total size of the data to be sent is too large. |
[ENAMETOOLONG] | File name too long.
This error code refers to the destination address, and can only be returned on sockets that use the AF_UNIX or AF_UNIX_CCSID address family. |
[ENETDOWN] | The network is not currently available.
This error code can only be returned on sockets that use a connectionless transport service. |
[ENETUNREACH] | Cannot reach the destination network.
This error code can only be returned on sockets that use a connectionless transport service. |
[ENOBUFS] | There is not enough buffer space for the
requested operation. |
[ENOENT] | No such file or directory.
This error code refers to the destination address, and can only be returned on sockets that use the AF_UNIX or AF_UNIX_CCSID address family. |
[ENOSYS] | Function not implemented.
This error code refers to the destination address, and can only be returned on sockets that use the AF_UNIX or AF_UNIX_CCSID address family. |
[ENOTCONN] | Requested operation requires a connection.
This error code can only be returned on sockets that use a connection-oriented transport service. |
[ENOTDIR] | Not a directory.
This error code refers to the destination address, and can only be returned on sockets that use the AF_UNIX or AF_UNIX_CCSID address family. |
[ENOTSOCK] | The specified descriptor does not reference a
socket. |
[EOPNOTSUPP] | Operation not supported.
This error code indicates one of the following:
|
[EPIPE] | Broken pipe. |
[EPROTOTYPE] | The socket type or protocols are not compatible.
This error code is only returned on sockets that use the AF_UNIX or the AF_UNIX_CCSID address family. |
[EUNATCH] | The protocol required to support the specified
address family is not available at this time. |
[EUNKNOWN] | Unknown system state. |
[EWOULDBLOCK] | Operation would have caused the thread to be
suspended. |
Error Messages
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
CPFA081 E | Unable to set return value or error code. |
Usage Notes
- A destination address cannot be specified if the socket pointed to by the
socket_descriptor parameter already has a destination address
associated with it. To not specify an address, users must set
the destination_address field to NULL or set the
address_length field to zero. (Not specifying an address by setting
the address_length field to zero is an IBM® extension.)
Note: The destination_address and address_length fields are ignored if the socket is using a connection-oriented transport service.
- If the socket is using a connectionless transport device, the socket is not
bound to an address, and the socket type is SOCK_DGRAM, the system
automatically selects an address (INADDR_ANY or in6addr_any and an available port number) and binds it to the socket
before sending the data. The IPV6_ADDR_PREFERECES socket option flags
set on setsockopt() will be taken into consideration when selecting
the source address on which to send the outgoing data.
- To broadcast on an AF_INET socket, the socket option
SO_BROADCAST must be set (with a setsockopt()).
- When using a connection-oriented transport service, all errors except
[EUNATCH] and [EUNKNOWN] are mapped to
[EPIPE] on an output operation when either of the following
occurs:
- A connection that is in progress is unsuccessful.
- An established connection is broken.
To get the actual error, use getsockopt() with the SO_ERROR option, or perform an input operation (for example, read()).
- If the socket is using an address family of AF_UNIX, the
destination address (which is a path name) is assumed to be in the default
coded character set identifier (CCSID) currently in effect for the job. For
AF_UNIX_CCSID, the destination address is assumed to be in the
format and coded character set identifier (CCSID) specified in the
sockaddr_unc.
- When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to the value 520 or greater, the sendto() API is mapped to qso_sendto98().
Related Information
- _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98
compatible interface
- fcntl()--Perform File Control Command
- ioctl()--Perform I/O Control Request
- send()--Send Data
- sendmsg()--Send Data or Descriptors or Both
API introduced: V3R1