getsockopt(3c) 맨 페이지 - 윈디하나의 솔라나라

개요

섹션
맨 페이지 이름
검색(S)

getsockopt(3c)

Standard C Library Functions                                    getsockopt(3C)



NAME
       getsockopt, setsockopt - get and set options on sockets

SYNOPSIS
       #include <sys/socket.h>

       int getsockopt(int s, int level, int optname, void *restrict optval,
            socklen_t *restrict optlen);


       int setsockopt(int s, int level, int optname, const void *optval,
            socklen_t optlen);

DESCRIPTION
       The  getsockopt() and setsockopt() functions manipulate options associ‐
       ated with a socket. Options may exist at multiple protocol levels; they
       are always present at the uppermost "socket" level.


       The  level  argument  specifies  the protocol level at which the option
       resides. To manipulate options at the socket level, specify  the  level
       argument  as  SOL_SOCKET.  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 TCP, set level to the protocol number of TCP,  as  defined  in  the
       <netinet/in.h>  header,  or  as determined by using getprotobyname(3C).
       Some socket protocol families may also define additional  levels,  such
       as SOL_ROUTE. Only socket-level options are described here.


       The  parameters  optval and optlen are used to access option values for
       setsockopt(). For getsockopt(), they identify a  buffer  in  which  the
       value(s)  for  the requested option(s) are to be returned. For getsock‐
       opt(), optlen is a value-result  parameter,  initially  containing  the
       size  of  the  buffer  pointed  to by optval, and modified on return to
       indicate the actual size of the value returned. Use a 0  optval  if  no
       option value is to be supplied or returned.


       The  optname  and any specified options are passed uninterpreted to the
       appropriate  protocol  module  for  interpretation.  The  include  file
       <sys/socket.h>   contains  definitions  for  the  socket-level  options
       described below. Options at other protocol levels vary  in  format  and
       name.


       Most socket-level options take an int for optval. For setsockopt(), the
       optval parameter should be non-zero to enable a boolean option, or zero
       if the option is to be disabled. SO_LINGER uses a struct linger parame‐
       ter that specifies the desired state  of  the  option  and  the  linger
       interval.  struct  linger is defined in <sys/socket.h>. struct   linger
       contains the following members:

       l_onoff     on = 1/off = 0


       l_linger    linger time, in seconds



       The following options are recognized at the  socket  level.  Except  as
       noted,  each  may  be  examined with getsockopt() and set with setsock‐
       opt().

       SO_DEBUG              enable/disable recording of debugging information


       SO_REUSEADDR          enable/disable local address reuse


       SO_REUSEPORT          enable/disable local port reuse for  TCP/SCTP/UDP
                             socket


       SO_KEEPALIVE          enable/disable keep connections alive


       SO_DONTROUTE          enable/disable  routing  bypass for outgoing mes‐
                             sages


       SO_LINGER             linger on close if data is present


       SO_BROADCAST          enable/disable permission to  transmit  broadcast
                             messages


       SO_OOBINLINE          enable/disable  reception  of out-of-band data in
                             band


       SO_SNDBUF             set buffer size for output


       SO_RCVBUF             set buffer size for input


       SO_SNDTIMEO           set the send timeout for socket


       SO_RCVTIMEO           set the receive timeout for socket


       SO_DGRAM_ERRIND       application wants delayed error


       SO_TIMESTAMP          enable/disable reception of timestamp with  data‐
                             grams


       SO_LISTENQLIMIT       get the current value of listen queue limit (ini‐
                             tially set using the  backlog  argument  of  lis‐
                             ten(3C)).  This option is available only with the
                             getsockopt() function.


       SO_EXCLBIND           enable/disable exclusive binding of the socket


       SO_TYPE               get the type of the socket (get only)


       SO_ERROR              get and clear error on the socket (get only)

                             In addition to  SO_ERROR,  the  socket  error  is
                             retrieved and cleared by any ioctl(2) invocation.
                             In this case, the device  driver  detects  socket
                             error  and  passes  it  through  ioctl()  without
                             change to the caller.


       SO_MAC_EXEMPT         get  or  set  mandatory  access  control  on  the
                             socket.  This  option  is available only when the
                             system is configured with Trusted Extensions.


       SO_ALLZONES           bypass zone boundaries (privileged).


       SO_DOMAIN             get the domain used in the socket (get only)


       SO_PROTOTYPE          for socket in domains PF_INET and  PF_INET6,  get
                             the   underlying  protocol  number  used  in  the
                             socket. For socket in domain  PF_ROUTE,  get  the
                             address family used in the socket.


       SO_PASSIVE_CONNECT    modify connect(3C) to wait for connection request
                             from a peer instead of  initiating  a  connection
                             request  to  it.  It  is  applicable  to TCP/SCTP
                             PF_INET/PF_INET6 socket.


       SO_FLOW_SLA           set per socket service level properties: priority
                             and bandwidth limit.

                             It  is  applicable  to  TCP/UDP  PF_INET/PF_INET6
                             sockets. Requires PRIV_SYS_FLOW_CONFIG privilege.


       SO_FLOW_NAME          Make the socket a flow filter  of  the  specified
                             MAC flow.

                             It  is  applicable  to  TCP/UDP  PF_INET/PF_INET6
                             sockets. Requires PRIV_SYS_FLOW_CONFIG privilege.


       SO_NOSIGPIPE          Get and set whether this specific socket  returns
                             only  EPIPE  on  write when the socket is discon‐
                             nected or whether a SIGPIPE is send.



       The SO_DEBUG option enables debugging in the underlying  protocol  mod‐
       ules.  The SO_REUSEADDR or SO_REUSEPORT options indicate that the rules
       used in validating addresses and ports supplied in a bind() call should
       allow  reuse of local addresses or ports. For more information, see the
       bind(3C) man page. The SO_REUSEPORT option must be set by all the sock‐
       ets  including the first socket, before calling bind() to enable reuse.
       All the calling processes must have the  same  effective  UID  for  the
       bind()  call  to succeed. This option allows multiple listeners binding
       to the same local address or port pair. For TCP/SCTP socket, new incom‐
       ing  connection  requests  will  be  distributed across those listeners
       bound to the same local address or port pair. For UDP socket,  incoming
       datagrams will be distributed across those bound sockets. The algorithm
       used to determine how to select a socket using this option  to  deliver
       an  incoming  TCP/SCTP  connection  request  or  an UDP datagram can be
       changed by modifying the ipadm protocol property, reuseport-lbalg.  The
       current supported algorithms are:

           o      Round Robin (rr)


           o      Hashing on source IP address (src-ip)


           o      Hashing on source IP address and source port (src-ip-port)


           o      Hashing on source and destination IP address (src-dst-ip)


           o      Hashing on all 4 tuples (src-dst-ip-ports)



       The  string  in parenthesis is the value used in ipadm to represent the
       algorithm. For more information, see the ipadm(8) man page.


       The SO_KEEPALIVE 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 SIGPIPE signal.


       The  SO_DONTROUTE 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.


       The SO_LINGER option controls the action taken when unsent messages are
       queued  on a socket and a close(2) is performed. If the socket promises
       reliable delivery of data and SO_LINGER is set, the system  will  block
       the thread on the close() 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 setsockopt()
       call when SO_LINGER is requested).  If  SO_LINGER  is  disabled  and  a
       close() is issued, the system will process the close() in a manner that
       allows the thread to continue as quickly as possible.


       The option SO_BROADCAST requests permission to send broadcast datagrams
       on  the  socket.  With  protocols  that  support  out-of-band data, the
       SO_OOBINLINE option requests that out-of-band data  be  placed  in  the
       normal  data  input  queue as received; it will then be accessible with
       recv() or read() calls without the MSG_OOB flag.


       The SO_SNDBUF and SO_RCVBUF 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 UDP/TCP is determined by the value of the  ipadm  variable  max_buf
       for that particular protocol. Use the ipadm(8) utility to determine the
       current default values. See the Solaris  Tunable  Parameters  Reference
       Manual for information on setting the values of max_buf for either TCP,
       UDP or both. At present, lowering SO_RCVBUF on a TCP  connection  after
       it has been established has no effect.


       The  SO_SNDTIMEO and SO_RCVTIMEO options specify the timeout for socket
       I/O functions. Both options take a pointer to struct timeval  as  their
       argument. The default timeout value is zero, which means the socket I/O
       functions will never timeout. If the timeout expires and  no  data  has
       been  sent,  the  socket  I/O functions will return -1 and set errno to
       EAGAIN or EWOULDBLOCK. If some data has already been  transferred  when
       timeout fires, the socket I/O functions will return the number of bytes
       transferred so far. The socket functions affected by  this  option  are
       write(),  send(),  sendto(), sendmsg(), read(), recv(), recvfrom(), and
       recvmsg().


       By default, delayed errors (such as ICMP port unreachable packets)  are
       returned  only  for  connected  datagram  sockets.  The SO_DGRAM_ERRIND
       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 sendto()  or  sendmsg()  operation  will
       cause  a subsequent sendto() or sendmsg() operation using the same des‐
       tination address (to parameter) to fail with the appropriate error. See
       send(3C).


       If the SO_TIMESTAMP option is enabled on a SO_DGRAM or a SO_RAW socket,
       the recvmsg(3C) call will return a timestamp in the native data format,
       corresponding to when the datagram was received.


       The SO_EXCLBIND option is used to enable or disable the exclusive bind‐
       ing of a socket. It overrides the use of the SO_REUSEADDR option to re‐
       use  an  address  on  bind(3C). The actual semantics of the SO_EXCLBIND
       option depend on the underlying protocol. See tcp(4P)  or  udp(4P)  for
       more information.


       The  SO_TYPE  and SO_ERROR options are used only with getsockopt(). The
       SO_TYPE  option  returns  the  type  of  the   socket,   for   example,
       SOCK_STREAM.  It is useful for servers that inherit sockets on startup.
       The SO_ERROR 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.


       The SO_MAC_EXEMPT option is used to toggle socket behavior  with  unla‐
       beled 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 domi‐
       nates  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
       setsockopt()  with  this  option returns an EACCES error if the process
       lacks the NET_MAC_AWARE privilege  or  if  the  socket  is  bound.  The
       SO_MAC_EXEMPT  option  is  available only when the system is configured
       with Trusted Extensions.


       The SO_ALLZONES 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,  SO_ALLZONES
       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 traf‐
       fic 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 SO_ALLZONES 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 sys_net_config
       privilege. See zones(7).


       The SO_PASSIVE_CONNECT option can be used to modify connect() semantics
       for TCP and SCTP socket. After this option is set, calling connect() 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 connect(). After the expected connec‐
       tion is established, connect() returns.


       SO_FLOW_SLA  socket  option can be used to set per socket service level
       properties for the socket. The properties, priority and bandwidth limit
       are  supported  in SOCK_FLOW_PROP_VERSION1. These properties are effec‐
       tive for both outbound and inbound packets.


       Only TCP and UDP PF_INET/PF_INET6 sockets are supported at this time.


       The socket option takes a pointer to a sock_flow_props_t  structure  as
       the value:



         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



       A value of 0 for sfp_maxbw drops all packets for the socket.


       The  status of the flow creation can be obtained by a getsockopt(). The
       sfp_status field indicates the status. A value of 0  means  a  flow  is
       successfully  created. In case of an error, this field has the errno to
       indicate the error. This field is not set during  setsockopt()  and  is
       ignored.

