sctp_opt_info

- examine SCTP level options for an SCTP endpoint

Synopsis

cc [ flag... ] file... -lsocket -lnsl -lsctp [ library... ]
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/sctp.h>

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

Description

The sctp_opt_info() returns SCTP level options associated with the SCTP socket sock. If sock is a one-to-many style socket, id refers to the association of interest. If sock is a one-to-one socket or if sock is a branched-off one-to-many style socket, id is ignored. The opt parameter specifies the SCTP option to get. The arg structure is an option-specific structure buffer allocated by the caller. The len parameter is the length of the option specified.

Following are the currently supported values for the opt parameter. When one of the options below specifies an association id, the id is relevant for only one-to-many style SCTP sockets. The associatation id can be ignored for one-to-one style or branched-off one-to-many style SCTP sockets.

SCTP_RTOINFO

Returns the protocol parameters used to initialize and bind retransmission timeout (RTO) tunable. The following structure is used to access these parameters:

struct sctp_rtoinfo {
       sctp_assoc_t            srto_assoc_id;
       uint32_t                srto_initial;
       uint32_t                srto_max;
       uint32_t                srto_min;
};
where:
       srto_assoc_id           Association ID specified by the caller
       srto_initial            Initial RTO value
       srto_max                Maximum value for the RTO
       srto_min                Minimum value for the RTO

SSCTP_ASSOCINFO

Returns association-specific parameters. The following structure is used to access the 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;
};
where:
       srto_assoc_id           Association ID specified by the caller
       sasoc_asocmaxrxt        Maximum retransmission count for
                               the association
       sasoc_number_peer_destinations
                               Number of addresses the peer has
       sasoc_peer_rwnd         Current value of the peer's
                               receive window
       sasoc_local_rwnd        Last reported receive window sent
                               to the peer
       sasoc_cookie_life       Association cookie lifetime used
                               when issuing cookies

All parameters with time values are in milliseconds.

SCTP_DEFAULT_SEND_PARAM

Returns the default set of parameters used by the sendto() function on this association. The following structure is used to access the parameters:

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;
};
where:
       sinfo_stream            Default stream for sendmsg()
       sinfo_ssn               Always returned as 0
       sinfo_flags             Default flags for sendmsg()
                               that include the following:
                               MSG_UNORDERED
                               MSG_ADDR_OVER
                               MSG_ABORT
                               MSG_EOF
                               MSG_PR_SCTP
       sinfo_ppid              Default payload protocol identifier
                               for sendmsg()
       sinfo_context           Default context for sendmsg()
       sinfo_timetolive        Time to live in milliseconds for a
                               message on the sending side.
                               The message expires if the sending
                               side does not start the first
                               transmission for the message within
                               the specified time period. If the
                               sending side starts the first
                               transmission before the time period
                               expires, the message is sent as a
                               normal reliable message. A value of
                               0 indicates that the message does not
                               expire. When MSG_PR_SCTP is set in
                               sinfo_flags, the message expires if
                               it is not acknowledged within the
                               time period.
       sinfo_tsn               Always returned as 0
       sinfo_cumtsn            Always returned as 0
       sinfo_assoc_id          Association ID specified by the caller

SCTP_PEER_ADDR_PARAMS

Returns the parameters for a specified peer address of the association. The following structure is used to access the 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_ipv4_tos;
};

where:

spp_assoc_id

Association ID specified by the caller.

spp_address

Peer's address.

spp_hbinterval

Heartbeat interval in milliseconds.

spp_pathmaxrxt

Maximum number of retransmissions to an address before it is considered 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 spp_flags, the given value is used as the path MTU. If SPP_PMTUD_ENABLE is set in spp_flags, 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 IPv6 layer setting.

spp_ipv4_tos

This field is used in conjunction with the SPP_IPV4_TOS flag. This setting has precedence over any IPv4 layer setting.

spp_flags

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

SPP_HB_ENABLE

Enable heartbeats on the specified address.

SPP_HB_DISABLE

Disable 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 have undetermined results.

SPP_HB_DEMAND

Request a user initiated heartbeat to be made immediately. This must 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

This field will enable PMTU discovery upon the specified address.

SPP_PMTUD_DISABLE

This field will disable PMTU discovery upon 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 will have undetermined results.

SPP_IPV6_FLOWLABEL

Setting this flag enables the setting of the IPV6 flowlabel value. The value is obtained in the spp_ipv6_flowlabel field.

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), the value returned is that of the address. If just an association is specified (and no address), 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 will be left cleared.

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 in 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 is set when called (in the spp_address field) then that specific destination address' TOS value is returned. If just an association is specified then the association default TOS is returned. If neither an association nor a destination is specified, then the sockets default TOS is returned.

SCTP_STATUS

Returns the current status information about the association. The following structure is used to access the parameters:

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;
       uint16_t                sstat_fragmentation_point;
       struct sctp_paddrinfo   sstat_primary;
};
where:

       sstat_assoc_id          Association ID specifed by the caller
       sstat_state             Current state of the association
                               which might be one of the following:

                               SCTP_CLOSED
                               SCTP_BOUND
                               SCTP_LISTEN
                               SCTP_COOKIE_WAIT
                               SCTP_COOKIE_ECHOED
                               SCTP_ESTABLISHED
                               SCTP_SHUTDOWN_PENDING
                               SCTP_SHUTDOWN_SENT
                               SCTP_SHUTDOWN_RECEIVED
                               SCTP_SHUTDOWN_ACK_SENT
       sstat_rwnd              Current receive window of the 
                               association peer
       sstat_unackdata         Number of unacked DATA chunks
       sstat_penddata          Number of DATA chunks pending 
                               receipt
       sstat_instrms           Number of inbound streams
       sstat_outstrms          Number of outbound streams
       sstat_fragmentation_point
                               Size at which SCTP fragmentation occurs
       sstat_primary           Information about the primary
                               peer address

       sstat_primary has 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;
                        };
                        where:
                        spinfo_assoc_id         Association ID
                                                specified by
                                                the caller
                        spinfo_address          Primary peer
                                                address
                        spinfo_state            State of the peer
                                                address:
                                                SCTP_ACTIVE or
                                                SCTP_INACTIVE
                        spinfo_cwnd             Congestion window
                                                of the peer 
                                                address
                        spinfo_srtt             Smoothed round-trip
                                                time calculation of
                                                the peer address
                        spinfo_rto              Current retransmission 
                                                timeout value of the
                                                peer address in 
                                                milliseconds
                        spinfo_mtu              P-MTU of the address

Return Values

Upon successful completion, the sctp_opt_info() function returns 0. Otherwise, the function returns -1 and sets errno to indicate the error.

Errors

The sctp_opt_info() call fails under the following conditions.

EBADF

The sock argument is an invalid file descriptor.

ENOTSOCK

The sock argument is not a socket.

EINVAL

The association id is invalid for a one-to-many style SCTP socket.

EINVAL

The input buffer length is insufficient for the option specified.

EINVAL

The peer address is invalid or does not belong to the association.

EAFNOSUPPORT

The address family for the peer's address is other than AF_INET or AF_INET6.

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

in.h(3HEAD), libsctp(3LIB), getsockopt(3SOCKET), setsockopt(3SOCKET), socket(3SOCKET), inet(7P), inet6(7P), ip(7P), ip6(7P), sctp(7P)