xti_sctp.3.man

This a separate release of the OpenSS7 X/Open XTI/TLI library, TLI modules (timod, tirdwr) and the I

connection.
.\"
.\"
.TP
.B T_SCTP_DISPOSITION
This option determines whether SCTP will retain and deliver messages that were
not successfully acknowledged by the peer for retrieval, or will deliver
confirmation of acknowledgment for message successfully acknowledged by the
peer.
The option value is formatted as a
.BR t_scalar_t ,
and can have one of the following values:
.RS
.TP
.I T_SCTP_DISPOSITION_NONE
Messages will not be retained for retrieval and acknowledgments will not be
provided for messages.
.TP
.I T_SCTP_DISPOSITION_UNSENT
Messages that were unsent will be retained for retrieval.
.TP
.I T_SCTP_DISPOSITION_SENT
Messages that were sent and unacknowledged, or that were unsent, will be
retained for retrieval.
.TP
.I T_SCTP_DISPOSITION_GAP_ACKED
Messages that were sent and gap acknowledged as well as messages that were
sent and unacknowledged and messages that were unsent, will be retained for
retrieval.
.TP
.I T_SCTP_DISPOSITION_ACKED
Messages that were sent and acknowledged (but unconfirmed), messages that were
sent and gap acknowledged, messages that were sent and unacknowledged, and
messages that were unsent, will be retained for retrieval.
.PP
This option permits messages that are unsent, sent but not acknowledged or
sent and gap acknowledged, to be retrieved from the transport endpoint before
close.  This is accomplished by setting the
.I T_SCTP_DISPOSITION
option before shutdown or abort of the transport connection, and then calling
.BR t_rcv "(3) or " t_rcvv (3)
after
.BR POLLHUP ", " SIGPIPE " or " EPIPE
indicating a shutdown or abort of the transport connection.
Messages then read will set the
.I T_SCTP_DISPOSITION
option on the transport endpoint to indicate whether they were
.IR T_SCTP_DISPOSITION_UNSENT ", " T_SCTP_DISPOSITION_SENT ", " T_SCTP_DISPOSITION_GAP_ACKED " or " T_SCTP_DISPOSITION_ACKED .
.PP
If the transport endpoint has option
.I T_SCTP_PR
set and the peer supports partial reliability (see
.IR T_SCTP_PR ),
message which have failed partial reliability delivery (were dropped) will also
be retrieved by
.BR t_rcv "(3) or " t_rcvv (3).
.PP
Alternatively, if the socket option
.I T_SCTP_DISPOSITION
is set to
.IR T_SCTP_DISPOSITION_ACKED ,
.BR t_rcv "(3) or " t_rcvv (3)
will also return acknowledgments for messages not acknowledged sent at the
time of the transport connection disconnection.
.PP
This option is intended for use with the
.BR sockets (3)
library,
is extremely non-portable,
and has little use for
.BR xti (3).
.RE
.\"
.\"
.TP
.B T_SCTP_LIFETIME
This option determines the SCTP lifetime
.[
RFC 2960
.]
or the partial reliability timed reliability lifetime
.[
draft-ietf-tsvwg-prsctp-00.txt
.]
associated with message that are sent on this transport endpoint.
The option value is formatted as a
.B t_scalar_t
that contains the lifetime (in milliseconds).
.\"
.\"
.TP
.B T_SCTP_ADD
This option determines whether the transport endpoint will support the add IP
extension
.RB ( ADD-IP " and " DEL-IP )
described in draft-ietf-tsvwg-addip-sctp-07.txt.
.[
draft-ietf-tsvwg-addip-sctp-07.txt
.]
The option value is formatted as a
.B t_scalar_t
that can have values
.BR T_YES " or " T_NO .
.sp
When set to
.BR T_YES ,
this option request that SCTP respond to ASCONF chunks with ADD-IP or DEL-IP
requests.  When set to
.BR T_NO ,
SCTP will refuse these requests for the transport connection.
This option can be set or read at any time during the transport connection
lifetime.
.\"
.\"
.TP
.B T_SCTP_ADD_IP
This option adds a IP address to an existing transport endpoint.
The option value is formatted as a
.B sockaddr_in
structure that contains the local IP address to add.
Option
.I T_SCTP_ADD
must be set to
.B T_YES
for this option to be valid.
.sp
If the transport stream is in a connected or connecting state, this invokes
the ASCONF procedure to add the IP address to the existing transport
connection.  If the transport stream is in a disconnected state, setting this
option will add the local IP address to the addresses bound with
.BR t_bind (3),
and acts as a hierarchal subsequent binding operation.
.sp
Note that if a transport endpoint was initially bound to
.IR INADDR_ANY ,
IP addresses may be automatically added to the transport connection
if new network interfaces are added to the system, or if existing network
interfaces are configured using
.BR ifconfig (8)
or equivalent commands.
.\"
.\"
.TP
.B T_SCTP_DEL_IP
This option deletes an IP address from an existing transport endpoint.
The option value is formatted as a
.B sockaddr_in
structure that contains the local IP address to delete.
Option
.I T_SCTP_ADD
must be set to
.B T_YES
for this option to be valid.
.sp
If the transport stream is in a connected or connecting state, this invokes
the ASCONF procedure to remove the IP address from the transport connection.
If the transport stream is in a disconnected state, setting this option will
remove the local IP address from the addresses bound with
.BR t_bind (3),
and acts as a hierarchal subsequent unbinding operation.
.sp
Note that if the transport endpoint was initially bound to
.IR INADDR_ANY ,
IP addresses may be automatically removed from the transport connection if
existing network interfaces are removed from the system, or if network
interfaces are reconfigured with
.BR ifconfig (8)
or equivalent commands.
.\"
.\"
.TP
.B T_SCTP_SET
This option determines whether the transport endpoint will support the add IP
extensions
.RB ( SET-PRIMARY )
described in draft-ietf-tsvwg-addip-sctp-07.txt.
.[
draft-ietf-tsvwg-addip-sctp-07.txt
.]
The option value is formatted as a
.B t_scalar_t
that can have values
.BR T_YES " or " T_NO .
.sp
When set to
.BR T_YES ,
this option request that SCTP respond to ASCONF chunks with SET-PRIMARY
requests.  When set to
.BR T_NO ,
SCTP will refuse these requests for the transport connection.
This option can be set or read at any time during the transport connection
lifetime.
.\"
.\"
.TP
.B T_SCTP_STATUS
This option conveys the association status  and the status associated with
each of the destination transport addresses forming the transport connection.
This is a read-only option.
The returned value is formatted as a
.B t_sctp_status
structure containing one
.B t_sctp_dest_status
structure for each destination transport address, formatted as follows:
.sp
.nf
\fC\s-1\
typedef struct t_sctp_status {
    t_uscalar_t curr_rwnd;   /* receive window */
    t_uscalar_t curr_rbuf;   /* receive buffer */
    t_uscalar_t curr_nrep;   /* dests reported */
    t_sctp_dest_status_t curr_dest[0]; /* primary dest */
} t_sctp_status_t;
.sp
typedef struct t_sctp_dest_status {
    t_uscalar_t dest_addr;   /* address */
    t_uscalar_t dest_cwnd;   /* congestion window */
    t_uscalar_t dest_unack;  /* unacknowledged chunks */
    t_uscalar_t dest_srtt;   /* smooth round trip time */
    t_uscalar_t dest_rvar;   /* rtt variance */
    t_uscalar_t dest_rto;    /* current rto */
    t_uscalar_t dest_sst;    /* slow start threshold */
} t_sctp_dest_status_t;
\s+1\fR
.fi
.RS
.PP
The
.B t_sctp_status
structure has the following fields:
.TP \w'dest_unack\(em'u
.I curr_rwnd
is the current advertised receive window in bytes.
.PD 0
.TP
.I curr_rbuf
is the current receive buffer size in bytes.
.TP
.I curr_nrep
is the number of
.B t_sctp_dest_status
structure that follow this structure.
.PD
.PP
The
.B t_sctp_dest_status
structure has the following fields:
.TP \w'dest_unack\(em'u
.I dest_addr
is the address associated with this specific
.B t_sctp_dest_status
structure.
.PD 0
.TP
.I dest_cwnd
is the congestion window for the given destination transport address in bytes.
.TP
.I dest_unack
is the number of unacknowledged DATA chunks outstanding to the given
destination transport address in chunks.
.TP
.I dest_srtt
is the smoothed round trip time for the destination transport address in
milliseconds.
.TP
.I dest_rvar
is the round trip time variance for the destination transport address in
milliseconds.
.TP
.I dest_rto
is the current value of the round trip timeout for the destination transport
address in milliseconds.
.TP
.I dest_sst
is the current value of the slow start threshold for the destination transport
address in bytes.
.PD
.RE
.\"
.\"
.TP
.B T_SCTP_TSN
This option determines the SCTP Transmit Sequence Number that is to be associated
with a given data transmission.  The option value is formatted as a
.B t_scalar_t
that contains the numeric value of the SCTP Transmit Sequence Number.
This options is used with
.BR t_optmgmt (3).
The SCTP transport provider determines which values will be used on all packets sent with
.BR t_snd "(3), " t_sndv "(3), " write "(2) or " writev (2).
The current value, when read, using
.BR t_optmgmt (3),
will return the value that was contained in the last packet read with
.BR t_rcv "(3), " t_rcvv "(3), " read "(2) or " readv (2).
.\"
.\"
.TP
.B T_SCTP_DEBUG
This option determines implementation specific debugging features.
The option value is formatted as a
.BR t_scalar_t ,
that can be one of the following values:
.RS
.TP
.I T_SCTP_OPTION_DROPPING
the stream will drop packets at the software level for debugging purposes.
.TP
.I T_SCTP_OPTION_BREAK
the stream will break the first destination address at intervals for debugging
purposes.
.TP
.I T_SCTP_OPTION_DBREAK
the stream will break destination addresses in both directions at intervals
for debugging purposes.
.TP
.I T_SCTP_OPTION_RANDOM
the stream will drop packets at random at the software level for debugging
purposes.
.RE
.\"
.\"
.SH FUNCTIONS
.PP
.\"
.\"
.SS t_accept\fR(3)
.PP
.PP
SCTP supports this XTI/TLI library call as described in
.BR t_accept (3),
with the additional considerations described here.
.PP
When the XTI/TLI user provides a transport endpoint address in
.IR call->addr ,
the address can be an array of
.B sockaddr_in
structures, each indicating a local address for the responding endpoint.
If this list of addresses does not include the destination address of the
connection indication, the set of addresses will be expanded by the SCTP
provider to include the destination address of the connection indication.
.PP
Issuing
.BR t_accept (3)
assigns an already established connection to
.IR resfd .
.PP
Since user data cannot be exchanged during the connection establishment phase,
.I call->udata.len
must be set to zero.
.PP
When
.RI ( "resfd != fd" ),
the function
.BR t_accept (3)
is recommended to be called with
.I resfd
in the
.B T_UNBND
state, though an endpoint which is bound to any local address (in the
.B T_IDLE
state) can also be used.
.PP
After
.BR t_accept (3)
completes, the endpoint
.I resfd
will represent a connected SCTP endpoint whose complete binding essentially has
both local and remote address components.
.PP
If file descriptor
.I resfd
was unbound before calling
.BR t_accept (3),
after the call completes its local address binding would be to the same
protocol address bound to
.IR fd .
If the file descriptor
.I resfd
was bound to a local address before calling
.BR t_accept (3),
that local address binding is dissolved and the local address part of the
binding after
.BR t_accept (3)
completes would become the same as the address bound to
.IR fd .
.PP
If options with end-to-end significance
.RB ( T_IP_OPTIONS ", " T_IP_TOS ", " T_SCTP_OSTREAMS ", " T_SCTP_ISTREAMS ", " T_SCTP_ECN " and " T_SCTP_ALI )
are to be sent with the connection confirmation, the values of these options
must be set with
.BR t_optmgmt (3)
prior to the
.B T_LISTEN
event occurs.  When the transport user detects a
.B T_LISTEN
event, SCTP has already established the connection.  Association-related
options passed with
.BR t_accept (3)
become effective at once, but since the connection is already established,
they are transmitted with subsequent IP datagrams sent out in the
.B T_DATAXFER
state.
.PP
SCTP provides a number of options, described in
.IR \(lqOPTIONS\(rq ,
above, that may be included in this XTI/TLI call
in the
.I call->opt
parameter to change local and end-to-end characteristics of the transport
endpoint accepting the connection.
The options of end-to-end significance that can be included in this XTI/TLI
library call are:
.TP
.I T_IP_OPTIONS
.TP
.I T_IP_TOS
.TP
.I T_SCTP_ISTREAMS
sets the number of incoming streams for the transport connection.  This value
is only significant if it is lower than the value requested by the peer in the
options returned from the call to
.BR t_listen (3).
.TP
.I T_SCTP_OSTREAMS
sets the number of outgoing streams for the transport connection.  This value
is only significant if it is lower than the value required by the peer in the
options returned from the call to
.BR t_listen (3).
.TP
.I T_SCTP_ECN
sets whether explicit congestion notification is supported on the transport
connection.  This value is only significant if the peer indicates that it
supports explicit congestion notification in the options returned from the
call to
.BR t_listen (3).
.TP
.I T_SCTP_ALI
sets the adaptation layer information specifying the local endpoint
capabilities that are available on the transport connection.
.PP
The association-related options that can be included in this XTI/TLI call include
(other association-related options may also be included):
.TP
.I XTI_RCVBUF
.TP
.I T_IP_TTL
.PP
The options of local significance that can be included in this XTI/TLI call
include (other options of local significance may also be included):
.TP
.I XTI_DEBUG
.TP
.I XTI_LINGER
.TP
.I XTI_RCVLOWAT
.TP
.I XTI_SNDBUF