tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search     info

RFC 6458

 
 
 

Sockets API Extensions for the Stream Control Transmission Protocol (SCTP)

Part 3 of 4, p. 57 to 88
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 57 
7.  Common Operations for Both Styles

7.1.  send(), recv(), sendto(), and recvfrom()

   Applications can use send() and sendto() to transmit data to the peer
   of an SCTP endpoint.  recv() and recvfrom() can be used to receive
   data from the peer.

   The function prototypes are

   ssize_t send(int sd,
                const void *msg,
                size_t len,
                int flags);

   ssize_t sendto(int sd,
                  const void *msg,
                  size_t len,
                  int flags,
                  const struct sockaddr *to,
                  socklen_t tolen);

   ssize_t recv(int sd,
                void *buf,
                size_t len,
                int flags);

   ssize_t recvfrom(int sd,
                    void *buf,
                    size_t len,
                    int flags,
                    struct sockaddr *from,
                    socklen_t *fromlen);

   and the arguments are

   sd:  The socket descriptor of an SCTP endpoint.

   msg:  The message to be sent.

   len:  The size of the message or the size of the buffer.

   to:  One of the peer addresses of the association to be used to send
      the message.

   tolen:  The size of the address.

   buf:  The buffer to store a received message.

Top      Up      ToC       Page 58 
   from:  The buffer to store the peer address used to send the received
      message.

   fromlen:  The size of the from address.

   flags:  (described below).

   These calls give access to only basic SCTP protocol features.  If
   either peer in the association uses multiple streams, or sends
   unordered data, these calls will usually be inadequate and may
   deliver the data in unpredictable ways.

   SCTP has the concept of multiple streams in one association.  The
   above calls do not allow the caller to specify on which stream a
   message should be sent.  The system uses stream 0 as the default
   stream for send() and sendto().  recv() and recvfrom() return data
   from any stream, but the caller cannot distinguish the different
   streams.  This may result in data seeming to arrive out of order.
   Similarly, if a DATA chunk is sent unordered, recv() and recvfrom()
   provide no indication.

   SCTP is message based.  The msg buffer above in send() and sendto()
   is considered to be a single message.  This means that if the caller
   wants to send a message that is composed by several buffers, the
   caller needs to combine them before calling send() or sendto().
   Alternately, the caller can use sendmsg() to do that without
   combining them.  Sending a message using send() or sendto() is atomic
   unless explicit EOR marking is enabled on the socket specified by sd.
   Using sendto() on a non-connected one-to-one style socket for
   implicit connection setup may or may not work, depending on the SCTP
   implementation.  recv() and recvfrom() cannot distinguish message
   boundaries (i.e., there is no way to observe the MSG_EOR flag to
   detect partial delivery).

   When receiving, if the buffer supplied is not large enough to hold a
   complete message, the receive call acts like a stream socket and
   returns as much data as will fit in the buffer.

   Note that the send() and recv() calls may not be used for a one-to-
   many style socket.

   Note that if an application calls a send() or sendto() function with
   no user data, the SCTP implementation should reject the request with
   an appropriate error message.  An implementation is not allowed to
   send a DATA chunk with no user data [RFC4960].

Top      Up      ToC       Page 59 
7.2.  setsockopt() and getsockopt()

   Applications use setsockopt() and getsockopt() to set or retrieve
   socket options.  Socket options are used to change the default
   behavior of socket calls.  They are described in Section 8.

   The function prototypes are

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

   and

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

   and the arguments are

   sd:  The socket descriptor.

   level:  Set to IPPROTO_SCTP for all SCTP options.

   optname:  The option name.

   optval:  The buffer to store the value of the option.

   optlen:  The size of the buffer (or the length of the option
      returned).

   These functions return 0 on success and -1 in case of an error.

   All socket options set on a one-to-one style listening socket also
   apply to all future accepted sockets.  For one-to-many style sockets,
   often a socket option will pass a structure that includes an assoc_id
   field.  This field can be filled with the association identifier of a
   particular association and unless otherwise specified can be filled
   with one of the following constants:

   SCTP_FUTURE_ASSOC:  Specifies that only future associations created
      after this socket option will be affected by this call.

Top      Up      ToC       Page 60 
   SCTP_CURRENT_ASSOC:  Specifies that only currently existing
      associations will be affected by this call, and future
      associations will still receive the previous default value.

   SCTP_ALL_ASSOC:  Specifies that all current and future associations
      will be affected by this call.

7.3.  read() and write()

   Applications can use read() and write() to receive and send data from
   and to a peer.  They have the same semantics as recv() and send(),
   except that the flags parameter cannot be used.

7.4.  getsockname()

   Applications use getsockname() to retrieve the locally bound socket
   address of the specified socket.  This is especially useful if the
   caller let SCTP choose a local port.  This call is for single-homed
   endpoints.  It does not work well with multi-homed endpoints.  See
   Section 9.5 for a multi-homed version of the call.

   The function prototype is

   int getsockname(int sd,
                   struct sockaddr *address,
                   socklen_t *len);

   and the arguments are

   sd:  The socket descriptor to be queried.

   address:  On return, one locally bound address (chosen by the SCTP
      stack) is stored in this buffer.  If the socket is an IPv4 socket,
      the address will be IPv4.  If the socket is an IPv6 socket, the
      address will be either an IPv6 or IPv4 address.

   len:  The caller should set the length of the address here.  On
      return, this is set to the length of the returned address.

   getsockname() returns 0 on success and -1 in case of an error.

   If the actual length of the address is greater than the length of the
   supplied sockaddr structure, the stored address will be truncated.

   If the socket has not been bound to a local name, the value stored in
   the object pointed to by address is unspecified.

Top      Up      ToC       Page 61 
7.5.  Implicit Association Setup

   The application can begin sending and receiving data using the
   sendmsg()/recvmsg() or sendto()/recvfrom() calls, without going
   through any explicit association setup procedures (i.e., no connect()
   calls required).

   Whenever sendmsg() or sendto() is called and the SCTP stack at the
   sender finds that no association exists between the sender and the
   intended receiver (identified by the address passed either in the
   msg_name field of the msghdr structure in the sendmsg() call or the
   dest_addr field in the sendto() call), the SCTP stack will
   automatically set up an association to the intended receiver.

   Upon successful association setup, an SCTP_COMM_UP notification will
   be dispatched to the socket at both the sender and receiver side.
   This notification can be read by the recvmsg() system call (see
   Section 3.1.4).

   Note that if the SCTP stack at the sender side supports bundling, the
   first user message may be bundled with the COOKIE ECHO message
   [RFC4960].

   When the SCTP stack sets up a new association implicitly, the
   SCTP_INIT type ancillary data may also be passed along (see
   Section 5.3.1 for details of the data structures) to change some
   parameters used in setting up a new association.

   If this information is not present in the sendmsg() call, or if the
   implicit association setup is triggered by a sendto() call, the
   default association initialization parameters will be used.  These
   default association parameters may be set with respective
   setsockopt() calls or be left to the system defaults.

   Implicit association setup cannot be initiated by send() calls.

