Debian Codegraph @

upstream/debian-unstable/man2/getsockopt.2

raw
1 .\" Copyright 1983-1991, The Regents of the University of California.
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
5 .\"
6 .TH getsockopt 2 2025-10-29 "Linux man-pages 6.18"
7 .SH NAME
8 getsockopt, setsockopt \- get and set options on sockets
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <sys/socket.h>
15 .P
16 .BR "int getsockopt(" "socklen_t *restrict optlen;"
17 .BI " int " sockfd ", int " level ", int " optname ,
18 .BI " void " optval "[_Nullable restrict *" optlen ],
19 .BI " socklen_t *restrict " optlen );
20 .BR "int setsockopt(" "socklen_t optlen;"
21 .BI " int " sockfd ", int " level ", int " optname ,
22 .BI " const void " optval [ optlen ],
23 .BI " socklen_t " optlen );
24 .fi
25 .SH DESCRIPTION
26 .BR getsockopt ()
27 and
28 .BR setsockopt ()
29 manipulate options for the socket referred to by the file descriptor
30 .IR sockfd .
31 Options may exist at multiple protocol levels;
32 they are always present at the uppermost socket level.
33 .P
34 When manipulating socket options, the level at which the
35 option resides and the name of the option must be specified.
36 To manipulate options at the sockets API level,
37 .I level
38 is specified as
39 .BR SOL_SOCKET .
40 To manipulate options at any
41 other level the protocol number of the appropriate protocol
42 controlling the option is supplied.
43 For example,
44 to indicate that an option is to be interpreted by the
45 .B TCP
46 protocol,
47 .I level
48 should be set to the protocol number of
49 .BR TCP ;
50 see
51 .BR getprotoent (3).
52 .P
53 The arguments
54 .I optval
55 and
56 .I optlen
57 are used to access option values for
58 .BR setsockopt ().
59 For
60 .BR getsockopt ()
61 they identify a buffer in which the value for the
62 requested option(s) are to be returned.
63 For
64 .BR getsockopt (),
65 .I optlen
66 is a value-result argument, initially containing the
67 size of the buffer pointed to by
68 .IR optval ,
69 and modified on return to indicate the actual size of
70 the value returned.
71 If no option value is to be supplied or returned,
72 .I optval
73 may be NULL.
74 .P
75 .I Optname
76 and any specified options are passed uninterpreted to the appropriate
77 protocol module for interpretation.
78 The include file
79 .I <sys/socket.h>
80 contains definitions for socket level options,
81 described below.
82 Options at other protocol levels vary in format and name;
83 consult the appropriate entries in section 4 of the manual.
84 .P
85 Most socket-level options utilize an
86 .I int
87 argument for
88 .IR optval .
89 For
90 .BR setsockopt (),
91 the argument should be nonzero to enable a boolean option, or zero if the
92 option is to be disabled.
93 .P
94 For a description of the available socket options see
95 .BR socket (7)
96 and the appropriate protocol man pages.
97 .SH RETURN VALUE
98 On success, zero is returned for the standard options.
99 On error, \-1 is returned, and
100 .I errno
101 is set to indicate the error.
102 .P
103 Netfilter allows the programmer
104 to define custom socket options with associated handlers;
105 for such options,
106 the return value on success is the value returned by the handler.
107 .SH ERRORS
108 .TP
109 .B EBADF
110 The argument
111 .I sockfd
112 is not a valid file descriptor.
113 .TP
114 .B EFAULT
115 The address pointed to by
116 .I optval
117 is not in a valid part of the process address space.
118 For
119 .BR getsockopt (),
120 this error may also be returned if
121 .I optlen
122 is not in a valid part of the process address space.
123 .TP
124 .B EINVAL
125 .I optlen
126 invalid in
127 .BR setsockopt ().
128 In some cases this error can also occur for an invalid value in
129 .I optval
130 (e.g., for the
131 .B IP_ADD_MEMBERSHIP
132 option described in
133 .BR ip (7)).
134 .TP
135 .B ENOPROTOOPT
136 The option is unknown at the level indicated.
137 .TP
138 .B ENOTSOCK
139 The file descriptor
140 .I sockfd
141 does not refer to a socket.
142 .SH STANDARDS
143 POSIX.1-2024.
144 .SH HISTORY
145 POSIX.1-2001,
146 SVr4, 4.4BSD (first appeared in 4.2BSD).
147 .\" SVr4 documents additional ENOMEM and ENOSR error codes, but does
148 .\" not document the
149 .\" .BR SO_SNDLOWAT ", " SO_RCVLOWAT ", " SO_SNDTIMEO ", " SO_RCVTIMEO
150 .\" options
151 .SH BUGS
152 Several of the socket options should be handled at lower levels of the
153 system.
154 .SH SEE ALSO
155 .BR ioctl (2),
156 .BR socket (2),
157 .BR getprotoent (3),
158 .BR protocols (5),
159 .BR ip (7),
160 .BR packet (7),
161 .BR socket (7),
162 .BR tcp (7),
163 .BR udp (7),
164 .BR unix (7)