'\"macro stdmacro
.if n .pH g3n.t_bind @(#)t_bind	40.5 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} t_bind 3N "Networking Support Utilities" "\&"
.if \nX=1 .ds x} t_bind 3N "Networking Support Utilities"
.if \nX=2 .ds x} t_bind 3N "" "\&"
.if \nX=3 .ds x} t_bind "" "" "\&"
.if \nX=4 .ds x} t_bind "NS_LIB" "EXTENSION" " "
.TH \*(x}
.SH NAME
\f4t_bind\f1 \- bind an address to a transport endpoint
.SH SYNOPSIS
\f4#include <tiuser.h>\f1
.PP
\f4int t_bind (fd, req, ret)\f1
.br
\f4int fd;\f1
.br
\f4struct t_bind *req;\f1
.br
\f4struct t_bind *ret;\f1
.SH DESCRIPTION
This function
associates a protocol address
with the transport endpoint specified by
\f4fd\fP
and activates that transport endpoint.
In connection mode, the transport provider may begin accepting or requesting
connections on the transport endpoint.
In connectionless mode, the transport user may send or receive
data units through the transport endpoint.
.PP
The \f4req\fP and \f4ret\fP arguments point to a \f4t_bind\fP structure
containing the following members:
.PP
.nf
.ft4
struct netbuf addr;
unsigned qlen;
.ftP
.fi
.PP
\f4netbuf\f1 is described in \f4intro\fP(3).
The \f4addr\fP field of the \f4t_bind\fP structure specifies a protocol
address and the \f4qlen\fP field is used to indicate the maximum number
of outstanding connect indications.
.PP
\f4req\fP is used to request that an address, represented by the
\f4netbuf\fP structure, be bound to the given transport endpoint.
\f4len\fP
[see \f4netbuf\f1 in \f4intro\fP(3); also for \f4buf\f1 and \f4maxlen\f1]
specifies the number of bytes in the address and
\f4buf\fP
points to the address buffer.
\f4maxlen\fP
has no meaning for the
\f4req\fP
argument.
On return, \f4ret\fP contains the address that
the transport provider actually bound to the transport endpoint;
this may be different from the address specified by the user in
\f4req\fP.
In \f4ret\fP, the user specifies \f4maxlen\fP, which is the maximum size
of the address buffer, and \f4buf\fP, which points to the buffer where
the address is to be placed.
On return, \f4len\fP specifies the number of bytes in the bound address
and \f4buf\fP points to the bound address.
If \f4maxlen\fP is not large enough to hold the returned address, an error
will result.
.PP
If the requested address is not available, or if no address is specified in
\f4req\fP (the \f4len\f1 field of \f4addr\f1 in \f4req\f1 is zero)
the transport provider may assign an appropriate address to be bound,
and will return that address in the \f4addr\fP field of \f4ret\fP.
The user can compare the addresses in \f4req\fP and \f4ret\f1
to determine whether the transport provider bound the transport
endpoint to a different address than that requested.
.PP
\f4req\f1 may be \s-1NULL\s+1 if the user does not wish to specify an
address to be bound.
Here, the value of \f4qlen\f1 is assumed to be zero, and the transport
provider must assign an address to the transport endpoint.
Similarly, \f4ret\f1
may be \s-1NULL\s+1 if the user does not care what address was
bound by the provider and is not interested in the negotiated
value of
\f4qlen\f1.
It is valid to set
\f4req\fP
and
\f4ret\fP
to
\s-1NULL\s0
for the same call, in which case the provider chooses the address
to bind to the transport endpoint and does not return that
information to the user.
.PP
The
\f4qlen\f1
field has meaning only when initializing a connection-mode service.
It specifies the number of outstanding connect indications the transport
provider should support for the given transport endpoint.
An outstanding connect indication is one that has been passed to the transport
user by the transport provider.
A value of
\f4qlen\f1
greater than zero
is only meaningful when issued by a passive transport user that expects
other users to call it.
The value of
\f4qlen\f1
will be negotiated by the transport provider and may be changed
if the transport provider cannot support the specified number of
outstanding connect indications.
On return, the
\f4qlen\f1
field in
\f4ret\f1
will contain the negotiated value.
.PP
This function allows
more than one transport endpoint to be bound to the
same protocol address (however, the transport provider
must support this capability also), but it is not allowable to bind more than
one protocol address to the same transport endpoint.
If a user binds more than one transport endpoint to the same protocol
address, only one endpoint can be used to listen for
connect indications associated with that protocol address.
In other words, only one
\f4t_bind\fP
for a given protocol address
may specify a value of
\f4qlen\f1
greater than zero.
In this way, the transport provider can identify which transport endpoint
should be notified of an incoming connect indication.
If a user attempts to bind a protocol address to a second transport
endpoint with a value of
\f4qlen\f1
greater than zero, the transport
provider will assign another address to be bound to that
endpoint.
If a user accepts a connection on the transport endpoint that is being
used as the listening endpoint, the bound protocol address will be found to
be busy for the duration of that connection.
No other transport endpoints may be bound for listening while that initial
listening endpoint is in the data transfer phase.
This will prevent more than one transport endpoint bound to the same
protocol address from accepting connect indications.
.P
On failure,
\f4t_errno\fP
may be set to one of the following:
.TP 19
\f4[TBADF]\fP
The specified file descriptor does not refer to a transport endpoint.
.TP
\f4[TOUTSTATE]\fP
The function was issued in the wrong sequence.
.TP
\f4[TBADADDR]\fP
The specified protocol address was in an incorrect format or
contained illegal information.
.TP
\f4[TNOADDR]\fP
The transport provider could not allocate an address.
.TP
\f4[TACCES]\fP
The user does not have permission to use the specified address.
.TP
\f4[TBUFOVFLW]\fP
The number of bytes allowed for an incoming argument is not
sufficient to store the value of that argument.
The provider's state will change to
\f4T_IDLE\f1
and the information to be returned in
\f4ret\fP
will be discarded.
.TP
\f4[TSYSERR]\fP
A system error has occurred during execution of this function.
.br
.ne 5
.SH SEE ALSO
\f4intro\fP(3), t_\f4open\fP(3N), t_\f4optmgmt\fP(3N), t_\f4unbind\fP(3N).
.sp .2
\f2UNIX System V Network Programmer's Guide\f1.
.SH DIAGNOSTICS
\f4t_bind\fP returns 0 on success and \-1 on failure and
\f4t_errno\f1 is set to indicate the error.
.Ee