8.  Socket Options

   The following subsection describes various SCTP-level socket options
   that are common to both styles.  SCTP associations can be
   multi-homed.  Therefore, certain option parameters include a
   sockaddr_storage structure to select to which peer address the option
   should be applied.

   For the one-to-many style sockets, an sctp_assoc_t (association
   identifier) parameter is used to identify the association instance
   that the operation affects.  So it must be set when using this style.

Top      Up      ToC       Page 62 
   For the one-to-one style sockets and branched-off one-to-many style
   sockets (see Section 9.2), this association ID parameter is ignored.

   Note that socket- or IP-level options are set or retrieved per
   socket.  This means that for one-to-many style sockets, the options
   will be applied to all associations (similar to using SCTP_ALL_ASSOC
   as the association identifier) belonging to the socket.  For the one-
   to-one style, these options will be applied to all peer addresses of
   the association controlled by the socket.  Applications should be
   careful in setting those options.

   For some IP stacks, getsockopt() is read-only, so a new interface
   will be needed when information must be passed both into and out of
   the SCTP stack.  The syntax for sctp_opt_info() is

   int sctp_opt_info(int sd,
                     sctp_assoc_t id,
                     int opt,
                     void *arg,
                     socklen_t *size);

   The sctp_opt_info() call is a replacement for getsockopt() only and
   will not set any options associated with the specified socket.  A
   setsockopt() call must be used to set any writable option.

   For one-to-many style sockets, id specifies the association to query.
   For one-to-one style sockets, id is ignored.  For one-to-many style
   sockets, any association identifier in the structure provided as arg
   is ignored, and id takes precedence.

   Note that SCTP_CURRENT_ASSOC and SCTP_ALL_ASSOC cannot be used with
   sctp_opt_info() or in getsockopt() calls.  Using them will result in
   an error (returning -1 and errno set to EINVAL).  SCTP_FUTURE_ASSOC
   can be used to query information for future associations.

   The field opt specifies which SCTP socket option to get.  It can get
   any socket option currently supported that requests information
   (either read/write options or read-only) such as

   SCTP_RTOINFO

   SCTP_ASSOCINFO

   SCTP_PRIMARY_ADDR

   SCTP_PEER_ADDR_PARAMS

   SCTP_DEFAULT_SEND_PARAM

Top      Up      ToC       Page 63 
   SCTP_MAX_SEG

   SCTP_AUTH_ACTIVE_KEY

   SCTP_DELAYED_SACK

   SCTP_MAX_BURST

   SCTP_CONTEXT

   SCTP_EVENT

   SCTP_DEFAULT_SNDINFO

   SCTP_DEFAULT_PRINFO

   SCTP_STATUS

   SCTP_GET_PEER_ADDR_INFO

   SCTP_PEER_AUTH_CHUNKS

   SCTP_LOCAL_AUTH_CHUNKS

   The arg field is an option-specific structure buffer provided by the
   caller.  See the rest of this section for more information on these
   options and option-specific structures.

   sctp_opt_info() returns 0 on success, or on failure returns -1 and
   sets errno to the appropriate error code.

8.1.  Read/Write Options

8.1.1.  Retransmission Timeout Parameters (SCTP_RTOINFO)

   The protocol parameters used to initialize and limit the
   retransmission timeout (RTO) are tunable.  See [RFC4960] for more
   information on how these parameters are used in RTO calculation.

   The following structure is used to access and modify these
   parameters:

   struct sctp_rtoinfo {
     sctp_assoc_t srto_assoc_id;
     uint32_t srto_initial;
     uint32_t srto_max;
     uint32_t srto_min;
   };

Top      Up      ToC       Page 64 
   srto_assoc_id:  This parameter is ignored for one-to-one style
      sockets.  For one-to-many style sockets, the application may fill
      in an association identifier or SCTP_FUTURE_ASSOC.  It is an error
      to use SCTP_{CURRENT|ALL}_ASSOC in srto_assoc_id.

   srto_initial:  This parameter contains the initial RTO value.

   srto_max and srto_min:  These parameters contain the maximum and
      minimum bounds for all RTOs.

   All times are given in milliseconds.  A value of 0, when modifying
   the parameters, indicates that the current value should not be
   changed.

   To access or modify these parameters, the application should call
   getsockopt() or setsockopt(), respectively, with the option name
   SCTP_RTOINFO.

8.1.2.  Association Parameters (SCTP_ASSOCINFO)

   This option is used to both examine and set various association and
   endpoint parameters.  See [RFC4960] for more information on how these
   parameters are used.

   The following structure is used to access and modify these
   parameters:

   struct sctp_assocparams {
     sctp_assoc_t sasoc_assoc_id;
     uint16_t sasoc_asocmaxrxt;
     uint16_t sasoc_number_peer_destinations;
     uint32_t sasoc_peer_rwnd;
     uint32_t sasoc_local_rwnd;
     uint32_t sasoc_cookie_life;
   };

   sasoc_assoc_id:  This parameter is ignored for one-to-one style
      sockets.  For one-to-many style sockets, the application may fill
      in an association identifier or SCTP_FUTURE_ASSOC.  It is an error
      to use SCTP_{CURRENT|ALL}_ASSOC in sasoc_assoc_id.

   sasoc_asocmaxrxt:  This parameter contains the maximum retransmission
      attempts to make for the association.

   sasoc_number_peer_destinations:  This parameter is the number of
      destination addresses that the peer has.

Top      Up      ToC       Page 65 
   sasoc_peer_rwnd:  This parameter holds the current value of the
      peer's rwnd (reported in the last selective acknowledgment (SACK))
      minus any outstanding data (i.e., data in flight).

   sasoc_local_rwnd:  This parameter holds the last reported rwnd that
      was sent to the peer.

   sasoc_cookie_life:  This parameter is the association's cookie life
      value used when issuing cookies.

   The value of sasoc_peer_rwnd is meaningless when examining endpoint
   information (i.e., it is only valid when examining information on a
   specific association).

   All time values are given in milliseconds.  A value of 0, when
   modifying the parameters, indicates that the current value should not
   be changed.

   The values of sasoc_asocmaxrxt and sasoc_cookie_life may be set on
   either an endpoint or association basis.  The rwnd and destination
   counts (sasoc_number_peer_destinations, sasoc_peer_rwnd,
   sasoc_local_rwnd) are not settable, and any value placed in these is
   ignored.

   To access or modify these parameters, the application should call
   getsockopt() or setsockopt(), respectively, with the option name
   SCTP_ASSOCINFO.

   The maximum number of retransmissions before an address is considered
   unreachable is also tunable, but is address-specific, so it is
   covered in a separate option.  If an application attempts to set the
   value of the association's maximum retransmission parameter to more
   than the sum of all maximum retransmission parameters, setsockopt()
   may return an error.  The reason for this, from Section 8.2 of
   [RFC4960], is as follows:

      Note: When configuring the SCTP endpoint, the user should avoid
      having the value of 'Association.Max.Retrans' (sasoc_maxrxt in
      this option) larger than the summation of the 'Path.Max.Retrans'
      (see spp_pathmaxrxt in Section 8.1.12) of all of the destination
      addresses for the remote endpoint.  Otherwise, all of the
      destination addresses may become inactive while the endpoint still
      considers the peer endpoint reachable.

