1. Oracle Solaris 11.4 Programming Interfaces Guide
  2. Socket Interfaces
  3. Stream Control Transmission Protocol
  4. SCTP Socket Interfaces
  5. sctp_opt_info() Function

sctp_opt_info() Function 

int sctp_opt_info(sock, id, opt, *arg, *len);
int sock, sctp_assoc_id_t id, int opt, void *arg, socklen_t *len;

The sctp_opt_info() function returns the SCTP level options that are associated with the socket described in the sock parameter. If the socket is a one-to-many SCTP socket model the value of the id parameter refers to a specific association. The id parameter is ignored for one-to-one SCTP sockets. The value of the opt parameter specifies the SCTP socket option to get. The value of the arg parameter is an option-specific structure buffer that is allocated by the calling program. The value of the *len parameter is the length of the option.

The opt parameter can have the following values:

  • SCTP_RTOINFO

  • SCTP_ASSOCINFO

  • SCTP_DEFAULT_SEND_PARAM

  • SCTP_PEER_ADDR_PARAMS

  • SCTP_STATUS

  • SCTP_INITMSG

  • SCTP_NODELAY

  • SCTP_AUTOCLOSE

  • SCTP_PRIMARY_ADDR

  • SCTP_GET_PEER_ADDR_INFO

  • SCTP_EVENT

  • SCTP_DELAYED_SACK

  • SCTP_PARTIAL_DELIVERY_POINT

  • SCTP_FRAGMENT_INTERLEAVE

  • SCTP_MAX_BURST

  • SCTP_CONTEXT

  • SCTP_EXPLICIT_EOR

  • SCTP_REUSE_PORT

  • SCTP_RECVRVCINFO

  • SCTP_RECVNXTINFO

  • SCTP_DEFAULT_SNDINFO

  • SCTP_GETASSOC_NUMBER

  • SCTP_GET_ASSOC_ID_LIST

A few of the opt parameters are described in detail here:

SCTP_RTOINFO

Returns the protocol parameters that are used to initialize and bind the retransmission timeout (RTO) tunable. The protocol parameters use the following structure:

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

The calling program provides this value, which specifies the association of interest.

srto_initial

This value is the initial RTO value.

srto_max

This value is the maximum RTO value.

srto_min

This value is the minimum RTO value.

SCTP_ASSOCINFO

Returns the association-specific parameters. The parameters use the following structure:

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

The calling program provides this value, which specifies the association of interest.

sasoc_assocmaxrxt

This value specifies the maximum retransmission count for the association.

sasoc_number_peer_destinations

This value specifies the number of addresses that the peer has.

sasoc_peer_rwnd

This value specifies the current value of the peer's receive window.

sasoc_local_rwnd

This value specifies the last reported receive window that the peer transmitted to.

sasoc_cookie_life

The value specifies the lifetime of the association's cookie. The value is used when issuing cookies.

All parameters that use time values are measured in milliseconds.

SCTP_DEFAULT_SEND_PARAM

Returns the default set of parameters that a call to the sendto function uses on this association. For more information, see the sendto(3C) man page. The parameters use the following structure: 

struct sctp_sndrcvinfo {
    uint16_t        sinfo_stream;
    uint16_t        sinfo_ssn;
    uint16_t        sinfo_flags;
    uint32_t        sinfo_ppid;
    uint32_t        sinfo_context;
    uint32_t        sinfo_timetolive;
    uint32_t        sinfo_tsn;
    uint32_t        sinfo_cumtsn;
    sctp_assoc_t    sinfo_assoc_id;
};
sinfo_stream

This value specifies the default stream for the sendmsg() call.

sinfo_ssn

This value is always zero.

sinfo_flags

This value contains the default flags for the sendmsg() call. This flag can take on the following values:

  • MSG_UNORDERED

  • MSG_ADDR_OVER

  • MSG_ABORT

  • MSG_EOF

  • MSG_PR_SCTP

sinfo_ppid