USAGE
       Example 1 Examples of Usage



              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));
              ...



       A  socket  application  using  this socket option, causes the system to
       create a system flow. flowadm(8) can be used to  observe  these  flows.
       These system generated flows have the prefix <id>.sys.sock.


       The  pfiles command prints the SO_FLOW_SLA socket option along with the
       other socket options.


       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 lis‐
       tener/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.

           o      Sockets using IP loopback addresses (/dev/lo0) are not  sup‐
                  ported.


           o      Only connected UDP is supported. This means the socket call,
                  connect(), must be made for the option to be enforced.


           o      INADDR_ANY IP address is not supported. So, the socket call,
                  bind(),  must  pass  an  IP  address  for  the  option to be
                  enforced.



       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. getsockopt() should be used to determine if a flow is created.


       SO_FLOW_NAME socket option makes a socket a member of the specified MAC
       flow. Multiple sockets can belong to the same flow. Each socket maps to
       a flow filter. The flow is created if it does not already exist. If the
       flow exists, it is assumed that the flow name is known and the applica‐
       tion got it out of band.


       The following is an example code using SO_FLOW_NAME:


         char flow[MAXUSERFLOWNAMELEN];
         (void) strlcpy(flow, "tenantA", MAXUSERFLOWNAMELEN);
         /* Assign a socket to the flow */rv = setsockopt(sock1, SOL_SOCKET, SO_FLOW_NAME, flow,
         strlen(flow));
         rv = setsockopt(sock1, SOL_SOCKET, SO_FLOW_NAME, flow,
              strlen(flow));
         rv = setsockopt(sock2, SOL_SOCKET, SO_FLOW_NAME, flow,
              strlen(flow));
         ...



       An application can use either SO_FLOW_SLA or SO_FLOW_NAME option exclu‐
       sively. They can also be used together with the following rules.


       For a given socket, this sequence of setsockopt() calls is allowed:


         setsockopt(s, SO_FLOW_NAME, ...)
         setsockopt(s, SO_FLOW_SLA, ...)



       In  this  case,  the  SLA on the flow is modified. SO_FLOW_SLA does not
       create any system flow though the socket already belongs to a  flow  as
       indicated by SO_FLOW_NAME.


       For a given socket, this sequence is not allowed:


         setsockopt(s, SO_FLOW_SLA, ...);
         setsockopt(s, SO_FLOW_NAME, ...);



       We  do  not  allow  this  because  we  already  create  a  system  flow
       <int>.sys.sock for the first call. The second call fails in this case.


       getsockopt() can be called with either of the  socket  options  at  any
       time.