Top      Up      ToC       Page 66 
8.1.3.  Initialization Parameters (SCTP_INITMSG)

   Applications can specify protocol parameters for the default
   association initialization.  The structure used to access and modify
   these parameters is defined in Section 5.3.1.  The option name
   argument to setsockopt() and getsockopt() is SCTP_INITMSG.

   Setting initialization parameters is effective only on an unconnected
   socket (for one-to-many style sockets, only future associations are
   affected by the change).

8.1.4.  SO_LINGER

   An application can use this option to perform the SCTP ABORT
   primitive.  This option affects all associations related to the
   socket.

   The linger option structure is

   struct linger {
     int l_onoff;  /* option on/off */
     int l_linger; /* linger time   */
   };

   To enable the option, set l_onoff to 1.  If the l_linger value is set
   to 0, calling close() is the same as the ABORT primitive.  If the
   value is set to a negative value, the setsockopt() call will return
   an error.  If the value is set to a positive value linger_time, the
   close() can be blocked for at most linger_time.  Please note that the
   time unit is in seconds, according to POSIX, but might be different
   on specific platforms.  If the graceful shutdown phase does not
   finish during this period, close() will return, but the graceful
   shutdown phase will continue in the system.

   Note that this is a socket-level option, not an SCTP-level option.
   When using this option, an application must specify a level of
   SOL_SOCKET in the call.

8.1.5.  SCTP_NODELAY

   This option turns on/off any Nagle-like algorithm.  This means that
   packets are generally sent as soon as possible, and no unnecessary
   delays are introduced, at the cost of more packets in the network.
   In particular, not using any Nagle-like algorithm might reduce the
   bundling of small user messages in cases where this would require an
   additional delay.

   Turning this option on disables any Nagle-like algorithm.

Top      Up      ToC       Page 67 
   This option expects an integer boolean flag, where a non-zero value
   turns on the option, and a zero value turns off the option.

8.1.6.  SO_RCVBUF

   This option sets the receive buffer size in octets.  For SCTP one-to-
   one style sockets, this option controls the receiver window size.
   For one-to-many style sockets, the meaning is implementation
   dependent.  It might control the receive buffer for each association
   bound to the socket descriptor, or it might control the receive
   buffer for the whole socket.  This option expects an integer.

   Note that this is a socket-level option, not an SCTP-level option.
   When using this option, an application must specify a level of
   SOL_SOCKET in the call.

8.1.7.  SO_SNDBUF

   This option sets the send buffer size.  For SCTP one-to-one style
   sockets, this option controls the amount of data SCTP may have
   waiting in internal buffers to be sent.  This option therefore bounds
   the maximum size of data that can be sent in a single send call.  For
   one-to-many style sockets, the effect is the same, except that it
   applies to one or all associations (see Section 3.3) bound to the
   socket descriptor used in the setsockopt() or getsockopt() call.  The
   option applies to each association's window size separately.  This
   option expects an integer.

   Note that this is a socket-level option, not an SCTP-level option.
   When using this option, an application must specify a level of
   SOL_SOCKET in the call.

8.1.8.  Automatic Close of Associations (SCTP_AUTOCLOSE)

   This socket option is applicable to the one-to-many style socket
   only.  When set, it will cause associations that are idle for more
   than the specified number of seconds to automatically close using the
   graceful shutdown procedure.  An idle association is defined as an
   association that has not sent or received user data.  The special
   value of '0' indicates that no automatic close of any association
   should be performed; this is the default value.  This option expects
   an integer defining the number of seconds of idle time before an
   association is closed.

Top      Up      ToC       Page 68 
   An application using this option should enable the ability to receive
   the association change notification.  This is the only mechanism by
   which an application is informed about the closing of an association.
   After an association is closed, the association identifier assigned
   to it can be reused.  An application should be aware of this to avoid
   the possible problem of sending data to an incorrect peer endpoint.

8.1.9.  Set Primary Address (SCTP_PRIMARY_ADDR)

   This option requests that the local SCTP stack uses the enclosed peer
   address as the association's primary.  The enclosed address must be
   one of the association peer's addresses.

   The following structure is used to make a set peer primary request:

   struct sctp_setprim {
     sctp_assoc_t ssp_assoc_id;
     struct sockaddr_storage ssp_addr;
   };

   ssp_assoc_id:  This parameter is ignored for one-to-one style
      sockets.  For one-to-many style sockets, it identifies the
      association for this request.  Note that the special sctp_assoc_t
      SCTP_{FUTURE|ALL|CURRENT}_ASSOC are not allowed.

   ssp_addr:  This parameter is the address to set as primary.  No
      wildcard address is allowed.

8.1.10.  Set Adaptation Layer Indicator (SCTP_ADAPTATION_LAYER)

   This option requests that the local endpoint set the specified
   Adaptation Layer Indication parameter for all future INIT and
   INIT-ACK exchanges.

   The following structure is used to access and modify this parameter:

   struct sctp_setadaptation {
     uint32_t   ssb_adaptation_ind;
   };

   ssb_adaptation_ind:  The adaptation layer indicator that will be
      included in any outgoing Adaptation Layer Indication parameter.

8.1.11.  Enable/Disable Message Fragmentation (SCTP_DISABLE_FRAGMENTS)

   This option is an on/off flag and is passed as an integer, where a
   non-zero is on and a zero is off.  If enabled, no SCTP message
   fragmentation will be performed.  The effect of enabling this option

Top      Up      ToC       Page 69 
   is that if a message being sent exceeds the current Path MTU (PMTU)
   size, the message will not be sent and instead an error will be
   indicated to the user.  If this option is disabled (the default),
   then a message exceeding the size of the PMTU will be fragmented and
   reassembled by the peer.

8.1.12.  Peer Address Parameters (SCTP_PEER_ADDR_PARAMS)

   Applications can enable or disable heartbeats for any peer address of
   an association, modify an address's heartbeat interval, force a
   heartbeat to be sent immediately, and adjust the address's maximum
   number of retransmissions sent before an address is considered
   unreachable.

   The following structure is used to access and modify an address's
   parameters:

   struct sctp_paddrparams {
     sctp_assoc_t spp_assoc_id;
     struct sockaddr_storage spp_address;
     uint32_t spp_hbinterval;
     uint16_t spp_pathmaxrxt;
     uint32_t spp_pathmtu;
     uint32_t spp_flags;
     uint32_t spp_ipv6_flowlabel;
     uint8_t  spp_dscp;
   };

   spp_assoc_id:  This parameter is ignored for one-to-one style
      sockets.  For one-to-many style sockets, the application may fill
      in an association identifier or SCTP_FUTURE_ASSOC for this query.
      It is an error to use SCTP_{CURRENT|ALL}_ASSOC in spp_assoc_id.

   spp_address:  This specifies which address is of interest.  If a
      wildcard address is provided, it applies to all current and future
      paths.

   spp_hbinterval:  This contains the value of the heartbeat interval,
      in milliseconds (HB.Interval in [RFC4960]).  Note that unless the
      spp_flags field is set to SPP_HB_ENABLE, the value of this field
      is ignored.  Note also that a value of zero indicates that the
      current setting should be left unchanged.  To set an actual value
      of zero, the SPP_HB_TIME_IS_ZERO flag should be used.  Even when
      it is set to 0, it does not mean that SCTP will continuously send
      out heartbeats, since the actual interval also includes the
      current RTO and jitter (see Section 8.3 of [RFC4960]).

