xref: /illumos-gate/usr/src/man/man3socket/sctp_opt_info.3socket (revision a1d41cf940fc4cda50098ad61e6a78b19c7483cd)
te
Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
SCTP_OPT_INFO 3SOCKET "March 10, 2023"
NAME
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 association 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;
};
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
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 specified 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(7) for descriptions of the following attributes:
ATTRIBUTE TYPE ATTRIBUTE VALUE
Interface Stability Evolving
MT-Level Safe
SEE ALSO
in.h (3HEAD), libsctp (3LIB), getsockopt (3SOCKET), setsockopt (3SOCKET), sockaddr (3SOCKET), socket (3SOCKET), inet (4P), inet6 (4P), ip (4P), ip6 (4P), sctp (4P)