| .\" Copyright (c) 1983, 1991 The Regents of the University of California. |
| .\" All rights reserved. |
| .\" |
| .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions |
| .\" are met: |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in the |
| .\" documentation and/or other materials provided with the distribution. |
| .\" 3. All advertising materials mentioning features or use of this software |
| .\" must display the following acknowledgement: |
| .\" This product includes software developed by the University of |
| .\" California, Berkeley and its contributors. |
| .\" 4. Neither the name of the University nor the names of its contributors |
| .\" may be used to endorse or promote products derived from this software |
| .\" without specific prior written permission. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
| .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| .\" SUCH DAMAGE. |
| .\" %%%LICENSE_END |
| .\" |
| .\" $Id: getsockopt.2,v 1.1 1999/05/24 14:57:04 freitag Exp $ |
| .\" |
| .\" Modified Sat Jul 24 16:19:32 1993 by Rik Faith (faith@cs.unc.edu) |
| .\" Modified Mon Apr 22 02:29:06 1996 by Martin Schulze (joey@infodrom.north.de) |
| .\" Modified Tue Aug 27 10:52:51 1996 by Andries Brouwer (aeb@cwi.nl) |
| .\" Modified Thu Jan 23 13:29:34 1997 by Andries Brouwer (aeb@cwi.nl) |
| .\" Modified Sun Mar 28 21:26:46 1999 by Andries Brouwer (aeb@cwi.nl) |
| .\" Modified 1999 by Andi Kleen <ak@muc.de>. |
| .\" Removed most stuff because it is in socket.7 now. |
| .\" |
| .TH GETSOCKOPT 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| getsockopt, setsockopt \- get and set options on sockets |
| .SH SYNOPSIS |
| .nf |
| .BR "#include <sys/types.h>" " /* See NOTES */" |
| .B #include <sys/socket.h> |
| .PP |
| .BI "int getsockopt(int " sockfd ", int " level ", int " optname , |
| .BI " void *" optval ", socklen_t *" optlen ); |
| .BI "int setsockopt(int " sockfd ", int " level ", int " optname , |
| .BI " const void *" optval ", socklen_t " optlen ); |
| .fi |
| .SH DESCRIPTION |
| .BR getsockopt () |
| and |
| .BR setsockopt () |
| manipulate options for the socket referred to by the file descriptor |
| .IR sockfd . |
| Options may exist at multiple |
| protocol levels; they are always present at the uppermost |
| socket level. |
| .PP |
| When manipulating socket options, the level at which the |
| option resides and the name of the option must be specified. |
| To manipulate options at the sockets API level, |
| .I level |
| is specified as |
| .BR SOL_SOCKET . |
| To manipulate options at any |
| other level the protocol number of the appropriate protocol |
| controlling the option is supplied. |
| For example, |
| to indicate that an option is to be interpreted by the |
| .B TCP |
| protocol, |
| .I level |
| should be set to the protocol number of |
| .BR TCP ; |
| see |
| .BR getprotoent (3). |
| .PP |
| The arguments |
| .I optval |
| and |
| .I optlen |
| are used to access option values for |
| .BR setsockopt (). |
| For |
| .BR getsockopt () |
| they identify a buffer in which the value for the |
| requested option(s) are to be returned. |
| For |
| .BR getsockopt (), |
| .I optlen |
| is a value-result argument, initially containing the |
| size of the buffer pointed to by |
| .IR optval , |
| and modified on return to indicate the actual size of |
| the value returned. |
| If no option value is to be supplied or returned, |
| .I optval |
| may be NULL. |
| .PP |
| .I Optname |
| and any specified options are passed uninterpreted to the appropriate |
| protocol module for interpretation. |
| The include file |
| .I <sys/socket.h> |
| contains definitions for socket level options, described below. |
| Options at |
| other protocol levels vary in format and name; consult the appropriate |
| entries in section 4 of the manual. |
| .PP |
| Most socket-level options utilize an |
| .I int |
| argument for |
| .IR optval . |
| For |
| .BR setsockopt (), |
| the argument should be nonzero to enable a boolean option, or zero if the |
| option is to be disabled. |
| .PP |
| For a description of the available socket options see |
| .BR socket (7) |
| and the appropriate protocol man pages. |
| .SH RETURN VALUE |
| On success, zero is returned for the standard options. |
| On error, \-1 is returned, and |
| .I errno |
| is set appropriately. |
| .PP |
| Netfilter allows the programmer |
| to define custom socket options with associated handlers; for such |
| options, the return value on success is the value returned by the handler. |
| .SH ERRORS |
| .TP 10 |
| .B EBADF |
| The argument |
| .I sockfd |
| is not a valid file descriptor. |
| .TP |
| .B EFAULT |
| The address pointed to by |
| .I optval |
| is not in a valid part of the process address space. |
| For |
| .BR getsockopt (), |
| this error may also be returned if |
| .I optlen |
| is not in a valid part of the process address space. |
| .TP |
| .B EINVAL |
| .I optlen |
| invalid in |
| .BR setsockopt (). |
| In some cases this error can also occur for an invalid value in |
| .IR optval |
| (e.g., for the |
| .B IP_ADD_MEMBERSHIP |
| option described in |
| .BR ip (7)). |
| .TP |
| .B ENOPROTOOPT |
| The option is unknown at the level indicated. |
| .TP |
| .B ENOTSOCK |
| The file descriptor |
| .I sockfd |
| does not refer to a socket. |
| .SH CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008, |
| SVr4, 4.4BSD (these system calls first appeared in 4.2BSD). |
| .\" SVr4 documents additional ENOMEM and ENOSR error codes, but does |
| .\" not document the |
| .\" .BR SO_SNDLOWAT ", " SO_RCVLOWAT ", " SO_SNDTIMEO ", " SO_RCVTIMEO |
| .\" options |
| .SH NOTES |
| POSIX.1 does not require the inclusion of |
| .IR <sys/types.h> , |
| and this header file is not required on Linux. |
| However, some historical (BSD) implementations required this header |
| file, and portable applications are probably wise to include it. |
| .PP |
| For background on the |
| .I socklen_t |
| type, see |
| .BR accept (2). |
| .SH BUGS |
| Several of the socket options should be handled at lower levels of the |
| system. |
| .SH SEE ALSO |
| .BR ioctl (2), |
| .BR socket (2), |
| .BR getprotoent (3), |
| .BR protocols (5), |
| .BR ip (7), |
| .BR packet (7), |
| .BR socket (7), |
| .BR tcp (7), |
| .BR udp (7), |
| .BR unix (7) |