Top      Up      ToC       Page 70 
   spp_pathmaxrxt:  This contains the maximum number of retransmissions
      before this address shall be considered unreachable.  Note that a
      value of zero indicates that the current setting should be left
      unchanged.

   spp_pathmtu:  This field contains the current Path MTU of the peer
      address.  It is the number of bytes available in an SCTP packet
      for chunks.  Providing a value of 0 does not change the current
      setting.  If a positive value is provided and SPP_PMTUD_DISABLE is
      set in the spp_flags field, the given value is used as the Path
      MTU.  If SPP_PMTUD_ENABLE is set in the spp_flags field, the
      spp_pathmtu field is ignored.

   spp_flags:  These flags are used to control various features on an
      association.  The flag field is a bitmask that may contain zero or
      more of the following options:

      SPP_HB_ENABLE:  This field enables heartbeats on the specified
         address.

      SPP_HB_DISABLE:  This field disables heartbeats on the specified
         address.  Note that SPP_HB_ENABLE and SPP_HB_DISABLE are
         mutually exclusive; only one of these two should be specified.
         Enabling both fields will yield undetermined results.

      SPP_HB_DEMAND:  This field requests that a user-initiated
         heartbeat be made immediately.  This must not be used in
         conjunction with a wildcard address.

      SPP_HB_TIME_IS_ZERO:  This field specifies that the time for
         heartbeat delay is to be set to 0 milliseconds.

      SPP_PMTUD_ENABLE:  This field will enable PMTU discovery on the
         specified address.

      SPP_PMTUD_DISABLE:  This field will disable PMTU discovery on the
         specified address.  Note that if the address field is empty,
         then all addresses on the association are affected.  Note also
         that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually
         exclusive.  Enabling both fields will yield undetermined
         results.

      SPP_IPV6_FLOWLABEL:  Setting this flag enables the setting of the
         IPV6 flow label value.  The value is contained in the
         spp_ipv6_flowlabel field.

Top      Up      ToC       Page 71 
         Upon retrieval, this flag will be set to indicate that the
         spp_ipv6_flowlabel field has a valid value returned.  If a
         specific destination address is set (in the spp_address field),
         then the value returned is that of the address.  If just an
         association is specified (and no address), then the
         association's default flow label is returned.  If neither an
         association nor a destination is specified, then the socket's
         default flow label is returned.  For non-IPv6 sockets, this
         flag will be left cleared.

      SPP_DSCP:  Setting this flag enables the setting of the
         Differentiated Services Code Point (DSCP) value associated with
         either the association or a specific address.  The value is
         obtained in the spp_dscp field.

         Upon retrieval, this flag will be set to indicate that the
         spp_dscp field has a valid value returned.  If a specific
         destination address is set when called (in the spp_address
         field), then that specific destination address's DSCP value is
         returned.  If just an association is specified, then the
         association's default DSCP is returned.  If neither an
         association nor a destination is specified, then the socket's
         default DSCP is returned.

   spp_ipv6_flowlabel:  This field is used in conjunction with the
      SPP_IPV6_FLOWLABEL flag and contains the IPv6 flow label.  The 20
      least significant bits are used for the flow label.  This setting
      has precedence over any IPv6-layer setting.

   spp_dscp:  This field is used in conjunction with the SPP_DSCP flag
      and contains the DSCP.  The 6 most significant bits are used for
      the DSCP.  This setting has precedence over any IPv4- or IPv6-
      layer setting.

   Please note that changing the flow label or DSCP value will affect
   all packets sent by the SCTP stack after setting these parameters.
   The flow label might also be set via the sin6_flowinfo field of the
   sockaddr_in6 structure.

8.1.13.  Set Default Send Parameters (SCTP_DEFAULT_SEND_PARAM) -
         DEPRECATED

   Please note that this option is deprecated.  SCTP_DEFAULT_SNDINFO
   (Section 8.1.31) should be used instead.

   Applications that wish to use the sendto() system call may wish to
   specify a default set of parameters that would normally be supplied
   through the inclusion of ancillary data.  This socket option allows

Top      Up      ToC       Page 72 
   such an application to set the default sctp_sndrcvinfo structure.
   The application that wishes to use this socket option simply passes
   the sctp_sndrcvinfo structure (defined in Section 5.3.2) to this
   call.  The input parameters accepted by this call include
   sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context, and
   sinfo_timetolive.  The sinfo_flags field is composed of a bitwise OR
   of SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL.  The sinfo_assoc_id
   field specifies the association to which to apply the parameters.
   For a one-to-many style socket, any of the predefined constants are
   also allowed in this field.  The field is ignored for one-to-one
   style sockets.

8.1.14.  Set Notification and Ancillary Events (SCTP_EVENTS) -
         DEPRECATED

   This socket option is used to specify various notifications and
   ancillary data the user wishes to receive.  Please see Section 6.2.1
   for a full description of this option and its usage.  Note that this
   option is considered deprecated and is present for backward
   compatibility.  New applications should use the SCTP_EVENT option.
   See Section 6.2.2 for a full description of that option as well.

8.1.15.  Set/Clear IPv4 Mapped Addresses (SCTP_I_WANT_MAPPED_V4_ADDR)

   This socket option is a boolean flag that turns on or off the mapping
   of IPv4 addresses.  If this option is turned on, then IPv4 addresses
   will be mapped to IPv6 representation.  If this option is turned off,
   then no mapping will be done of IPv4 addresses, and a user will
   receive both PF_INET6 and PF_INET type addresses on the socket.  See
   [RFC3542] for more details on mapped IPv6 addresses.

   If this socket option is used on a socket of type PF_INET, an error
   is returned.

   By default, this option is turned off and expects an integer to be
   passed where a non-zero value turns on the option and a zero value
   turns off the option.

8.1.16.  Get or Set the Maximum Fragmentation Size (SCTP_MAXSEG)

   This option will get or set the maximum size to put in any outgoing
   SCTP DATA chunk.  If a message is larger than this maximum size, it
   will be fragmented by SCTP into the specified size.  Note that the
   underlying SCTP implementation may fragment into smaller sized chunks
   when the PMTU of the underlying association is smaller than the value
   set by the user.  The default value for this option is '0', which
   indicates that the user is not limiting fragmentation and only the
   PMTU will affect SCTP's choice of DATA chunk size.  Note also that

