]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1983, 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
a9cd9cb7 | 4 | .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
fea681da MK |
5 | .\" Redistribution and use in source and binary forms, with or without |
6 | .\" modification, are permitted provided that the following conditions | |
7 | .\" are met: | |
8 | .\" 1. Redistributions of source code must retain the above copyright | |
9 | .\" notice, this list of conditions and the following disclaimer. | |
10 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer in the | |
12 | .\" documentation and/or other materials provided with the distribution. | |
13 | .\" 3. All advertising materials mentioning features or use of this software | |
14 | .\" must display the following acknowledgement: | |
15 | .\" This product includes software developed by the University of | |
16 | .\" California, Berkeley and its contributors. | |
17 | .\" 4. Neither the name of the University nor the names of its contributors | |
18 | .\" may be used to endorse or promote products derived from this software | |
19 | .\" without specific prior written permission. | |
20 | .\" | |
21 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
22 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
23 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
24 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
25 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
26 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
27 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
28 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
29 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
30 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
31 | .\" SUCH DAMAGE. | |
8c9302dc | 32 | .\" %%%LICENSE_END |
fea681da MK |
33 | .\" |
34 | .\" $Id: getsockopt.2,v 1.1 1999/05/24 14:57:04 freitag Exp $ | |
35 | .\" | |
36 | .\" Modified Sat Jul 24 16:19:32 1993 by Rik Faith (faith@cs.unc.edu) | |
37 | .\" Modified Mon Apr 22 02:29:06 1996 by Martin Schulze (joey@infodrom.north.de) | |
38 | .\" Modified Tue Aug 27 10:52:51 1996 by Andries Brouwer (aeb@cwi.nl) | |
39 | .\" Modified Thu Jan 23 13:29:34 1997 by Andries Brouwer (aeb@cwi.nl) | |
40 | .\" Modified Sun Mar 28 21:26:46 1999 by Andries Brouwer (aeb@cwi.nl) | |
c13182ef | 41 | .\" Modified 1999 by Andi Kleen <ak@muc.de>. |
35478399 | 42 | .\" Removed most stuff because it is in socket.7 now. |
fea681da | 43 | .\" |
c4e7b714 | 44 | .TH GETSOCKOPT 2 2008-12-03 "Linux" "Linux Programmer's Manual" |
fea681da MK |
45 | .SH NAME |
46 | getsockopt, setsockopt \- get and set options on sockets | |
47 | .SH SYNOPSIS | |
521bf584 | 48 | .nf |
53a6b01d | 49 | .BR "#include <sys/types.h>" " /* See NOTES */" |
fea681da MK |
50 | .br |
51 | .B #include <sys/socket.h> | |
521bf584 | 52 | .sp |
c4e7b714 | 53 | .BI "int getsockopt(int " sockfd ", int " level ", int " optname , |
521bf584 | 54 | .BI " void *" optval ", socklen_t *" optlen ); |
c4e7b714 | 55 | .BI "int setsockopt(int " sockfd ", int " level ", int " optname , |
521bf584 MK |
56 | .BI " const void *" optval ", socklen_t " optlen ); |
57 | .fi | |
fea681da | 58 | .SH DESCRIPTION |
7145b9a9 | 59 | .BR getsockopt () |
fea681da | 60 | and |
e511ffb6 | 61 | .BR setsockopt () |
3fdfdab8 MK |
62 | manipulate options for the socket referred to by the file descriptor |
63 | .IR sockfd . | |
c13182ef | 64 | Options may exist at multiple |
fea681da | 65 | protocol levels; they are always present at the uppermost |
3fdfdab8 | 66 | socket level. |
fea681da | 67 | |
3fdfdab8 | 68 | When manipulating socket options, the level at which the |
fea681da | 69 | option resides and the name of the option must be specified. |
3fdfdab8 | 70 | To manipulate options at the sockets API level, |
fea681da MK |
71 | .I level |
72 | is specified as | |
73 | .BR SOL_SOCKET . | |
74 | To manipulate options at any | |
75 | other level the protocol number of the appropriate protocol | |
c13182ef MK |
76 | controlling the option is supplied. |
77 | For example, | |
fea681da MK |
78 | to indicate that an option is to be interpreted by the |
79 | .B TCP | |
80 | protocol, | |
81 | .I level | |
82 | should be set to the protocol number of | |
83 | .BR TCP ; | |
84 | see | |
85 | .BR getprotoent (3). | |
86 | ||
c4bb193f | 87 | The arguments |
fea681da MK |
88 | .I optval |
89 | and | |
90 | .I optlen | |
91 | are used to access option values for | |
e511ffb6 | 92 | .BR setsockopt (). |
fea681da | 93 | For |
e511ffb6 | 94 | .BR getsockopt () |
fea681da | 95 | they identify a buffer in which the value for the |
c13182ef MK |
96 | requested option(s) are to be returned. |
97 | For | |
e511ffb6 | 98 | .BR getsockopt (), |
fea681da | 99 | .I optlen |
c4bb193f | 100 | is a value-result argument, initially containing the |
fea681da MK |
101 | size of the buffer pointed to by |
102 | .IR optval , | |
103 | and modified on return to indicate the actual size of | |
c13182ef MK |
104 | the value returned. |
105 | If no option value is to be supplied or returned, | |
fea681da MK |
106 | .I optval |
107 | may be NULL. | |
108 | ||
109 | .I Optname | |
110 | and any specified options are passed uninterpreted to the appropriate | |
c13182ef MK |
111 | protocol module for interpretation. |
112 | The include file | |
fea681da | 113 | .I <sys/socket.h> |
c13182ef MK |
114 | contains definitions for socket level options, described below. |
115 | Options at | |
fea681da MK |
116 | other protocol levels vary in format and name; consult the appropriate |
117 | entries in section 4 of the manual. | |
118 | ||
119 | Most socket-level options utilize an | |
120 | .I int | |
c4bb193f | 121 | argument for |
fea681da MK |
122 | .IR optval . |
123 | For | |
e511ffb6 | 124 | .BR setsockopt (), |
c7094399 | 125 | the argument should be nonzero to enable a boolean option, or zero if the |
fea681da | 126 | option is to be disabled. |
fea681da MK |
127 | .PP |
128 | For a description of the available socket options see | |
129 | .BR socket (7) | |
130 | and the appropriate protocol man pages. | |
47297adb | 131 | .SH RETURN VALUE |
c13182ef MK |
132 | On success, zero is returned. |
133 | On error, \-1 is returned, and | |
fea681da MK |
134 | .I errno |
135 | is set appropriately. | |
136 | .SH ERRORS | |
137 | .TP 10 | |
138 | .B EBADF | |
139 | The argument | |
3e4088f4 | 140 | .I sockfd |
fea681da MK |
141 | is not a valid descriptor. |
142 | .TP | |
143 | .B EFAULT | |
c13182ef | 144 | The address pointed to by |
fea681da | 145 | .I optval |
c13182ef MK |
146 | is not in a valid part of the process address space. |
147 | For | |
e511ffb6 | 148 | .BR getsockopt (), |
fea681da MK |
149 | this error may also be returned if |
150 | .I optlen | |
151 | is not in a valid part of the process address space. | |
152 | .TP | |
153 | .B EINVAL | |
154 | .I optlen | |
c13182ef | 155 | invalid in |
1e321034 | 156 | .BR setsockopt (). |
71b2fb38 MK |
157 | In some cases this error can also occur for an invalid value in |
158 | .IR optval | |
159 | (e.g., for the | |
160 | .B IP_ADD_MEMBERSHIP | |
161 | option described in | |
162 | .BR ip (7)). | |
fea681da MK |
163 | .TP |
164 | .B ENOPROTOOPT | |
165 | The option is unknown at the level indicated. | |
166 | .TP | |
167 | .B ENOTSOCK | |
168 | The argument | |
3e4088f4 | 169 | .I sockfd |
fea681da | 170 | is a file, not a socket. |
47297adb | 171 | .SH CONFORMING TO |
c13182ef | 172 | SVr4, 4.4BSD (these system calls first appeared in 4.2BSD), |
bc07c514 | 173 | POSIX.1-2001. |
97c1eac8 | 174 | .\" SVr4 documents additional ENOMEM and ENOSR error codes, but does |
c13182ef | 175 | .\" not document the |
97c1eac8 MK |
176 | .\" .BR SO_SNDLOWAT ", " SO_RCVLOWAT ", " SO_SNDTIMEO ", " SO_RCVTIMEO |
177 | .\" options | |
19c98696 | 178 | .SH NOTES |
53a6b01d MK |
179 | POSIX.1-2001 does not require the inclusion of |
180 | .IR <sys/types.h> , | |
181 | and this header file is not required on Linux. | |
182 | However, some historical (BSD) implementations required this header | |
183 | file, and portable applications are probably wise to include it. | |
184 | ||
c13182ef | 185 | The |
97c1eac8 | 186 | .I optlen |
c13182ef | 187 | argument of |
66ee0c7e MK |
188 | .BR getsockopt () |
189 | and | |
190 | .BR setsockopt () | |
c13182ef | 191 | is in reality an |
97c1eac8 MK |
192 | .I "int [*]" |
193 | (and this is what 4.x BSD and libc4 and libc5 have). | |
c13182ef MK |
194 | Some POSIX confusion resulted in the present |
195 | .IR socklen_t , | |
97c1eac8 | 196 | also used by glibc. |
fea681da MK |
197 | See also |
198 | .BR accept (2). | |
199 | .SH BUGS | |
200 | Several of the socket options should be handled at lower levels of the | |
201 | system. | |
47297adb | 202 | .SH SEE ALSO |
fea681da MK |
203 | .BR ioctl (2), |
204 | .BR socket (2), | |
205 | .BR getprotoent (3), | |
206 | .BR protocols (5), | |
207 | .BR socket (7), | |
208 | .BR tcp (7), | |
209 | .BR unix (7) |