'\" te .\" Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights reserved. .\" Copyright 1989 AT&T .TH getsockopt 3SOCKET "7 Jul 2011" "SunOS 5.11" "Sockets Library Functions" .SH NAME getsockopt, setsockopt \- get and set options on sockets .SH SYNOPSIS .LP .nf \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ] #include \fBint\fR \fBgetsockopt\fR(\fBint\fR \fIs\fR, \fBint\fR \fIlevel\fR, \fBint\fR \fIoptname\fR, \fBvoid *\fR\fIoptval\fR, \fBsocklen_t *\fR\fIoptlen\fR); .fi .LP .nf \fBint\fR \fBsetsockopt\fR(\fBint\fR \fIs\fR, \fBint\fR \fIlevel\fR, \fBint\fR \fIoptname\fR, \fBconst void *\fR\fIoptval\fR, \fBsocklen_t\fR \fIoptlen\fR); .fi .SH DESCRIPTION .sp .LP The \fBgetsockopt()\fR and \fBsetsockopt()\fR functions manipulate options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost "socket" level. .sp .LP The \fIlevel\fR argument specifies the protocol level at which the option resides. To manipulate options at the socket level, specify the \fIlevel\fR argument as \fBSOL_SOCKET\fR. To manipulate options at the protocol level, supply the appropriate protocol number for the protocol controlling the option. For example, to indicate that an option will be interpreted by the \fBTCP\fR, set \fIlevel\fR to the protocol number of \fBTCP\fR, as defined in the \fB\fR header, or as determined by using \fBgetprotobyname\fR(3C). Some socket protocol families may also define additional levels, such as \fBSOL_ROUTE\fR. Only socket-level options are described here. .sp .LP The parameters \fIoptval\fR and \fIoptlen\fR are used to access option values for \fBsetsockopt()\fR. For \fBgetsockopt()\fR, they identify a buffer in which the value(s) for the requested option(s) are to be returned. For \fBgetsockopt()\fR, \fIoptlen\fR is a value-result parameter, initially containing the size of the buffer pointed to by \fIoptval\fR, and modified on return to indicate the actual size of the value returned. Use a 0 \fIoptval\fR if no option value is to be supplied or returned. .sp .LP The \fIoptname\fR and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The include file <\fBsys/socket.h\fR> contains definitions for the socket-level options described below. Options at other protocol levels vary in format and name. .sp .LP Most socket-level options take an \fBint\fR for \fIoptval\fR. For \fBsetsockopt()\fR, the \fIoptval\fR parameter should be non-zero to enable a boolean option, or zero if the option is to be disabled. \fBSO_LINGER\fR uses a \fBstruct linger\fR parameter that specifies the desired state of the option and the linger interval. \fBstruct linger\fR is defined in <\fBsys/socket.h\fR>. \fBstruct\fR \fBlinger\fR contains the following members: .sp .ne 2 .mk .na \fB\fBl_onoff\fR\fR .ad .RS 12n .rt on = 1/off = 0 .RE .sp .ne 2 .mk .na \fB\fBl_linger\fR\fR .ad .RS 12n .rt linger time, in seconds .RE .sp .LP The following options are recognized at the socket level. Except as noted, each may be examined with \fBgetsockopt()\fR and set with \fBsetsockopt()\fR. .sp .ne 2 .mk .na \fB\fBSO_DEBUG\fR\fR .ad .RS 22n .rt enable/disable recording of debugging information .RE .sp .ne 2 .mk .na \fB\fBSO_REUSEADDR\fR\fR .ad .RS 22n .rt enable/disable local address reuse .RE .sp .ne 2 .mk .na \fB\fBSO_REUSEPORT\fR\fR .ad .RS 22n .rt enable/disable local port reuse for \fBPF_INET\fR/\fBPF_INET6\fR socket .RE .sp .ne 2 .mk .na \fB\fBSO_KEEPALIVE\fR\fR .ad .RS 22n .rt enable/disable keep connections alive .RE .sp .ne 2 .mk .na \fB\fBSO_DONTROUTE\fR\fR .ad .RS 22n .rt enable/disable routing bypass for outgoing messages .RE .sp .ne 2 .mk .na \fB\fBSO_LINGER\fR\fR .ad .RS 22n .rt linger on close if data is present .RE .sp .ne 2 .mk .na \fB\fBSO_BROADCAST\fR\fR .ad .RS 22n .rt enable/disable permission to transmit broadcast messages .RE .sp .ne 2 .mk .na \fB\fBSO_OOBINLINE\fR\fR .ad .RS 22n .rt enable/disable reception of out-of-band data in band .RE .sp .ne 2 .mk .na \fB\fBSO_SNDBUF\fR\fR .ad .RS 22n .rt set buffer size for output .RE .sp .ne 2 .mk .na \fB\fBSO_RCVBUF\fR\fR .ad .RS 22n .rt set buffer size for input .RE .sp .ne 2 .mk .na \fB\fBSO_DGRAM_ERRIND\fR\fR .ad .RS 22n .rt application wants delayed error .RE .sp .ne 2 .mk .na \fB\fBSO_TIMESTAMP\fR\fR .ad .RS 22n .rt enable/disable reception of timestamp with datagrams .RE .sp .ne 2 .mk .na \fB\fBSO_EXCLBIND\fR\fR .ad .RS 22n .rt enable/disable exclusive binding of the socket .RE .sp .ne 2 .mk .na \fB\fBSO_TYPE\fR\fR .ad .RS 22n .rt get the type of the socket (get only) .RE .sp .ne 2 .mk .na \fB\fBSO_ERROR\fR\fR .ad .RS 22n .rt get and clear error on the socket (get only) .sp In addition to \fBSO_ERROR\fR, the socket error is retrieved and cleared by any \fBioctl\fR(2) invocation. In this case, the device driver detects socket error and passes it through \fBioctl()\fR without change to the caller. .RE .sp .ne 2 .mk .na \fB\fBSO_MAC_EXEMPT\fR\fR .ad .RS 22n .rt get or set mandatory access control on the socket. This option is available only when the system is configured with Trusted Extensions. .RE .sp .ne 2 .mk .na \fB\fBSO_ALLZONES\fR\fR .ad .RS 22n .rt bypass zone boundaries (privileged). .RE .sp .ne 2 .mk .na \fB\fBSO_DOMAIN\fR\fR .ad .RS 22n .rt get the domain used in the socket (get only) .RE .sp .ne 2 .mk .na \fB\fBSO_PROTOTYPE\fR\fR .ad .RS 22n .rt for socket in domains \fBPF_INET\fR and \fBPF_INET6\fR, get the underlying protocol number used in the socket. For socket in domain \fBPF_ROUTE\fR, get the address family used in the socket. .RE .sp .ne 2 .mk .na \fB\fBSO_PASSIVE_CONNECT\fR\fR .ad .RS 22n .rt modify \fBconnect\fR(3SOCKET) to wait for connection request from a peer instead of initiating a connection request to it. It is applicable to TCP/SCTP \fBPF_INET\fR/\fBPF_INET6\fR socket. .RE .sp .ne 2 .mk .na \fB\fBSO_FLOW_SLA\fR\fR .ad .RS 22n .rt set per socket service level properties: priority and bandwidth limit. .sp It is applicable to TCP/UDP PF_INET/PF_INET6 sockets. Requires \fBPRIV_SYS_FLOW_CONFIG\fR privilege. .RE .sp .LP The \fBSO_DEBUG\fR option enables debugging in the underlying protocol modules. The \fBSO_REUSEADDR\fR/\fBSO_REUSEPORT\fR options indicate that the rules used in validating addresses and ports supplied in a \fBbind\fR(3SOCKET) call should allow reuse of local addresses or ports. The \fBSO_KEEPALIVE\fR option enables the periodic transmission of messages on a connected socket. If the connected party fails to respond to these messages, the connection is considered broken and threads using the socket are notified using a \fBSIGPIPE\fR signal. The \fBSO_DONTROUTE\fR option indicates that outgoing messages should bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface according to the network portion of the destination address. .sp .LP The \fBSO_LINGER\fR option controls the action taken when unsent messages are queued on a socket and a \fBclose\fR(2) is performed. If the socket promises reliable delivery of data and \fBSO_LINGER\fR is set, the system will block the thread on the \fBclose()\fR attempt until it is able to transmit the data or until it decides it is unable to deliver the information (a timeout period, termed the linger interval, is specified in the \fBsetsockopt()\fR call when \fBSO_LINGER\fR is requested). If \fBSO_LINGER\fR is disabled and a \fBclose()\fR is issued, the system will process the \fBclose()\fR in a manner that allows the thread to continue as quickly as possible. .sp .LP The option \fBSO_BROADCAST\fR requests permission to send broadcast datagrams on the socket. With protocols that support out-of-band data, the \fBSO_OOBINLINE\fR option requests that out-of-band data be placed in the normal data input queue as received; it will then be accessible with \fBrecv()\fR or \fBread()\fR calls without the \fBMSG_OOB\fR flag. .sp .LP The \fBSO_SNDBUF\fR and \fBSO_RCVBUF\fR options adjust the normal buffer sizes allocated for output and input buffers, respectively. The buffer size may be increased for high-volume connections or may be decreased to limit the possible backlog of incoming data. The maximum buffer size for \fBUDP/TCP\fR is determined by the value of the \fBipadm\fR variable \fImax_buf\fR for that particular protocol. Use the \fBipadm\fR(1M) utility to determine the current default values. See the \fISolaris Tunable Parameters Reference Manual\fR for information on setting the values of \fBmax_buf\fR for either TCP, UDP or both. At present, lowering \fBSO_RCVBUF\fR on a TCP connection after it has been established has no effect. .sp .LP By default, delayed errors (such as \fBICMP\fR port unreachable packets) are returned only for connected datagram sockets. The \fBSO_DGRAM_ERRIND\fR option makes it possible to receive errors for datagram sockets that are not connected. When this option is set, certain delayed errors received after completion of a \fBsendto()\fR or \fBsendmsg()\fR operation will cause a subsequent \fBsendto()\fR or \fBsendmsg()\fR operation using the same destination address (\fIto\fR parameter) to fail with the appropriate error. See \fBsend\fR(3SOCKET). .sp .LP If the \fBSO_TIMESTAMP\fR option is enabled on a \fBSO_DGRAM\fR or a \fBSO_RAW\fR socket, the \fBrecvmsg\fR(3C) call will return a timestamp in the native data format, corresponding to when the datagram was received. .sp .LP The \fBSO_EXCLBIND\fR option is used to enable or disable the exclusive binding of a socket. It overrides the use of the \fBSO_REUSEADDR\fR option to reuse an address on \fBbind\fR(3SOCKET). The actual semantics of the \fBSO_EXCLBIND\fR option depend on the underlying protocol. See \fBtcp\fR(7P) or \fBudp\fR(7P) for more information. .sp .LP The \fBSO_TYPE\fR and \fBSO_ERROR\fR options are used only with \fBgetsockopt()\fR. The \fBSO_TYPE\fR option returns the type of the socket, for example, \fBSOCK_STREAM\fR. It is useful for servers that inherit sockets on startup. The \fBSO_ERROR\fR option returns any pending error on the socket and clears the error status. It may be used to check for asynchronous errors on connected datagram sockets or for other asynchronous errors. .sp .LP The \fBSO_MAC_EXEMPT\fR option is used to toggle socket behavior with unlabeled peers. A socket that has this option enabled can communicate with an unlabeled peer if it is in the global zone or has a label that dominates the default label of the peer. Otherwise, the socket must have a label that is equal to the default label of the unlabeled peer. Calling \fBsetsockopt()\fR with this option returns an \fBEACCES\fR error if the process lacks the \fBNET_MAC_AWARE\fR privilege or if the socket is bound. The \fBSO_MAC_EXEMPT\fR option is available only when the system is configured with Trusted Extensions. .sp .LP The \fBSO_ALLZONES\fR option can be used to bypass zone boundaries between shared-IP zones. Normally, the system prevents a socket from being bound to an address that is not assigned to the current zone. It also prevents a socket that is bound to a wildcard address from receiving traffic for other zones. However, some daemons which run in the global zone might need to send and receive traffic using addresses that belong to other shared-IP zones. If set before a socket is bound, \fBSO_ALLZONES\fR causes the socket to ignore zone boundaries between shared-IP zones and permits the socket to be bound to any address assigned to the shared-IP zones. If the socket is bound to a wildcard address, it receives traffic intended for all shared-IP zones and behaves as if an equivalent socket were bound in each active shared-IP zone. Applications that use the \fBSO_ALLZONES\fR option to initiate connections or send datagram traffic should specify the source address for outbound traffic by binding to a specific address. There is no effect from setting this option in an exclusive-IP zone. Setting this option requires the \fBsys_net_config\fR privilege. See \fBzones\fR(5). .sp .LP The \fBSO_PASSIVE_CONNECT\fR option can be used to modify \fBconnect()\fR semantics for TCP and SCTP socket. After this option is set, calling \fBconnect()\fR on the socket will not initiate a connection setup sequence. Instead, the transport end point is in listen state waiting for a connection request from the remote peer specified in \fBconnect()\fR. After the expected connection is established, \fBconnect()\fR returns. .sp .LP \fBSO_FLOW_SLA\fR socket option can be used to set per socket service level properties for the socket. The properties, priority and bandwidth limit are supported in \fBSOCK_FLOW_PROP_VERSION1\fR. These properties are effective for both outbound and inbound packets. .sp .LP Only TCP and UDP PF_INET/PF_INET6 sockets are supported at this time. .sp .LP The socket option takes a pointer to a \fBsock_flow_props_t\fR structure as the value: .sp .in +2 .nf typedef struct sock_flow_props_s { int sfp_version; uint32_t sfp_mask; int sfp_priority; /* flow priority */ uint64_t sfp_maxbw; /* bandwidth limit in bps */ int sfp_status; /* flow create status for getsockopt */ } sock_flow_props_t; #define SOCK_FLOW_PROP_VERSION1 1 /* bit mask values for sfp_mask */ #define SFP_MAXBW 0x00000001 /* BW Limit */ #define SFP_PRIORITY 0x00000008 /* Priority */ /* possible values for sfp_priority */ #define SFP_PRIO_NORMAL 1 #define SFP_PRIO_HIGH 2 .fi .in -2 .sp .LP A value of 0 for \fBsfp_maxbw\fR drops all packets for the socket. .sp .LP The status of the flow creation can be obtained by a \fBgetsockopt()\fR. The \fBsfp_status\fR field indicates the status. A value of 0 means a flow is successfully created. In case of an error, this field has the \fBerrno\fR to indicate the error. This field is not set during \fBsetsockopt()\fR and is ignored. .SH USAGE .LP \fBExample 1 \fRExamples of Usage .sp .in +2 .nf a. at the time of socket(3c) call sock_flow_props_t sprop; ... sock = socket(AF_INET, SOCK_DGRAM, 0); sprop.sfp_version = SOCK_FLOW_PROP_VERSION1; sprop.sfp_mask = SFP_PRIORITY; sprop.sfp_priority = SFP_PRIO_HIGH; setsockopt(sock, SOL_SOCKET, SO_FLOW_SLA, &sprop, sizeof (sprop)); ... b. at the time of the accept(3c) call sock_flow_props_t sprop; ... newsock = accept(listen_sock, (struct sockaddr *)&from, &fromlen); // construct sprop setsockopt(newsock, SOL_SOCKET, SO_FLOW_SLA, &sprop, sizeof (sprop)); ... .fi .in -2 .sp .LP A socket application using this socket option, causes the system to create a system flow. \fBflowadm\fR(1M) can be used to observe these flows. These system generated flows have the prefix \fB.sys.sock\fR\&. .sp .LP The \fBpfiles\fR command prints the \fBSO_FLOW_SLA\fR socket option along with the other socket options. .sp .LP Creation of a system flow requires the link name and the 5-tuple in case of a connected socket and the local 3-tuple in case of a listener/bound socket. The following restrictions exist for the cases where a link name or a value in the 5-tuple/3-tuple can not be obtained given a socket. Some of these restrictions may be relaxed in future. .RS +4 .TP .ie t \(bu .el o Sockets using IP loopback addresses (\fB/dev/lo0\fR) are not supported. .RE .RS +4 .TP .ie t \(bu .el o Only connected UDP is supported. This means the socket call, \fBconnect()\fR, must be made for the option to be enforced. .RE .RS +4 .TP .ie t \(bu .el o \fBINADDR_ANY\fR IP address is not supported. So, the socket call, \fBbind()\fR, must pass an IP address for the option to be enforced. .RE .sp .LP Note that a flow is not created if the above conditions are not met. It is not an error (i.e. bind/connect would not fail) if a flow is not created. \fBgetsockopt()\fR should be used to determine if a flow is created. .SH RETURN VALUES .sp .LP If successful, \fBgetsockopt()\fR and \fBsetsockopt()\fR return \fB0\fR. Otherwise, the functions return \fB\(mi1\fR and set \fBerrno\fR to indicate the error. .SH ERRORS .sp .LP The \fBgetsockopt()\fR and \fBsetsockopt()\fR calls succeed unless: .sp .ne 2 .mk .na \fB\fBEBADF\fR\fR .ad .RS 17n .rt The argument \fIs\fR is not a valid file descriptor. .RE .sp .ne 2 .mk .na \fB\fBEACCES\fR\fR .ad .RS 17n .rt Permission denied. .RE .sp .ne 2 .mk .na \fB\fBEADDRINUSE\fR\fR .ad .RS 17n .rt Address already joined for \fBIP_ADD_MEMBERSHIP\fR. .RE .sp .ne 2 .mk .na \fB\fBEADDRNOTAVAIL\fR\fR .ad .RS 17n .rt Bad interface address for \fBIP_ADD_MEMBERSHIP\fR and \fBIP_DROP_MEMBERSHIP\fR. .RE .sp .ne 2 .mk .na \fB\fBEHOSTUNREACH\fR\fR .ad .RS 17n .rt Invalid address for \fBIP_MULTICAST_IF\fR. .RE .sp .ne 2 .mk .na \fB\fBEINVAL\fR\fR .ad .RS 17n .rt Invalid length for \fBIP_OPTIONS\fR. .sp Not a multicast address for \fBIP_ADD_MEMBERSHIP\fR and \fBIP_DROP_MEMBERSHIP\fR. .sp The specified option is invalid at the specified socket level, or the socket has been shut down. .RE .sp .ne 2 .mk .na \fB\fBENOBUFS\fR\fR .ad .RS 17n .rt \fBSO_SNDBUF\fR or \fBSO_RCVBUF\fR exceeds a system limit. .RE .sp .ne 2 .mk .na \fB\fBENOENT\fR\fR .ad .RS 17n .rt Address not joined for \fBIP_DROP_MEMBERSHIP\fR. .RE .sp .ne 2 .mk .na \fB\fBENOMEM\fR\fR .ad .RS 17n .rt There was insufficient memory available for the operation to complete. .RE .sp .ne 2 .mk .na \fB\fBENOPROTOOPT\fR\fR .ad .RS 17n .rt The option is unknown at the level indicated. .RE .sp .ne 2 .mk .na \fB\fBENOSR\fR\fR .ad .RS 17n .rt There were insufficient STREAMS resources available for the operation to complete. .RE .sp .ne 2 .mk .na \fB\fBENOTSOCK\fR\fR .ad .RS 17n .rt The argument \fIs\fR is not a socket. .RE .sp .ne 2 .mk .na \fB\fBEPERM\fR\fR .ad .RS 17n .rt No permissions or sufficient privileges. .RE .sp .ne 2 .mk .na \fB\fBENOTCONN\fR\fR .ad .RS 17n .rt Flow creation status for \fBgetsockopt()\fR for \fBSO_FLOW_SLA\fR. No flow is created yet as the application did not do a connect or bind. .RE .sp .ne 2 .mk .na \fB\fBEOPNOTSUPP\fR\fR .ad .RS 17n .rt Flow creation status for \fBgetsockopt()\fR for \fBSO_FLOW_SLA\fR. Flow creation is not supported for this socket. .RE .sp .ne 2 .mk .na \fB\fBEALREADY\fR\fR .ad .RS 17n .rt A flow with identical attributes exists. .RE .sp .ne 2 .mk .na \fB\fBEINPROGRESS\fR\fR .ad .RS 17n .rt A flow is being created. .RE .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ MT-LevelSafe .TE .SH SEE ALSO .sp .LP \fBipadm\fR(1M), \fBclose\fR(2), \fBioctl\fR(2), \fBread\fR(2), \fBbind\fR(3SOCKET), \fBconnect\fR(3SOCKET), \fBrecv\fR(3SOCKET), \fBsend\fR(3SOCKET), \fBsocket\fR(3SOCKET), \fBsocket.h\fR(3HEAD), \fBattributes\fR(5), \fBzones\fR(5), \fBtcp\fR(7P), \fBudp\fR(7P), \fBflowadm\fR(1M) .sp .LP \fISolaris Tunable Parameters Reference Manual\fR