This value is the default payload protocol identifier for the sendmsg() call.

sinfo_context

This value is the default context for the sendmsg() call.

sinfo_timetolive

This value specifies a time period in milliseconds. After this time period has passed, the message expires if its transmission has not begun. A value of zero indicates that the message does not expire. If the MSG_PR_SCTP flag is set, the message expires when its transmission has not successfully completed within the time period specified in sinfo_timetolive.

sinfo_tsn

This value is always zero.

sinfo_cumtsn

This value is always zero.

sinfo_assoc_id

This value is filled in by the calling application. This value specifies the association of interest.

SCTP_PEER_ADDR_PARAMS

Returns the parameters for a specified peer address. The parameters use the following structure:

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_ipv4_tos;
};
spp_assoc_id

The calling program provides this value, which specifies the association of interest.

spp_address

This value specifies the peer's address of interest.

spp_hbinterval

This value specifies the heartbeat interval in milliseconds.

spp_pathmaxrxt

This value specifies the maximum number of retransmissions to attempt on an address before considering the address unreachable.

spp_pathmtu

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, the given value is used as the path MTU. If SPP_PMTUD_ENABLE is set in the spp_flags, then the spp_pathmtu field is ignored.

spp_ipv6_flowlabel

This field is used in conjunction with the SPP_IPV6_FLOWLABEL flag. This setting has precedence over any other IPv6 layer setting.

spp_flags

The spp_flags flags are used to control various features on an association. The flag field is a bit mask which may contain one of the following options:

  • SPP_HB_ENABLE – Enable heartbeats on the specified address.

  • SPP_HB_DISABLE – Disable heartbeats on the specified address. SPP_HB_ENABLE and SPP_HB_DISABLE are mutually exclusive, only one of the two should be specified. Enabling both fields will result in undetermined results.

  • SPP_HB_DEMAND – Request a user initiated heartbeat to be made immediately. This option should not be used in conjunction with a wildcard address.

  • SPP_HB_TIME_IS_ZERO – Specifies that the time for heartbeat delay is to be set to the value of 0 milliseconds.

  • SPP_PMTUD_ENABLE – Enable PMTU discovery on the specified address.

  • SPP_PMTUD_DISABLE – Disable PMTU discovery on the specified address. If the address field is empty then all addresses on the association are affected. SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE options are mutually exclusive. Enabling both options will result in undetermined results.

  • SPP_IPV6_FLOWLABEL – Enables the setting of the IPV6 flowlabel value. The value is obtained from the spp_ipv6_flowlabel field. Upon retrieval, this flag will be set to indicate that the ipv6_flowlabel field has a valid value returned. If a specific destination address is set in the spp_address field, then the value of the address is returned. If only an association is specified and no address is specified, then the association's default flowlabel is returned. If neither an association nor a destination is specified, then the socket's default flowlabel is returned. For non– IPv6 sockets, this flag is left empty.

  • SPP_IPV4_TOS – Setting this flag enables the setting of the IPV4 TOS value associated with either the association or a specific address. The value is obtained from the spp_ipv4_tos field. Upon retrieval, this flag will be set to indicate that the spp_ipv4_tos field has a valid value returned. If a specific destination address in the spp_address field is set when called, then the TOS value of the specific destination address returned. If only an association is specified then the default TOS of the association is returned. If neither an association nor a destination is specified, then the default TOS value of the socket is returned.

SCTP_STATUS

Returns the current status information about the association. The parameters use the following structure:

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

The calling program provides this value, which specifies the association of interest.

sstat_state

This value is the association's current state. The association can take on the following states:

SCTP_IDLE

The SCTP endpoint does not have any association associated with it. Immediately after the call to the socket() function opens an endpoint, or after the endpoint closes, the endpoint is in this state.

SCTP_BOUND

An SCTP endpoint is bound to one or more local addresses after calling the bind().

SCTP_LISTEN

This endpoint is waiting for an association request from any remote SCTP endpoint.

