SOSendTo

Syntax

#include <cafe.h>
#include <cafe/network.h>

int SOSendTo(
             int                    fd, 
             const void            *buffer, 
             int                    len, 
             int                    flags,
             const struct sockaddr *dest_addr, 
             int                    dest_len
            );

Parameters

fd Descriptor of the sending socket.
buffer The message to send.
len Length of the message, in bytes. For UDP sockets, len greater than 1478 will cause an SO_EMSGSIZE error.
flags Bitwise OR of the following values:
  • MSG_OOB........Send data out of band.
  • MSG_DONTROUTE..Don't use a gateway to send the packet.
  • MSG_DONTWAIT...Enable non-blocking operation.
dest_addr Address of the target.
dest_len Length of the destination address in bytes.

Return Values

int, upon success, returns the number of characters sent. Upon failure, returns -1 and errno is set appropriately.

Errors

These are errors generated by the socket layer; additional errors may be generated by the underlying protocol modules. See SOLastError.

SO_EBUSY The socket resource manager is busy and cannot process requests. Try again later.
SO_EINVAL One of the specified arguments is invalid (e.g., dest_addr is NULL, len is a negative value, dest_len is not in the valid range, etc.).
SO_EABORTED The operation was aborted. When a socket is closed, operations that are blocked on the socket are aborted.
SO_EUNKNOWN An unknown error occurred for some reason. Should be treated as a serious error and the corresponding socket should be closed.
SO_ELIBNOTREADY Socket library is not initialized.
SO_ENOMEM Indicates insufficient memory in the network stack. Usually a transient condition and the operation can be retried after a few seconds. If it occurs repeatedly should be treated as a serious error and the corresponding socket should be closed.
SO_ENOTSOCK The argument fd does not refer to a socket.
SO_EMSGSIZE The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. For UDP sockets, len greater than 1478 will cause this error.
SO_EWOULDBLOCK The socket is marked non-blocking and the requested operation would block.
SO_EPIPE The socket is unable to send any more data. This typically indicates that the socket is not connected.
SO_ENOTCONN The socket is associated with a connection-oriented protocol and has not been connected (see SOConnect and SOAccept ).
SO_ENOBUFS Indicates insufficient packet buffers in the network stack. Usually a transient condition and the operation can be retried after a few seconds. If it occurs repeatedly should be treated as a serious error and the corresponding socket should be closed.
SO_ECONNREFUSED The socket received an ICMP destination unreachable message from the last message sent. This typically indicates that the receiver is not listening on the remote port.
SO_EADDRNOTAVAIL Returned only for UDP sends to broadcast address when network interface is not UP. Should be treated as a serious error and the corresponding socket should be closed.
SO_ENETUNREACH The specified destination is unreachable.
SO_EFAULT An abnormal operation occurred in the stack. The corresponding socket should be closed for this type of serious error.
SO_EIEIO An error occurred in the network card driver while sending out the packet. Returned only for UDP sockets. Usually a transient condition and the operation can be retried after a few seconds. If it occurs repeatedly should be treated as a serious error and the corresponding socket should be closed.
SO_ERANGEINVALID An unknown error occurred for some reason in the stack. Should be treated as a serious error and the corresponding socket should be closed.
SO_EAPIERROR An error occurred when processing the request in the stack. Should be treated as a serious error and the corresponding socket should be closed.

Description

Sends a message on a socket. No indication of failure to deliver is implicit in SOSendTo. Only locally detected errors are indicated by a return value of -1 and errno set to the error code.

If no message space is available at the socket to hold the message to be transmitted, then SOSendTo normally blocks, unless the socket is a non-blocking socket or the MSG_DONTWAIT flag is turned on.

The flag MSG_OOB is used to send "out-of-band" data on sockets that support this notion (e.g. SOCK_STREAM); the underlying protocol must also support "out-of-band" data. MSG_DONTROUTE is usually used only by diagnostic or routing programs.

Do Not Call From

Callbacks Do not call this function from any callback function.
Interrupt handler Do not call this function from any interrupt handler.
Exception handler Do not call this function from any exception handler.

See Also

SORecvFrom

Revision History

2013/11/08 Removed SO_EDESTADDRREQ.
2013/05/09 Updated Errors (SO_EUNKNOWN, SO_EDESTADDRREQ, SO_EADDRNOTAVAIL, SO_EIEIO, SO_ERANGEINVALID and SO_EAPIERROR were added).
2012/10/09 Updated Errors section.
2012/08/16 Cleanup pass.
2011/07/11 Added Errors section.
2011/02/21 Initial version.


CONFIDENTIAL