diff options
Diffstat (limited to 'man3p/setsockopt.3p')
| -rw-r--r-- | man3p/setsockopt.3p | 225 |
1 files changed, 225 insertions, 0 deletions
diff --git a/man3p/setsockopt.3p b/man3p/setsockopt.3p new file mode 100644 index 000000000..a37d470a2 --- /dev/null +++ b/man3p/setsockopt.3p @@ -0,0 +1,225 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETSOCKOPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" setsockopt +.SH NAME +setsockopt \- set the socket options +.SH SYNOPSIS +.LP +\fB#include <sys/socket.h> +.br +.sp +int setsockopt(int\fP \fIsocket\fP\fB, int\fP \fIlevel\fP\fB, int\fP +\fIoption_name\fP\fB, +.br +\ \ \ \ \ \ const void *\fP\fIoption_value\fP\fB, socklen_t\fP \fIoption_len\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIsetsockopt\fP() function shall set the option specified by +the \fIoption_name\fP argument, at the protocol level +specified by the \fIlevel\fP argument, to the value pointed to by +the \fIoption_value\fP argument for the socket associated with +the file descriptor specified by the \fIsocket\fP argument. +.LP +The \fIlevel\fP argument specifies the protocol level at which the +option resides. To set options at the socket level, specify +the \fIlevel\fP argument as SOL_SOCKET. To set options at other levels, +supply the appropriate \fIlevel\fP identifier for the +protocol controlling the option. For example, to indicate that an +option is interpreted by the TCP (Transport Control Protocol), +set \fIlevel\fP to IPPROTO_TCP as defined in the \fI<netinet/in.h>\fP +header. +.LP +The \fIoption_name\fP argument specifies a single option to set. The +\fIoption_name\fP argument and any specified options are +passed uninterpreted to the appropriate protocol module for interpretations. +The \fI<sys/socket.h>\fP header defines the socket-level options. +The options are as +follows: +.TP 7 +SO_DEBUG +Turns on recording of debugging information. This option enables or +disables debugging in the underlying protocol modules. This +option takes an \fBint\fP value. This is a Boolean option. +.TP 7 +SO_BROADCAST +Permits sending of broadcast messages, if this is supported by the +protocol. This option takes an \fBint\fP value. This is a +Boolean option. +.TP 7 +SO_REUSEADDR +Specifies that the rules used in validating addresses supplied to +\fIbind\fP() should +allow reuse of local addresses, if this is supported by the protocol. +This option takes an \fBint\fP value. This is a Boolean +option. +.TP 7 +SO_KEEPALIVE +Keeps connections active by enabling the periodic transmission of +messages, if this is supported by the protocol. This option +takes an \fBint\fP value. +.LP +If the connected socket fails to respond to these messages, the connection +is broken and threads writing to that socket are +notified with a SIGPIPE signal. This is a Boolean option. +.TP 7 +SO_LINGER +Lingers on a \fIclose\fP() if data is present. This option controls +the action taken +when unsent messages queue on a socket and \fIclose\fP() is performed. +If SO_LINGER is set, +the system shall block the process during \fIclose\fP() until it can +transmit the data or +until the time expires. If SO_LINGER is not specified, and \fIclose\fP() +is issued, the +system handles the call in a way that allows the process to continue +as quickly as possible. This option takes a \fBlinger\fP +structure, as defined in the \fI<sys/socket.h>\fP header, to specify +the state +of the option and linger interval. +.TP 7 +SO_OOBINLINE +Leaves received out-of-band data (data marked urgent) inline. This +option takes an \fBint\fP value. This is a Boolean +option. +.TP 7 +SO_SNDBUF +Sets send buffer size. This option takes an \fBint\fP value. +.TP 7 +SO_RCVBUF +Sets receive buffer size. This option takes an \fBint\fP value. +.TP 7 +SO_DONTROUTE +Requests that outgoing messages bypass the standard routing facilities. +The destination shall be on a directly-connected +network, and messages are directed to the appropriate network interface +according to the destination address. The effect, if any, +of this option depends on what protocol is in use. This option takes +an \fBint\fP value. This is a Boolean option. +.TP 7 +SO_RCVLOWAT +Sets the minimum number of bytes to process for socket input operations. +The default value for SO_RCVLOWAT is 1. If SO_RCVLOWAT +is set to a larger value, blocking receive calls normally wait until +they have received the smaller of the low water mark value or +the requested amount. (They may return less than the low water mark +if an error occurs, a signal is caught, or the type of data +next in the receive queue is different from that returned; for example, +out-of-band data.) This option takes an \fBint\fP value. +Note that not all implementations allow this option to be set. +.TP 7 +SO_RCVTIMEO +Sets the timeout value that specifies the maximum amount of time an +input function waits until it completes. It accepts a +\fBtimeval\fP structure with the number of seconds and microseconds +specifying the limit on how long to wait for an input +operation to complete. If a receive operation has blocked for this +much time without receiving additional data, it shall return +with a partial count or \fIerrno\fP set to [EAGAIN] or [EWOULDBLOCK] +if no data is received. The default for this option is zero, +which indicates that a receive operation shall not time out. This +option takes a \fBtimeval\fP structure. Note that not all +implementations allow this option to be set. +.TP 7 +SO_SNDLOWAT +Sets the minimum number of bytes to process for socket output operations. +Non-blocking output operations shall process no data +if flow control does not allow the smaller of the send low water mark +value or the entire request to be processed. This option +takes an \fBint\fP value. Note that not all implementations allow +this option to be set. +.TP 7 +SO_SNDTIMEO +Sets the timeout value specifying the amount of time that an output +function blocks because flow control prevents data from +being sent. If a send operation has blocked for this time, it shall +return with a partial count or with \fIerrno\fP set to +[EAGAIN] or [EWOULDBLOCK] if no data is sent. The default for this +option is zero, which indicates that a send operation shall not +time out. This option stores a \fBtimeval\fP structure. Note that +not all implementations allow this option to be set. +.sp +.LP +For Boolean options, 0 indicates that the option is disabled and 1 +indicates that the option is enabled. +.LP +Options at other protocol levels vary in format and name. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsetsockopt\fP() shall return 0. Otherwise, +-1 shall be returned and \fIerrno\fP set to indicate +the error. +.SH ERRORS +.LP +The \fIsetsockopt\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIsocket\fP argument is not a valid file descriptor. +.TP 7 +.B EDOM +The send and receive timeout values are too big to fit into the timeout +fields in the socket structure. +.TP 7 +.B EINVAL +The specified option is invalid at the specified socket level or the +socket has been shut down. +.TP 7 +.B EISCONN +The socket is already connected, and a specified option cannot be +set while the socket is connected. +.TP 7 +.B ENOPROTOOPT +.sp +The option is not supported by the protocol. +.TP 7 +.B ENOTSOCK +The \fIsocket\fP argument does not refer to a socket. +.sp +.LP +The \fIsetsockopt\fP() function may fail if: +.TP 7 +.B ENOMEM +There was insufficient memory available for the operation to complete. +.TP 7 +.B ENOBUFS +Insufficient resources are available in the system to complete the +call. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIsetsockopt\fP() function provides an application program with +the means to control socket behavior. An application +program can use \fIsetsockopt\fP() to allocate buffer space, control +timeouts, or permit socket data broadcasts. The \fI<sys/socket.h>\fP +header defines the socket-level options available to +\fIsetsockopt\fP(). +.LP +Options may exist at multiple protocol levels. The SO_ options are +always present at the uppermost socket level. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISockets\fP , \fIbind\fP() , \fIendprotoent\fP() , \fIgetsockopt\fP() +, \fIsocket\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI<netinet/in.h>\fP, \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 . |