Top      Up      ToC       Page 73 
   values set larger than the maximum size of an IP datagram will
   effectively let SCTP control fragmentation (i.e., the same as setting
   this option to 0).

   The following structure is used to access and modify this parameter:

   struct sctp_assoc_value {
     sctp_assoc_t assoc_id;
     uint32_t assoc_value;
   };

   assoc_id:  This parameter is ignored for one-to-one style sockets.
      For one-to-many style sockets, this parameter indicates upon which
      association the user is performing an action.  It is an error to
      use SCTP_{CURRENT|ALL}_ASSOC in assoc_id.

   assoc_value:  This parameter specifies the maximum size in bytes.

8.1.17.  Get or Set the List of Supported HMAC Identifiers
         (SCTP_HMAC_IDENT)

   This option gets or sets the list of Hashed Message Authentication
   Code (HMAC) algorithms that the local endpoint requires the peer
   to use.

   The following structure is used to get or set these identifiers:

   struct sctp_hmacalgo {
     uint32_t shmac_number_of_idents;
     uint16_t shmac_idents[];
   };

   shmac_number_of_idents:  This field gives the number of elements
      present in the array shmac_idents.

   shmac_idents:  This parameter contains an array of HMAC identifiers
      that the local endpoint is requesting the peer to use, in priority
      order.  The following identifiers are valid:

      *  SCTP_AUTH_HMAC_ID_SHA1

      *  SCTP_AUTH_HMAC_ID_SHA256

   Note that the list supplied must include SCTP_AUTH_HMAC_ID_SHA1 and
   may include any of the other values in its preferred order (lowest
   list position has the highest preference in algorithm selection).

Top      Up      ToC       Page 74 
   Note also that the lack of SCTP_AUTH_HMAC_ID_SHA1, or the inclusion
   of an unknown HMAC identifier (including optional identifiers unknown
   to the implementation), will cause the set option to fail and return
   an error.

8.1.18.  Get or Set the Active Shared Key (SCTP_AUTH_ACTIVE_KEY)

   This option will get or set the active shared key to be used to build
   the association shared key.

   The following structure is used to access and modify these
   parameters:

   struct sctp_authkeyid {
     sctp_assoc_t scact_assoc_id;
     uint16_t scact_keynumber;
   };

   scact_assoc_id:  This parameter sets the active key of the specified
      association.  The special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be
      used.  For one-to-one style sockets, this parameter is ignored.
      Note, however, that this option will set the active key on the
      association if the socket is connected; otherwise, this option
      will set the default active key for the endpoint.

   scact_keynumber:  This parameter is the shared key identifier that
      the application is requesting to become the active shared key to
      be used for sending authenticated chunks.  The key identifier must
      correspond to an existing shared key.  Note that shared key
      identifier '0' defaults to a null key.

   When used with setsockopt(), the SCTP implementation must use the
   indicated shared key identifier for all messages being given to an
   SCTP implementation via a send call after the setsockopt() call,
   until changed again.  Therefore, the SCTP implementation must not
   bundle user messages that should be authenticated using different
   shared key identifiers.

   Initially, the key with key identifier 0 is the active key.

8.1.19.  Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK)

   This option will affect the way delayed SACKs are performed.  This
   option allows the application to get or set the delayed SACK time, in
   milliseconds.  It also allows changing the delayed SACK frequency.
   Changing the frequency to 1 disables the delayed SACK algorithm.
   Note that if sack_delay or sack_freq is 0 when setting this option,
   the current values will remain unchanged.

Top      Up      ToC       Page 75 
   The following structure is used to access and modify these
   parameters:

   struct sctp_sack_info {
     sctp_assoc_t sack_assoc_id;
     uint32_t sack_delay;
     uint32_t sack_freq;
   };

   sack_assoc_id:  This parameter is ignored for one-to-one style
      sockets.  For one-to-many style sockets, this parameter indicates
      upon which association the user is performing an action.  The
      special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used.

   sack_delay:  This parameter contains the number of milliseconds the
      user is requesting that the delayed SACK timer be set to.  Note
      that this value is defined in [RFC4960] to be between 200 and 500
      milliseconds.

   sack_freq:  This parameter contains the number of packets that must
      be received before a SACK is sent without waiting for the delay
      timer to expire.  The default value is 2; setting this value to 1
      will disable the delayed SACK algorithm.

8.1.20.  Get or Set Fragmented Interleave (SCTP_FRAGMENT_INTERLEAVE)

   Fragmented interleave controls how the presentation of messages
   occurs for the message receiver.  There are three levels of fragment
   interleave defined.  Two of the levels affect one-to-one style
   sockets, while one-to-many style sockets are affected by all three
   levels.

   This option takes an integer value.  It can be set to a value of 0,
   1, or 2.  Attempting to set this level to other values will return an
   error.

   Setting the three levels provides the following receiver
   interactions:

   level 0:  Prevents the interleaving of any messages.  This means that
      when a partial delivery begins, no other messages will be received
      except the message being partially delivered.  If another message
      arrives on a different stream (or association) that could be
      delivered, it will be blocked waiting for the user to read all of
      the partially delivered message.

Top      Up      ToC       Page 76 
   level 1:  Allows interleaving of messages that are from different
      associations.  For one-to-one style sockets, level 0 and level 1
      thus have the same meaning, since a one-to-one style socket always
      receives messages from the same association.  Note that setting a
      one-to-many style socket to this level may cause multiple partial
      deliveries from different associations, but for any given
      association, only one message will be delivered until all parts of
      a message have been delivered.  This means that one large message,
      being read with an association identifier of "X", will block other
      messages from association "X" from being delivered.

   level 2:  Allows complete interleaving of messages.  This level
      requires that the sender not only carefully observe the peer
      association identifier (or address) but also pay careful attention
      to the stream number.  With this option enabled, a partially
      delivered message may begin being delivered for association "X"
      stream "Y", and the next subsequent receive may return a message
      from association "X" stream "Z".  Note that no other messages
      would be delivered for association "X" stream "Y" until all of
      stream "Y"'s partially delivered message was read.  Note that this
      option also affects one-to-one style sockets.  Also note that for
      one-to-many style sockets, not only another stream's message from
      the same association may be delivered upon the next receive, but
      some other association's message may also be delivered upon the
      next receive.

   An implementation should default one-to-many style sockets to level
   1, because otherwise, it is possible that a peer could begin sending
   a partial message and thus block all other peers from sending data.
   However, a setting of level 2 requires that the application not only
   be aware of the association (via the association identifier or peer's
   address) but also the stream number.  The stream number is not
   present unless the user has subscribed to the sctp_data_io_event (see
   Section 6.2), which is deprecated, or has enabled the
   SCTP_RECVRCVINFO socket option (see Section 8.1.29).  This is also
   why we recommend that one-to-one style sockets be defaulted to level
   0 (level 1 for one-to-one style sockets has no effect).  Note that an
   implementation should return an error if an application attempts to
   set the level to 2 and has not subscribed to the sctp_data_io_event
   event, which is deprecated, or has enabled the SCTP_RECVRCVINFO
   socket option.

   For applications that have subscribed to events, those events appear
   in the normal socket buffer data stream.  This means that unless the
   user has set the fragmentation interleave level to 0, notifications
   may also be interleaved with partially delivered messages.

