diff options
Diffstat (limited to 'man3p/sendto.3p')
-rw-r--r-- | man3p/sendto.3p | 239 |
1 files changed, 239 insertions, 0 deletions
diff --git a/man3p/sendto.3p b/man3p/sendto.3p new file mode 100644 index 000000000..795c8e64e --- /dev/null +++ b/man3p/sendto.3p @@ -0,0 +1,239 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SENDTO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sendto +.SH NAME +sendto \- send a message on a socket +.SH SYNOPSIS +.LP +\fB#include <sys/socket.h> +.br +.sp +ssize_t sendto(int\fP \fIsocket\fP\fB, const void *\fP\fImessage\fP\fB, +size_t\fP \fIlength\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIflags\fP\fB, const struct sockaddr *\fP\fIdest_addr\fP\fB, +.br +\ \ \ \ \ \ socklen_t\fP \fIdest_len\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIsendto\fP() function shall send a message through a connection-mode +or connectionless-mode socket. If the socket is +connectionless-mode, the message shall be sent to the address specified +by \fIdest_addr\fP. If the socket is connection-mode, +\fIdest_addr\fP shall be ignored. +.LP +The \fIsendto\fP() function takes the following arguments: +.TP 7 +\fIsocket\fP +Specifies the socket file descriptor. +.TP 7 +\fImessage\fP +Points to a buffer containing the message to be sent. +.TP 7 +\fIlength\fP +Specifies the size of the message in bytes. +.TP 7 +\fIflags\fP +Specifies the type of message transmission. Values of this argument +are formed by logically OR'ing zero or more of the +following flags: +.TP 7 +MSG_EOR +.RS +Terminates a record (if supported by the protocol). +.RE +.TP 7 +MSG_OOB +.RS +Sends out-of-band data on sockets that support out-of-band data. The +significance and semantics of out-of-band data are +protocol-specific. +.RE +.sp +.TP 7 +\fIdest_addr\fP +Points to a \fBsockaddr\fP structure containing the destination address. +The length and format of the address depend on the +address family of the socket. +.TP 7 +\fIdest_len\fP +Specifies the length of the \fBsockaddr\fP structure pointed to by +the \fIdest_addr\fP argument. +.sp +.LP +If the socket protocol supports broadcast and the specified address +is a broadcast address for the socket protocol, +\fIsendto\fP() shall fail if the SO_BROADCAST option is not set for +the socket. +.LP +The \fIdest_addr\fP argument specifies the address of the target. +The \fIlength\fP argument specifies the length of the +message. +.LP +Successful completion of a call to \fIsendto\fP() does not guarantee +delivery of the message. A return value of -1 indicates +only locally-detected errors. +.LP +If space is not available at the sending socket to hold the message +to be transmitted and the socket file descriptor does not +have O_NONBLOCK set, \fIsendto\fP() shall block until space is available. +If space is not available at the sending socket to hold +the message to be transmitted and the socket file descriptor does +have O_NONBLOCK set, \fIsendto\fP() shall fail. +.LP +The socket in use may require the process to have appropriate privileges +to use the \fIsendto\fP() function. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsendto\fP() shall return the number +of bytes sent. Otherwise, -1 shall be returned and +\fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIsendto\fP() function shall fail if: +.TP 7 +.B EAFNOSUPPORT +Addresses in the specified address family cannot be used with this +socket. +.TP 7 +.B EAGAIN \fRor\fP EWOULDBLOCK +The socket's file descriptor is marked O_NONBLOCK and the requested +operation would block. +.TP 7 +.B EBADF +The \fIsocket\fP argument is not a valid file descriptor. +.TP 7 +.B ECONNRESET +A connection was forcibly closed by a peer. +.TP 7 +.B EINTR +A signal interrupted \fIsendto\fP() before any data was transmitted. +.TP 7 +.B EMSGSIZE +The message is too large to be sent all at once, as the socket requires. +.TP 7 +.B ENOTCONN +The socket is connection-mode but is not connected. +.TP 7 +.B ENOTSOCK +The \fIsocket\fP argument does not refer to a socket. +.TP 7 +.B EOPNOTSUPP +The \fIsocket\fP argument is associated with a socket that does not +support one or more of the values set in +\fIflags\fP. +.TP 7 +.B EPIPE +The socket is shut down for writing, or the socket is connection-mode +and is no longer connected. In the latter case, and if +the socket is of type SOCK_STREAM, the SIGPIPE signal is generated +to the calling thread. +.sp +.LP +If the address family of the socket is AF_UNIX, then \fIsendto\fP() +shall fail if: +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to the file system. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +pathname in the socket address. +.TP 7 +.B ENAMETOOLONG +A component of a pathname exceeded {NAME_MAX} characters, or an entire +pathname exceeded {PATH_MAX} characters. +.TP 7 +.B ENOENT +A component of the pathname does not name an existing file or the +pathname is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix of the pathname in the socket address +is not a directory. +.sp +.LP +The \fIsendto\fP() function may fail if: +.TP 7 +.B EACCES +Search permission is denied for a component of the path prefix; or +write access to the named socket is denied. +.TP 7 +.B EDESTADDRREQ +The socket is not connection-mode and does not have its peer address +set, and no destination address was specified. +.TP 7 +.B EHOSTUNREACH +The destination host cannot be reached (probably because the host +is down or a remote router cannot reach it). +.TP 7 +.B EINVAL +The \fIdest_len\fP argument is not a valid length for the address +family. +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to the file system. +.TP 7 +.B EISCONN +A destination address was specified and the socket is already connected. +This error may or may not be returned for connection +mode sockets. +.TP 7 +.B ENETDOWN +The local network interface used to reach the destination is down. +.TP 7 +.B ENETUNREACH +No route to the network is present. +.TP 7 +.B ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP 7 +.B ENOMEM +Insufficient memory was available to fulfill the request. +.sp +.LP +If the address family of the socket is AF_UNIX, then \fIsendto\fP() +may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the pathname in the socket address. +.TP 7 +.B ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIselect\fP() and \fIpoll\fP() functions can +be used to determine when it is possible to send more data. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetsockopt\fP() , \fIpoll\fP() , \fIrecv\fP() , \fIrecvfrom\fP() +, \fIrecvmsg\fP() , \fIselect\fP() , \fIsend\fP() , \fIsendmsg\fP() +, \fIsetsockopt\fP() , \fIshutdown\fP() , \fIsocket\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<sys/socket.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |