.TH getsockopt 3 "MiNT-Net"

.SH NAME

getsockopt, setsockopt \- get and set options on sockets

.SH SYNOPSIS

.B #include <sys/socket.h>

.PP

.PD 0

.B "int getsockopt(int s, int level, int optname,"

.IP

.B "void \(**optval, size_t \(**optlen);"

.PD

.PP

.PD 0

.B "int setsockopt(int s, int level, int optname,"

.IP

.B "void \(**optval, size_t optlen);"

.PD

.SH DESCRIPTION

.I getsockopt

and

.I setsockopt

manipulate options associated with a socket.

The socket is identified by the socket descriptor

.IR s .

Options can exist at multiple protocol levels,

and they are always present at the uppermost ``socket'' level (see

.IR socket (3)).

.PP

When manipulating socket options, the level at which the option resides

.RI ( level )

and the name of the option

.RI ( optname )

must be specified.

To manipulate options at the ``socket'' level,

.I level

is specified as

.SM SOL_SOCKET.

.PP

There are two kinds of options: boolean and non-boolean.

Boolean options are either set or not set and also can use

.I optval

and

.I optlen

(see below) to pass information.

Non-boolean options always use

.I optval

and

.I optlen

to pass information.

.PP

To determine whether or not a boolean option is set,

the return value of

.I getsockopt

must be examined.

If the option is set,

.I getsockopt

returns without error.

If the boolean option is not set,

.I getsockopt

returns \-1 and

.I errno

is set to

.SM ENOPROTOOPT.

.PP

For

.I setsockopt,

the parameters

.I optval

and

.I optlen

are used to pass option information from the calling process to the system.

.I optval

is the address of a location in memory that contains

the option information to be passed to the system.

.I optlen

is an object of type size_t that specifies the size in bytes of

the option information.

.PP

For

.I getsockopt,

.I optval

and

.I optlen

are used to pass option information from the system to the calling process.

.I optval

is the address of a location in memory that contains

the option information to be passed to the calling process, or

(char *)

.SM NULL

if the option is of type boolean.

.I optlen

is an address of an object of type size_t that is initially used to specify

the maximum number of bytes of option information to be passed.

If

.I optval

is not (char *)

.SM NULL,

.I optlen

is set on return to the actual number of bytes of option information passed.

If the

.I getsockopt

call fails, no option information is passed.

.PP

.I optname

and any specified options are passed uninterpreted to the

appropriate protocol module for interpretation.

The include file

.RB < sys/socket.h >

contains definitions for ``socket'' level options (see

.IR socket (3)).

Options at other protocol levels vary in format and name.

.PP

The ``socket'' level options defined in the include file

.RB < sys/socket.h >

are explained below:

.RS

.TP 25

.SM SO_DEBUG

(boolean option) no functionality; included only for compatibility.

.TP

.SM SO_DONTROUTE

(boolean option;

.SM SOCK_STREAM

sockets only) causes outgoing messages to bypass standard routing

facilities and to be routed by the network portion of the Internet address.

.TP

.SM SO_REUSEADDR

(boolean option;

.SM AF_INET

sockets only) allows local address reuse.

.TP

.SM SO_KEEPALIVE

(boolean option;

.SM SOCK_STREAM

sockets only;

.SM AF_INET

sockets only) keeps otherwise idle connected sockets active

by forcing transmissions every 45 seconds

for up to 6 minutes without a response.

.TP

.SM SO_LINGER

(boolean option;

.SM SOCK_STREAM

sockets only;

.SM AF_INET

sockets only) lingers on close if data is present.

For

.SM SO_LINGER,

optval points to a struct linger, defined in

.IR <sys/socket.h> .

The linger structure contains an integer boolean

flag to toggle behavior on/off and an integer linger value.

.TP

.SM SO_BROADCAST

(boolean option;

.SM SOCK_DGRAM

sockets only;

.SM AF_INET

sockets only) toggles permission to transmit broadcast messages.

.TP

.SM SO_RCVBUF

(non-boolean option) For stream sockets it changes the buffer size

of a socket's receive socket buffer.

For datagram sockets it changes the maximum size message

a socket can receive.

.TP

.SM SO_SNDBUF