Top      Up      ToC       Page 77 
8.1.21.  Set or Get the SCTP Partial Delivery Point
         (SCTP_PARTIAL_DELIVERY_POINT)

   This option will set or get the SCTP partial delivery point.  This
   point is the size of a message where the partial delivery API will be
   invoked to help free up rwnd space for the peer.  Setting this to a
   lower value will cause partial deliveries to happen more often.  This
   option expects an integer that sets or gets the partial delivery
   point in bytes.  Note also that the call will fail if the user
   attempts to set this value larger than the socket receive buffer
   size.

   Note that any single message having a length smaller than or equal to
   the SCTP partial delivery point will be delivered in a single read
   call as long as the user-provided buffer is large enough to hold the
   message.

8.1.22.  Set or Get the Use of Extended Receive Info
         (SCTP_USE_EXT_RCVINFO) - DEPRECATED

   This option will enable or disable the use of the extended version of
   the sctp_sndrcvinfo structure.  If this option is disabled, then the
   normal sctp_sndrcvinfo structure is returned in all receive message
   calls.  If this option is enabled, then the sctp_extrcvinfo structure
   is returned in all receive message calls.  The default is off.

   Note that the sctp_extrcvinfo structure is never used in any send
   call.

   This option is present for compatibility with older applications and
   is deprecated.  Future applications should use SCTP_NXTINFO to
   retrieve this same information via ancillary data.

8.1.23.  Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF)

   This option will enable or disable the use of the automatic
   generation of ASCONF chunks to add and delete addresses to an
   existing association.  Note that this option has two caveats, namely
   a) it only affects sockets that are bound to all addresses available
   to the SCTP stack, and b) the system administrator may have an
   overriding control that turns the ASCONF feature off no matter what
   setting the socket option may have.

   This option expects an integer boolean flag, where a non-zero value
   turns on the option, and a zero value turns off the option.

Top      Up      ToC       Page 78 
8.1.24.  Set or Get the Maximum Burst (SCTP_MAX_BURST)

   This option will allow a user to change the maximum burst of packets
   that can be emitted by this association.  Note that the default value
   is 4, and some implementations may restrict this setting so that it
   can only be lowered to positive values.

   To set or get this option, the user fills in the following structure:

   struct sctp_assoc_value {
     sctp_assoc_t assoc_id;
     uint32_t assoc_value;
   };

   assoc_id:  This parameter is ignored for one-to-one style sockets.
      For one-to-many style sockets, this parameter indicates upon which
      association the user is performing an action.  The special
      SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used.

   assoc_value:  This parameter contains the maximum burst.  Setting the
      value to 0 disables burst mitigation.

8.1.25.  Set or Get the Default Context (SCTP_CONTEXT)

   The context field in the sctp_sndrcvinfo structure is normally only
   used when a failed message is retrieved holding the value that was
   sent down on the actual send call.  This option allows the setting,
   on an association basis, of a default context that will be received
   on reading messages from the peer.  This is especially helpful for an
   application when using one-to-many style sockets to keep some
   reference to an internal state machine that is processing messages on
   the association.  Note that the setting of this value only affects
   received messages from the peer and does not affect the value that is
   saved with outbound messages.

   To set or get this option, the user fills in the following structure:

   struct sctp_assoc_value {
     sctp_assoc_t assoc_id;
     uint32_t assoc_value;
   };

   assoc_id:  This parameter is ignored for one-to-one style sockets.
      For one-to-many style sockets, this parameter indicates upon which
      association the user is performing an action.  The special
      SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used.

   assoc_value:  This parameter contains the context.

Top      Up      ToC       Page 79 
8.1.26.  Enable or Disable Explicit EOR Marking (SCTP_EXPLICIT_EOR)

   This boolean flag is used to enable or disable explicit end of record
   (EOR) marking.  When this option is enabled, a user may make multiple
   send system calls to send a record and must indicate that they are
   finished sending a particular record by including the SCTP_EOR flag.
   If this boolean flag is disabled, then each individual send system
   call is considered to have an SCTP_EOR indicator set on it implicitly
   without the user having to explicitly add this flag.  The default
   is off.

   This option expects an integer boolean flag, where a non-zero value
   turns on the option, and a zero value turns off the option.

8.1.27.  Enable SCTP Port Reusage (SCTP_REUSE_PORT)

   This option only supports one-to-one style SCTP sockets.  If used on
   a one-to-many style SCTP socket, an error is indicated.

   This option expects an integer boolean flag, where a non-zero value
   turns on the option, and a zero value turns off the option.

   This socket option must not be used after calling bind() or
   sctp_bindx() for a one-to-one style SCTP socket.  If using bind() or
   sctp_bindx() on a socket with the SCTP_REUSE_PORT option, all other
   SCTP sockets bound to the same port must have set the SCTP_REUSE_PORT
   option.  Calling bind() or sctp_bindx() for a socket without having
   set the SCTP_REUSE_PORT option will fail if there are other sockets
   bound to the same port.  At most one socket being bound to the same
   port may be listening.

   It should be noted that the behavior of the socket-level socket
   option to reuse ports and/or addresses for SCTP sockets is
   unspecified.

8.1.28.  Set Notification Event (SCTP_EVENT)

   This socket option is used to set a specific notification option.
   Please see Section 6.2.2 for a full description of this option and
   its usage.

8.1.29.  Enable or Disable the Delivery of SCTP_RCVINFO as Ancillary
         Data (SCTP_RECVRCVINFO)

   Setting this option specifies that SCTP_RCVINFO (defined in
   Section 5.3.5) is returned as ancillary data by recvmsg().

Top      Up      ToC       Page 80 
   This option expects an integer boolean flag, where a non-zero value
   turns on the option, and a zero value turns off the option.

8.1.30.  Enable or Disable the Delivery of SCTP_NXTINFO as Ancillary
         Data (SCTP_RECVNXTINFO)

   Setting this option specifies that SCTP_NXTINFO (defined in
   Section 5.3.6) is returned as ancillary data by recvmsg().

   This option expects an integer boolean flag, where a non-zero value
   turns on the option, and a zero value turns off the option.

