sendto()

Description

Send data to a specific destination.

#include <winsock.h>

int PASCAL FAR sendto ( SOCKET s, const char FAR * buf, int len, int flags, const struct sockaddr FAR * to, int tolen);

s

A descriptor identifying a socket.
buf
A buffer containing the data to be transmitted.
len
The length of the data in buf.
flags
Specifies the way in which the call is made.
to
A optional pointer to the address of the target socket.
tolen
The size of the address in to.

Remarks

sendto() is used on datagram or stream sockets and is used to write outgoing data on a socket. For datagram sockets, care must be taken not to exceed the maximum IP packet size of the underlying subnets, which is given by the iMaxUdpDg element in the WSAData structure returned by WSAStartup(). If the data is too long to pass atomically through the underlying protocol the error WSAEMSGSIZE is returned, and no data is transmitted. Note that the successful completion of a sendto() does not indicate that the data was successfully delivered.

sendto() is normally used on a SOCK_DGRAM socket to send a datagram to a specific peer socket identified by the to parameter. On a SOCK_STREAM socket, the to and tolen parameters are ignored; in this case the sendto() is equivalent to send().

To send a broadcast (on a SOCK_DGRAM only), the address in the to parameter should be constructed using the special IP address INADDR_BROADCAST (defined in winsock.h) together with the intended port number. It is generally inadvisable for a broadcast datagram to exceed the size at which fragmentation may occur, which implies that the data portion of the datagram (excluding headers) should not exceed 512 bytes.

If no buffer space is available within the transport system to hold the data to be transmitted, sendto() will block unless the socket has been placed in a non-blocking I/O mode. On non-blocking SOCK_STREAM sockets, the number of bytes written may be between 1 and the requested length, depending on buffer availability on both the local and foreign hosts. The select() call may be used to determine when it is possible to send more data.

Flags may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the flags parameter. The latter is constructed by or-ing any of the following values:

MSG_DONTROUTE

Specifies that the data should not be subject to routing. A Windows Sockets supplier may choose to ignore this flag; see also the discussion of the SO_DONTROUTE option in Socket Options.
MSG_OOB
Send out-of-band data (SOCK_STREAM only; see also Out of Band Data)

Return Value

If no error occurs, sendto() returns the total number of characters sent. (Note that this may be less than the number indicated by len.) Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

WSANOTINITIALISED

A successful WSAStartup() must occur before using this API.
WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEACCES
The requested address is a broadcast address, but the appropriate flag was not set.
WSAEINTR
The (blocking) call was canceled via WSACancelBlockingCall()
WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.
WSAEFAULT
The buf or to are not in a valid part of the user address space, or the to argument is too small (less than the sizeof a struct sockaddr).
WSAENETRESET
The connection must be reset because the Windows Sockets implementation dropped it.
WSAENOBUFS
The Windows Sockets implementation reports a buffer deadlock.
WSAENOTCONN
The socket is not connected (SOCK_STREAM only).
WSAENOTSOCK
The descriptor is not a socket.
WSAEOPNOTSUPP
MSG_OOB was specified, but the socket is not of type SOCK_STREAM.
WSAESHUTDOWN
The socket has been shutdown; it is not possible to sendto() on a socket after shutdown() has been invoked with how set to 1 or 2.
WSAEWOULDBLOCK
The socket is marked as non-blocking and the requested operation would block.
WSAEMSGSIZE
The socket is of type SOCK_DGRAM, and the datagram is larger than the maximum supported by the Windows Sockets implementation.
WSAECONNABORTED
The virtual circuit was aborted due to timeout or other failure.
WSAECONNRESET
The virtual circuit was reset by the remote side.
WSAEADDRNOTAVAIL
The specified address is not available from the local machine.
WSAEAFNOSUPPORT
Addresses in the specified family cannot be used with this socket.
WSAEDESTADDRREQ
A destination address is required.
WSAENETUNREACH
The network can't be reached from this host at this time.

See Also

recv(), recvfrom(), socket(), send(), WSAStartup()

---

[Back: send()]
[Next: setsockopt()]