![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to getsockopt.2 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys|
Return to getsockopt.2 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys |
1.1 root 1: .\" Copyright (c) 1983 The Regents of the University of California.
2: .\" All rights reserved.
3: .\"
4: .\" Redistribution and use in source and binary forms are permitted provided
5: .\" that: (1) source distributions retain this entire copyright notice and
6: .\" comment, and (2) distributions including binaries display the following
7: .\" acknowledgement: ``This product includes software developed by the
8: .\" University of California, Berkeley and its contributors'' in the
9: .\" documentation or other materials provided with the distribution and in
10: .\" all advertising materials mentioning features or use of this software.
11: .\" Neither the name of the University nor the names of its contributors may
12: .\" be used to endorse or promote products derived from this software without
13: .\" specific prior written permission.
14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
17: .\"
18: .\" @(#)getsockopt.2 6.6 (Berkeley) 6/23/90
19: .\"
20: .TH GETSOCKOPT 2 "June 23, 1990"
21: .UC 5
22: .SH NAME
23: getsockopt, setsockopt \- get and set options on sockets
24: .SH SYNOPSIS
25: .nf
26: .ft B
27: #include <sys/types.h>
28: #include <sys/socket.h>
29: .PP
30: .ft B
31: getsockopt(s, level, optname, optval, optlen)
32: int s, level, optname;
33: char *optval;
34: int *optlen;
35: .sp
36: setsockopt(s, level, optname, optval, optlen)
37: int s, level, optname;
38: char *optval;
39: int optlen;
40: .fi
41: .SH DESCRIPTION
42: .I Getsockopt
43: and
44: .I setsockopt
45: manipulate
46: .I options
47: associated with a socket. Options may exist at multiple
48: protocol levels; they are always present at the uppermost
49: ``socket'' level.
50: .PP
51: When manipulating socket options the level at which the
52: option resides and the name of the option must be specified.
53: To manipulate options at the ``socket'' level,
54: .I level
55: is specified as SOL_SOCKET. To manipulate options at any
56: other level the protocol number of the appropriate protocol
57: controlling the option is supplied. For example,
58: to indicate that an option is to be interpreted by the TCP protocol,
59: .I level
60: should be set to the protocol number of TCP; see
61: .IR getprotoent (3N).
62: .PP
63: The parameters
64: .I optval
65: and
66: .I optlen
67: are used to access option values for
68: .IR setsockopt .
69: For
70: .I getsockopt
71: they identify a buffer in which the value for the
72: requested option(s) are to be returned. For
73: .IR getsockopt ,
74: .I optlen
75: is a value-result parameter, initially containing the
76: size of the buffer pointed to by
77: .IR optval ,
78: and modified on return to indicate the actual size of
79: the value returned. If no option value is
80: to be supplied or returned,
81: .I optval
82: may be supplied as 0.
83: .PP
84: .I Optname
85: and any specified options are passed uninterpreted to the appropriate
86: protocol module for interpretation.
87: The include file
88: .RI < sys/socket.h >
89: contains definitions for ``socket'' level options, described below.
90: Options at other protocol levels vary in format and
91: name; consult the appropriate entries in section (4P).
92: .PP
93: Most socket-level options take an
94: .I int
95: parameter for
96: .IR optval .
97: For
98: .IR setsockopt ,
99: the parameter should non-zero to enable a boolean option,
100: or zero if the option is to be disabled.
101: SO_LINGER uses a
102: .I struct linger
103: parameter, defined in
104: .RI < sys/socket.h >,
105: which specifies the desired state of the option and the
106: linger interval (see below).
107: .PP
108: The following options are recognized at the socket level.
109: Except as noted, each may be examined with
110: .I getsockopt
111: and set with
112: .IR setsockopt .
113: .PP
114: .RS
115: .ta \w'SO_BROADCAST\ \ \ \ 'u
116: .nf
117: SO_DEBUG toggle recording of debugging information
118: SO_REUSEADDR toggle local address reuse
119: SO_KEEPALIVE toggle keep connections alive
120: SO_DONTROUTE toggle routing bypass for outgoing messages
121: SO_LINGER linger on close if data present
122: SO_BROADCAST toggle permission to transmit broadcast messages
123: SO_OOBINLINE toggle reception of out-of-band data in band
124: SO_SNDBUF set buffer size for output
125: SO_RCVBUF set buffer size for input
126: SO_TYPE get the type of the socket (get only)
127: SO_ERROR get and clear error on the socket (get only)
128: .fi
129: .RE
130: .PP
131: SO_DEBUG enables debugging in the underlying protocol modules.
132: SO_REUSEADDR indicates that the rules used in validating addresses supplied
133: in a
134: .IR bind (2)
135: call should allow reuse of local addresses. SO_KEEPALIVE enables the
136: periodic transmission of messages on a connected socket. Should the
137: connected party fail to respond to these messages, the connection is
138: considered broken and processes using the socket are notified via a
139: SIGPIPE signal. SO_DONTROUTE indicates that outgoing messages should
140: bypass the standard routing facilities. Instead, messages are directed
141: to the appropriate network interface according to the network portion
142: of the destination address.
143: .PP
144: SO_LINGER controls the action taken when unsent messags
145: are queued on socket and a
146: .IR close (2)
147: is performed.
148: If the socket promises reliable delivery of data and SO_LINGER is set,
149: the system will block the process on the
150: .I close
151: attempt until it is able to transmit the data or until it decides it
152: is unable to deliver the information (a timeout period, termed the
153: linger interval, is specified in the
154: .IR setsockopt
155: call when SO_LINGER is requested).
156: If SO_LINGER is disabled and a
157: .I close
158: is issued, the system will process the close in a manner that allows
159: the process to continue as quickly as possible.
160: .PP
161: The option SO_BROADCAST requests permission to send broadcast datagrams
162: on the socket.
163: Broadcast was a privileged operation in earlier versions of the system.
164: With protocols that support out-of-band data, the SO_OOBINLINE option
165: requests that out-of-band data be placed in the normal data input queue
166: as received; it will then be accessible with
167: .I recv
168: or
169: .I read
170: calls without the MSG_OOB flag.
171: SO_SNDBUF and SO_RCVBUF are options to adjust the normal
172: buffer sizes allocated for output and input buffers, respectively.
173: The buffer size may be increased for high-volume connections,
174: or may be decreased to limit the possible backlog of incoming data.
175: The system places an absolute limit on these values.
176: Finally, SO_TYPE and SO_ERROR are options used only with
177: .IR setsockopt .
178: SO_TYPE returns the type of the socket, such as SOCK_STREAM;
179: it is useful for servers that inherit sockets on startup.
180: SO_ERROR returns any pending error on the socket and clears
181: the error status.
182: It may be used to check for asynchronous errors on connected
183: datagram sockets or for other asynchronous errors.
184: .SH "RETURN VALUE"
185: A 0 is returned if the call succeeds, \-1 if it fails.
186: .SH ERRORS
187: The call succeeds unless:
188: .TP 20
189: [EBADF]
190: The argument \fIs\fP is not a valid descriptor.
191: .TP 20
192: [ENOTSOCK]
193: The argument \fIs\fP is a file, not a socket.
194: .TP 20
195: [ENOPROTOOPT]
196: The option is unknown at the level indicated.
197: .TP 20
198: [EFAULT]
199: The address pointed to by
200: .I optval
201: is not in a valid part of the process address space.
202: For
203: .IR getsockopt ,
204: this error may also be returned if
205: .I optlen
206: is not in a valid part of the process address space.
207: .SH "SEE ALSO"
208: ioctl(2), socket(2), getprotoent(3N)
209: .SH BUGS
210: Several of the socket options should be handled at lower levels of the system.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.