8.1.31.  Set Default Send Parameters (SCTP_DEFAULT_SNDINFO)

   Applications that wish to use the sendto() system call may wish to
   specify a default set of parameters that would normally be supplied
   through the inclusion of ancillary data.  This socket option allows
   such an application to set the default sctp_sndinfo structure.  The
   application that wishes to use this socket option simply passes the
   sctp_sndinfo structure (defined in Section 5.3.4) to this call.  The
   input parameters accepted by this call include snd_sid, snd_flags,
   snd_ppid, and snd_context.  The snd_flags parameter is composed of a
   bitwise OR of SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL.  The
   snd_assoc_id field specifies the association to which to apply the
   parameters.  For a one-to-many style socket, any of the predefined
   constants are also allowed in this field.  The field is ignored for
   one-to-one style sockets.

8.1.32.  Set Default PR-SCTP Parameters (SCTP_DEFAULT_PRINFO)

   This option sets and gets the default parameters for PR-SCTP.  They
   can be overwritten by specific information provided in send calls.

   The following structure is used to access and modify these
   parameters:

   struct sctp_default_prinfo {
     uint16_t pr_policy;
     uint32_t pr_value;
     sctp_assoc_t pr_assoc_id;
   };

   pr_policy:  This field is the same as that described in
      Section 5.3.7.

   pr_value:  This field is the same as that described in Section 5.3.7.

Top      Up      ToC       Page 81 
   pr_assoc_id:  This field is ignored for one-to-one style sockets.
      For one-to-many style sockets, pr_assoc_id can be a particular
      association identifier or SCTP_{FUTURE|CURRENT|ALL}_ASSOC.

8.2.  Read-Only Options

   The options defined in this subsection are read-only.  Using this
   option in a setsockopt() call will result in an error indicating
   EOPNOTSUPP.

8.2.1.  Association Status (SCTP_STATUS)

   Applications can retrieve current status information about an
   association, including association state, peer receiver window size,
   number of unacknowledged DATA chunks, and number of DATA chunks
   pending receipt.  This information is read-only.

   The following structure is used to access this information:

   struct sctp_status {
     sctp_assoc_t sstat_assoc_id;
     int32_t  sstat_state;
     uint32_t sstat_rwnd;
     uint16_t sstat_unackdata;
     uint16_t sstat_penddata;
     uint16_t sstat_instrms;
     uint16_t sstat_outstrms;
     uint32_t sstat_fragmentation_point;
     struct sctp_paddrinfo sstat_primary;
   };

   sstat_assoc_id:  This parameter is ignored for one-to-one style
      sockets.  For one-to-many style sockets, it holds the identifier
      for the association.  All notifications for a given association
      have the same association identifier.  The special SCTP_{FUTURE|
      CURRENT|ALL}_ASSOC cannot be used.

   sstat_state:  This contains the association's current state, i.e.,
      one of the following values:

      *  SCTP_CLOSED

      *  SCTP_BOUND

      *  SCTP_LISTEN

      *  SCTP_COOKIE_WAIT

Top      Up      ToC       Page 82 
      *  SCTP_COOKIE_ECHOED

      *  SCTP_ESTABLISHED

      *  SCTP_SHUTDOWN_PENDING

      *  SCTP_SHUTDOWN_SENT

      *  SCTP_SHUTDOWN_RECEIVED

      *  SCTP_SHUTDOWN_ACK_SENT

   sstat_rwnd:  This contains the association peer's current receiver
      window size.

   sstat_unackdata:  This is the number of unacknowledged DATA chunks.

   sstat_penddata:  This is the number of DATA chunks pending receipt.

   sstat_instrms:  This is the number of streams that the peer will be
      using outbound.

   sstat_outstrms:  This is the number of outbound streams that the
      endpoint is allowed to use.

   sstat_fragmentation_point:  This is the size at which SCTP
      fragmentation will occur.

   sstat_primary:  This is information on the current primary peer
      address.

   To access these status values, the application calls getsockopt()
   with the option name SCTP_STATUS.

8.2.2.  Peer Address Information (SCTP_GET_PEER_ADDR_INFO)

   Applications can retrieve information about a specific peer address
   of an association, including its reachability state, congestion
   window, and retransmission timer values.  This information is
   read-only.

   The following structure is used to access this information:

   struct sctp_paddrinfo {
     sctp_assoc_t spinfo_assoc_id;
     struct sockaddr_storage spinfo_address;
     int32_t  spinfo_state;
     uint32_t spinfo_cwnd;

Top      Up      ToC       Page 83 
     uint32_t spinfo_srtt;
     uint32_t spinfo_rto;
     uint32_t spinfo_mtu;
   };

   spinfo_assoc_id:  This parameter is ignored for one-to-one style
      sockets.

      For one-to-many style sockets, this field may be filled by the
      application, and if so, this field will have priority in looking
      up the association instead of using the address specified in
      spinfo_address.  Note that if the address does not belong to the
      association specified, then this call will fail.  If the
      application does not fill in the spinfo_assoc_id, then the address
      will be used to look up the association, and on return, this field
      will have the valid association identifier.  In other words, this
      call can be used to translate an address into an association
      identifier.  Note that the predefined constants are not allowed
      for this option.

   spinfo_address:  This is filled by the application and contains the
      peer address of interest.

   spinfo_state:  This contains the peer address's state:

      SCTP_UNCONFIRMED:  This is the initial state of a peer address.

      SCTP_ACTIVE:  This state is entered the first time after path
         verification.  It can also be entered if the state is
         SCTP_INACTIVE and the path supervision detects that the peer
         address is reachable again.

      SCTP_INACTIVE:  This state is entered whenever a path failure is
         detected.

   spinfo_cwnd:  This contains the peer address's current congestion
      window.

   spinfo_srtt:  This contains the peer address's current smoothed
      round-trip time calculation in milliseconds.

   spinfo_rto:  This contains the peer address's current retransmission
      timeout value in milliseconds.

   spinfo_mtu:  This is the current Path MTU of the peer address.  It is
      the number of bytes available in an SCTP packet for chunks.

Top      Up      ToC       Page 84 
8.2.3.  Get the List of Chunks the Peer Requires to Be Authenticated
        (SCTP_PEER_AUTH_CHUNKS)

   This option gets a list of chunk types (see [RFC4960]) for a
   specified association that the peer requires to be received
   authenticated only.

   The following structure is used to access these parameters:

   struct sctp_authchunks {
     sctp_assoc_t gauth_assoc_id;
     uint32_t gauth_number_of_chunks
     uint8_t  gauth_chunks[];
   };

   gauth_assoc_id:  This parameter indicates for which association the
      user is requesting the list of peer-authenticated chunks.  For
      one-to-one style sockets, this parameter is ignored.  Note that
      the predefined constants are not allowed with this option.

   gauth_number_of_chunks:  This parameter gives the number of elements
      in the array gauth_chunks.

   gauth_chunks:  This parameter contains an array of chunk types that
      the peer is requesting to be authenticated.  If the passed-in
      buffer size is not large enough to hold the list of chunk types,
      ENOBUFS is returned.