RETURN VALUES
       If  successful,  getsockopt() and setsockopt() return 0. Otherwise, the
       functions return −1 and set errno to indicate the error.

ERRORS
       The getsockopt() and setsockopt() calls succeed unless:

       EBADF            The argument s is not a valid file descriptor.


       EACCES           Permission denied.


       EADDRINUSE       Address already joined for IP_ADD_MEMBERSHIP.


       EADDRNOTAVAIL    Bad  interface  address  for   IP_ADD_MEMBERSHIP   and
                        IP_DROP_MEMBERSHIP.


       EHOSTUNREACH     Invalid address for IP_MULTICAST_IF.


       EINVAL           Invalid length for IP_OPTIONS.

                        Not  a  multicast  address  for  IP_ADD_MEMBERSHIP and
                        IP_DROP_MEMBERSHIP.

                        The specified  option  is  invalid  at  the  specified
                        socket level, or the socket has been shut down.


       ENOBUFS          SO_SNDBUF or SO_RCVBUF exceeds a system limit.


       ENOENT           Address not joined for IP_DROP_MEMBERSHIP.


       ENOMEM           There was insufficient memory available for the opera‐
                        tion to complete.


       ENOPROTOOPT      The option is unknown at the level indicated.


       ENOSR            There were insufficient  STREAMS  resources  available
                        for the operation to complete.


       ENOTSOCK         The argument s is not a socket.


       EPERM            No permissions or sufficient privileges.


       ENOTCONN         Flow creation status for getsockopt() for SO_FLOW_SLA.
                        No flow is created yet as the application did not do a
                        connect or bind.


       EOPNOTSUPP       Flow creation status for getsockopt() for SO_FLOW_SLA.
                        Flow creation is not supported for this socket.


       EALREADY         A flow with identical attributes exists.


       EINPROGRESS      A flow is being created.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i)


       ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityCommitted _ MT-Leve‐
       lAsync-Signal-Safe _ StandardSee standards(7).


SEE ALSO
       close(2), ioctl(2), read(2), write(2), bind(3C), connect(3C), getproto‐
       byname(3C),    recv(3C),     recvmsg(3C),     send(3C),     socket(3C),
       socket.h(3HEAD), tcp(4P), udp(4P), attributes(7), zones(7), flowadm(8),
       ipadm(8)


       Oracle Solaris 11.4 Tunable Parameters Reference Manual



Oracle Solaris 11.4               22 Jan 2018                   getsockopt(3C)
맨 페이지 내용의 저작권은 맨 페이지 작성자에게 있습니다.
RSS ATOM XHTML 5 CSS3