]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1983, 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
47009d5e | 4 | .\" SPDX-License-Identifier: BSD-4-Clause-UC |
fea681da MK |
5 | .\" |
6 | .\" $Id: getsockopt.2,v 1.1 1999/05/24 14:57:04 freitag Exp $ | |
7 | .\" | |
8 | .\" Modified Sat Jul 24 16:19:32 1993 by Rik Faith (faith@cs.unc.edu) | |
9 | .\" Modified Mon Apr 22 02:29:06 1996 by Martin Schulze (joey@infodrom.north.de) | |
10 | .\" Modified Tue Aug 27 10:52:51 1996 by Andries Brouwer (aeb@cwi.nl) | |
11 | .\" Modified Thu Jan 23 13:29:34 1997 by Andries Brouwer (aeb@cwi.nl) | |
12 | .\" Modified Sun Mar 28 21:26:46 1999 by Andries Brouwer (aeb@cwi.nl) | |
c13182ef | 13 | .\" Modified 1999 by Andi Kleen <ak@muc.de>. |
35478399 | 14 | .\" Removed most stuff because it is in socket.7 now. |
fea681da | 15 | .\" |
45186a5d | 16 | .TH GETSOCKOPT 2 2021-03-22 "Linux man-pages (unreleased)" |
fea681da MK |
17 | .SH NAME |
18 | getsockopt, setsockopt \- get and set options on sockets | |
2b862269 AC |
19 | .SH LIBRARY |
20 | Standard C library | |
8fc3b2cf | 21 | .RI ( libc ", " \-lc ) |
fea681da | 22 | .SH SYNOPSIS |
521bf584 | 23 | .nf |
fea681da | 24 | .B #include <sys/socket.h> |
68e4db0a | 25 | .PP |
c4e7b714 | 26 | .BI "int getsockopt(int " sockfd ", int " level ", int " optname , |
78eb47fc | 27 | .BI " void *restrict " optval ", socklen_t *restrict " optlen ); |
c4e7b714 | 28 | .BI "int setsockopt(int " sockfd ", int " level ", int " optname , |
521bf584 MK |
29 | .BI " const void *" optval ", socklen_t " optlen ); |
30 | .fi | |
fea681da | 31 | .SH DESCRIPTION |
7145b9a9 | 32 | .BR getsockopt () |
fea681da | 33 | and |
e511ffb6 | 34 | .BR setsockopt () |
3fdfdab8 MK |
35 | manipulate options for the socket referred to by the file descriptor |
36 | .IR sockfd . | |
c13182ef | 37 | Options may exist at multiple |
fea681da | 38 | protocol levels; they are always present at the uppermost |
3fdfdab8 | 39 | socket level. |
efeece04 | 40 | .PP |
3fdfdab8 | 41 | When manipulating socket options, the level at which the |
fea681da | 42 | option resides and the name of the option must be specified. |
3fdfdab8 | 43 | To manipulate options at the sockets API level, |
fea681da MK |
44 | .I level |
45 | is specified as | |
46 | .BR SOL_SOCKET . | |
47 | To manipulate options at any | |
48 | other level the protocol number of the appropriate protocol | |
c13182ef MK |
49 | controlling the option is supplied. |
50 | For example, | |
fea681da MK |
51 | to indicate that an option is to be interpreted by the |
52 | .B TCP | |
53 | protocol, | |
54 | .I level | |
55 | should be set to the protocol number of | |
56 | .BR TCP ; | |
57 | see | |
58 | .BR getprotoent (3). | |
efeece04 | 59 | .PP |
c4bb193f | 60 | The arguments |
fea681da MK |
61 | .I optval |
62 | and | |
63 | .I optlen | |
64 | are used to access option values for | |
e511ffb6 | 65 | .BR setsockopt (). |
fea681da | 66 | For |
e511ffb6 | 67 | .BR getsockopt () |
fea681da | 68 | they identify a buffer in which the value for the |
c13182ef MK |
69 | requested option(s) are to be returned. |
70 | For | |
e511ffb6 | 71 | .BR getsockopt (), |
fea681da | 72 | .I optlen |
c4bb193f | 73 | is a value-result argument, initially containing the |
fea681da MK |
74 | size of the buffer pointed to by |
75 | .IR optval , | |
76 | and modified on return to indicate the actual size of | |
c13182ef MK |
77 | the value returned. |
78 | If no option value is to be supplied or returned, | |
fea681da MK |
79 | .I optval |
80 | may be NULL. | |
efeece04 | 81 | .PP |
fea681da MK |
82 | .I Optname |
83 | and any specified options are passed uninterpreted to the appropriate | |
c13182ef MK |
84 | protocol module for interpretation. |
85 | The include file | |
fea681da | 86 | .I <sys/socket.h> |
c13182ef MK |
87 | contains definitions for socket level options, described below. |
88 | Options at | |
fea681da MK |
89 | other protocol levels vary in format and name; consult the appropriate |
90 | entries in section 4 of the manual. | |
efeece04 | 91 | .PP |
fea681da MK |
92 | Most socket-level options utilize an |
93 | .I int | |
c4bb193f | 94 | argument for |
fea681da MK |
95 | .IR optval . |
96 | For | |
e511ffb6 | 97 | .BR setsockopt (), |
c7094399 | 98 | the argument should be nonzero to enable a boolean option, or zero if the |
fea681da | 99 | option is to be disabled. |
fea681da MK |
100 | .PP |
101 | For a description of the available socket options see | |
102 | .BR socket (7) | |
103 | and the appropriate protocol man pages. | |
47297adb | 104 | .SH RETURN VALUE |
f8b553ce | 105 | On success, zero is returned for the standard options. |
c13182ef | 106 | On error, \-1 is returned, and |
fea681da | 107 | .I errno |
f6a4078b | 108 | is set to indicate the error. |
efeece04 | 109 | .PP |
f8b553ce MK |
110 | Netfilter allows the programmer |
111 | to define custom socket options with associated handlers; for such | |
112 | options, the return value on success is the value returned by the handler. | |
fea681da | 113 | .SH ERRORS |
0019177e | 114 | .TP |
fea681da MK |
115 | .B EBADF |
116 | The argument | |
3e4088f4 | 117 | .I sockfd |
d9cb0d7d | 118 | is not a valid file descriptor. |
fea681da MK |
119 | .TP |
120 | .B EFAULT | |
c13182ef | 121 | The address pointed to by |
fea681da | 122 | .I optval |
c13182ef MK |
123 | is not in a valid part of the process address space. |
124 | For | |
e511ffb6 | 125 | .BR getsockopt (), |
fea681da MK |
126 | this error may also be returned if |
127 | .I optlen | |
128 | is not in a valid part of the process address space. | |
129 | .TP | |
130 | .B EINVAL | |
131 | .I optlen | |
c13182ef | 132 | invalid in |
1e321034 | 133 | .BR setsockopt (). |
71b2fb38 | 134 | In some cases this error can also occur for an invalid value in |
1ae6b2c7 | 135 | .I optval |
71b2fb38 MK |
136 | (e.g., for the |
137 | .B IP_ADD_MEMBERSHIP | |
138 | option described in | |
139 | .BR ip (7)). | |
fea681da MK |
140 | .TP |
141 | .B ENOPROTOOPT | |
142 | The option is unknown at the level indicated. | |
143 | .TP | |
144 | .B ENOTSOCK | |
deedfd97 | 145 | The file descriptor |
3e4088f4 | 146 | .I sockfd |
deedfd97 | 147 | does not refer to a socket. |
3113c7f3 | 148 | .SH STANDARDS |
fbe37c48 MK |
149 | POSIX.1-2001, POSIX.1-2008, |
150 | SVr4, 4.4BSD (these system calls first appeared in 4.2BSD). | |
97c1eac8 | 151 | .\" SVr4 documents additional ENOMEM and ENOSR error codes, but does |
c13182ef | 152 | .\" not document the |
97c1eac8 MK |
153 | .\" .BR SO_SNDLOWAT ", " SO_RCVLOWAT ", " SO_SNDTIMEO ", " SO_RCVTIMEO |
154 | .\" options | |
19c98696 | 155 | .SH NOTES |
ec5df7af MK |
156 | For background on the |
157 | .I socklen_t | |
158 | type, see | |
fea681da MK |
159 | .BR accept (2). |
160 | .SH BUGS | |
161 | Several of the socket options should be handled at lower levels of the | |
162 | system. | |
47297adb | 163 | .SH SEE ALSO |
fea681da MK |
164 | .BR ioctl (2), |
165 | .BR socket (2), | |
166 | .BR getprotoent (3), | |
167 | .BR protocols (5), | |
423bd344 | 168 | .BR ip (7), |
49f7fca5 | 169 | .BR packet (7), |
fea681da MK |
170 | .BR socket (7), |
171 | .BR tcp (7), | |
423bd344 | 172 | .BR udp (7), |
fea681da | 173 | .BR unix (7) |