8.2.4.  Get the List of Chunks the Local Endpoint Requires to Be
        Authenticated (SCTP_LOCAL_AUTH_CHUNKS)

   This option gets a list of chunk types (see [RFC4960]) for a
   specified association that the local endpoint requires to be received
   authenticated only.

   The following structure is used to access these parameters:

   struct sctp_authchunks {
     sctp_assoc_t gauth_assoc_id;
     uint32_t gauth_number_of_chunks;
     uint8_t  gauth_chunks[];
   };

   gauth_assoc_id:  This parameter is ignored for one-to-one style
      sockets.  For one-to-many style sockets, the application may fill
      in an association identifier or SCTP_FUTURE_ASSOC.  It is an error
      to use SCTP_{CURRENT|ALL}_ASSOC in gauth_assoc_id.

Top      Up      ToC       Page 85 
   gauth_number_of_chunks:  This parameter gives the number of elements
      in the array gauth_chunks.

   gauth_chunks:  This parameter contains an array of chunk types that
      the local endpoint is requesting to be authenticated.  If the
      passed-in buffer is not large enough to hold the list of chunk
      types, ENOBUFS is returned.

8.2.5.  Get the Current Number of Associations (SCTP_GET_ASSOC_NUMBER)

   This option gets the current number of associations that are attached
   to a one-to-many style socket.  The option value is an uint32_t.
   Note that this number is only a snapshot.  This means that the number
   of associations may have changed when the caller gets back the option
   result.

   For a one-to-one style socket, this socket option results in an
   error.

8.2.6.  Get the Current Identifiers of Associations
        (SCTP_GET_ASSOC_ID_LIST)

   This option gets the current list of SCTP association identifiers of
   the SCTP associations handled by a one-to-many style socket.

   The option value has the structure

   struct sctp_assoc_ids {
     uint32_t gaids_number_of_ids;
     sctp_assoc_t gaids_assoc_id[];
   };

   The caller must provide a large enough buffer to hold all association
   identifiers.  If the buffer is too small, an error must be returned.
   The user can use the SCTP_GET_ASSOC_NUMBER socket option to get an
   idea of how large the buffer has to be.  gaids_number_of_ids gives
   the number of elements in the array gaids_assoc_id.  Note also that
   some or all of sctp_assoc_t returned in the array may become invalid
   by the time the caller gets back the result.

   For a one-to-one style socket, this socket option results in an
   error.

8.3.  Write-Only Options

   The options defined in this subsection are write-only.  Using this
   option in a getsockopt() or sctp_opt_info() call will result in an
   error indicating EOPNOTSUPP.

Top      Up      ToC       Page 86 
8.3.1.  Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR)

   This call requests that the peer mark the enclosed address as the
   association primary (see [RFC5061]).  The enclosed address must be
   one of the association's locally bound addresses.

   The following structure is used to make a set peer primary request:

   struct sctp_setpeerprim {
     sctp_assoc_t sspp_assoc_id;
     struct sockaddr_storage sspp_addr;
   };

   sspp_assoc_id:  This parameter is ignored for one-to-one style
      sockets.  For one-to-many style sockets, it identifies the
      association for this request.  Note that the predefined constants
      are not allowed for this option.

   sspp_addr:  The address to set as primary.

8.3.2.  Add a Chunk That Must Be Authenticated (SCTP_AUTH_CHUNK)

   This set option adds a chunk type that the user is requesting to be
   received only in an authenticated way.  Changes to the list of chunks
   will only affect future associations on the socket.

   The following structure is used to add a chunk:

   struct sctp_authchunk {
     uint8_t sauth_chunk;
   };

   sauth_chunk:  This parameter contains a chunk type that the user is
      requesting to be authenticated.

   The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH
   chunks must not be used.  If they are used, an error must be
   returned.  The usage of this option enables SCTP AUTH in cases where
   it is not required by other means (for example, the use of dynamic
   address reconfiguration).

8.3.3.  Set a Shared Key (SCTP_AUTH_KEY)

   This option will set a shared secret key that is used to build an
   association shared key.

   The following structure is used to access and modify these
   parameters:

Top      Up      ToC       Page 87 
   struct sctp_authkey {
     sctp_assoc_t sca_assoc_id;
     uint16_t sca_keynumber;
     uint16_t sca_keylength;
     uint8_t  sca_key[];
   };

   sca_assoc_id:  This parameter indicates on what association the
      shared key is being set.  The special SCTP_{FUTURE|CURRENT|
      ALL}_ASSOC can be used.  For one-to-one style sockets, this
      parameter is ignored.  Note, however, that on one-to-one style
      sockets, this option will set a key on the association if the
      socket is connected; otherwise, this option will set a key on the
      endpoint.

   sca_keynumber:  This parameter is the shared key identifier by which
      the application will refer to this shared key.  If a key of the
      specified index already exists, then this new key will replace the
      old existing key.  Note that shared key identifier '0' defaults to
      a null key.

   sca_keylength:  This parameter is the length of the array sca_key.

   sca_key:  This parameter contains an array of bytes that is to be
      used by the endpoint (or association) as the shared secret key.
      Note that if the length of this field is zero, a null key is set.

8.3.4.  Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY)

   This set option indicates that the application will no longer send
   user messages using the indicated key identifier.

   struct sctp_authkeyid {
     sctp_assoc_t scact_assoc_id;
     uint16_t scact_keynumber;
   };

   scact_assoc_id:  This parameter indicates from which association the
      shared key identifier is being deleted.  The special SCTP_{FUTURE|
      CURRENT|ALL}_ASSOC can be used.  For one-to-one style sockets,
      this parameter is ignored.  Note, however, that this option will
      deactivate the key from the association if the socket is
      connected; otherwise, this option will deactivate the key from the
      endpoint.

Top      Up      ToC       Page 88 
   scact_keynumber:  This parameter is the shared key identifier that
      the application is requesting to be deactivated.  The key
      identifier must correspond to an existing shared key.  Note that
      if this parameter is zero, use of the null key identifier '0' is
      deactivated on the endpoint and/or association.

   The currently active key cannot be deactivated.

8.3.5.  Delete a Shared Key (SCTP_AUTH_DELETE_KEY)

   This set option will delete an SCTP association's shared secret key
   that has been deactivated.

   struct sctp_authkeyid {
     sctp_assoc_t scact_assoc_id;
     uint16_t scact_keynumber;
   };

   scact_assoc_id:  This parameter indicates from which association the
      shared key identifier is being deleted.  The special SCTP_{FUTURE|
      CURRENT|ALL}_ASSOC can be used.  For one-to-one style sockets,
      this parameter is ignored.  Note, however, that this option will
      delete the key from the association if the socket is connected;
      otherwise, this option will delete the key from the endpoint.

   scact_keynumber:  This parameter is the shared key identifier that
      the application is requesting to be deleted.  The key identifier
      must correspond to an existing shared key and must not be in use
      for any packet being sent by the SCTP implementation.  This means,
      in particular, that it must be deactivated first.  Note that if
      this parameter is zero, use of the null key identifier '0' is
      deleted from the endpoint and/or association.

   Only deactivated keys that are no longer used by an association can
   be deleted.



(page 88 continued on part 4)

Next RFC Part