SCTP_COOKIE_WAIT

This SCTP endpoint has sent an INIT chunk and is waiting for an INIT-ACK chunk.

SCTP_COOKIE_ECHOED

This SCTP endpoint has echoed the cookie that it received from its peer's INIT-ACK chunk back to the peer.

SCTP_ESTABLISHED

This SCTP endpoint can exchange data with its peer.

SCTP_SHUTDOWN_PENDING

This SCTP endpoint has received a SHUTDOWN primitive from its upper layer. This endpoint no longer accepts data from its upper layer.

SCTP_SHUTDOWN_SEND

An SCTP endpoint that was in the SCTP_SHUTDOWN_PENDING state has sent a SHUTDOWN chunk to its peer. The SHUTDOWN chunk is sent only after all outstanding data from this endpoint to its peer is acknowledged. When this endpoint's peer sends a SHUTDOWN ACK chunk, this endpoint sends a SHUTDOWN COMPLETE chunk and the association is considered closed.

SCTP_SHUTDOWN_RECEIVED

An SCTP endpoint has received a SHUTDOWN chunk from its peer. This endpoint no longer accepts new data from its user.

SCTP_SHUTDOWN_ACK_SEND

An SCTP endpoint in the SCTP_SHUTDOWN_RECEIVED state has sent the SHUTDOWN ACK chunk to its peer. The endpoint only sends the SHUTDOWN ACK chunk after the peer acknowledges all outstanding data from this endpoint. When this endpoint's peer sends a SHUTDOWN COMPLETE chunk, the association is closed.

sstat_rwnd

This value is the association peer's current receive window.

sstat_unackdata

This value is the number of unacknowledged DATA chunks.

sstat_penddata

This value is the number of DATA chunks that are awaiting receipt.

sstat_instrms

This value is the number of inbound streams.

sstat_outstrms

This value is the number of outbound streams.

sstat_fragmentation_point

If the combined size of the message, the SCTP headers, and the IP headers exceeds the value of sstat_fragmentation_point, the message fragments. This value is equal to the Path Maximum Transmission Unit (P-MTU) for the packet's destination address.

sstat_primary

This value contains information about the primary peer address. This information uses the following structure:

struct sctp_paddrinfo {
    sctp_assoc_t               spinfo_assoc_id;
    struct sockaddr_storage    spinfo_address;
    int32_t                    spinfo_state;
    uint32_t                   spinfo_cwnd;
    uint32_t                   spinfo_srtt;
    uint32_t                   spinfo_rto;
    uint32_t                   spinfo_mtu;
};
spinfo_assoc_id

The calling program provides this value, which specifies the association of interest.

spinfo_address

This value is the primary peer's address.

spinfo_state

This value can take on either of the two values SCTP_ACTIVE or SCTP_INACTIVE.

spinfo_cwnd

This value is the congestion window of the peer address.

spinfo_srtt

This value is the current smoothed round-trip time calculation for the peer address. This value is expressed in milliseconds.

spinfo_rto

This value is the current retransmission timeout value for the peer address. This value is expressed in milliseconds.

spinfo_mtu

This value is the P-MTU for the peer address.

The sctp_opt_info() function returns 0 on success. The sctp_opt_info() function returns -1 on failure and sets the value of errno to the appropriate error code. If the file descriptor passed to the sctp_opt_info() in the sock parameter is invalid, the sctp_opt_info() function fails and returns EBADF. If the file descriptor passed to the sctp_opt_info() function in the sock parameter does not describe a socket, the sctp_opt_info() function fails and returns ENOTSOCK. If the association ID is invalid for a one-to-many SCTP socket model, the sctp_opt_info() function fails and sets the value of errno to EINVAL. If the input buffer length is too short for the option specified, the sctp_opt_info() function fails and sets the value of errno to EINVAL. If the address family for the peer's address is not AF_INET or AF_INET6, the sctp_opt_info() function fails and sets the value of errno to EAFNOSUPPORT.