(non-boolean option) For stream sockets,

it changes the buffer size of a socket's send socket buffer.

For datagram sockets it changes the maximum size message that can be sent.

.TP

.SM SO_USELOOPBACK

(boolean option) no functionality; included only for compatibility.

.RE

.PP

None of the boolean options are supported for

.SM SOCK_DGRAM

sockets.

.PP

If

.SM SO_DONTROUTE

is set, the system does not use the network routing tables

when determining which interface to use to send an outbound message.

Instead, the system sends the message out through the interface

that has a configured address matching the address

to which the message is intended to be sent.

If

.SM SO_DONTROUTE

is not set, the system uses the network routing tables.

.PP

.SM SO_REUSEADDR

indicates the rules used in validating addresses supplied in a

.IR bind (3)

call should allow reuse of local addresses.

This allows multiple

.SM SOCK_STREAM

sockets to be bound to the same local address,

as long as all existing sockets at the desired address

are in a connected state before the

.IR bind (3)

is done on the new socket.

The

.SM SO_REUSEADDR

option has no effect on

.SM SOCK_DGRAM

sockets.

.PP

The

.SM SO_KEEPALIVE

option defaults to off.

.PP

.SM SO_LINGER

controls the actions taken when unsent messages are queued on a

.SM SOCK_STREAM

socket and a

.IR close (3)

is performed.

If

.SM SO_LINGER

is toggled on with a non-zero linger interval,

the system blocks the process on the

.IR close (3)

attempt until it is able to transmit the data or until it decides

it is unable to deliver the information.

If

.SM SO_LINGER

is toggled on with a linger interval of zero,

the connection is immediately terminated on the

.IR close (3)

of the socket, and any unsent data queued on the connection is lost.

If

.SM SO_LINGER

is toggled off

(default upon socket creation) and a

.IR close (3)

is issued, the call returns immediately.

The system still gracefully brings down the connection

by transmitting any queued data, if possible.

.SM SO_LINGER

can be toggled on/off

at any time during the life of an established connection.

Toggling

.SM SO_LINGER

does not affect the action of

.IR shutdown (3).

.PP

The

.SM SO_BROADCAST

option requests permission to send Internet broadcast datagrams

on the socket.

.PP

For stream sockets,

.SM SO_RCVBUF

and

.SM SO_SNDBUF

can be used with

.I getsockopt

to find the current sizes (in number of bytes)

of the socket's receive and send buffers, respectively.

If supported by the protocol,

.SM SO_RCVBUF

and

.SM SO_SNDBUF

can also be used with

.I setsockopt

to set the sizes (in number of bytes)

of the socket's receive and send buffers, respectively.

The sizes are passed as integer values using

.I optval

and

.IR optlen .

You can increase a socket's buffer size at any time, but you can

decrease it only prior to establishing a connection.

The default and maximum buffer sizes are protocol-specific.

.PP

For datagram sockets,

.SM SO_RCVBUF

and

.SM SO_SNDBUF

can be used with

.I getsockopt

to find the current maximum datagram size (in number of bytes)

in the inbound and outbound direction, respectively.

.SM SO_RCVBUF

and

.SM SO_SNDBUF

can also be used with

.I setsockopt

to set the maximum datagram size.

The default and maximum datagram sizes are protocol-specific.

.RE

.SH RETURN VALUE

If the call is successful, 0 is returned.

If it fails, \-1 is returned and an error code is stored in

.BR errno .

.SH DIAGNOSTICS

The call to

.I getsockopt

or

.I setsockopt

fails if:

.TP 20

.SM [EBADF]

The argument

.I s

is not a valid descriptor.

.TP

.SM [EOPNOTSUPP]

The option is not supported by the protocol in use by the socket.

.TP

.SM [ENOMEM]

No buffer space is available.

.TP

.SM [ENOPROTOOPT]

In

.IR getsockopt ,

the requested option is currently not set.

.TP

.SM [EINVAL]

The option is unknown at the socket level or the socket has been shut down,

the

.I optval

or, in the case of

.IR getsockopt ,

.I optlen

parameters are not valid or the information cannot be obtained or set.

The argument

.I s

is a file, not a socket.

.SH SEE ALSO

socket(3).