'\"macro stdmacro
.if n .pH g3n.t_alloc @(#)t_alloc	40.4 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} t_alloc 3N "Networking Support Utilities" "\&"
.if \nX=1 .ds x} t_alloc 3N "Networking Support Utilities"
.if \nX=2 .ds x} t_alloc 3N "" "\&"
.if \nX=3 .ds x} t_alloc "" "" "\&"
.if \nX=4 .ds x} t_alloc "NS_LIB" "EXTENSION" " "
.TH \*(x}
.SH NAME
\f4t_alloc\f1 \- allocate a library structure
.SH SYNOPSIS
\f4#include <tiuser.h>\f1
.PP
\f4char *t_alloc(fd, struct_type, fields)\f1
.br
\f4int fd;\f1
.br
\f4int struct_type;\f1
.br
\f4int fields;\f1
.SH DESCRIPTION
The \f4t_alloc\fP function dynamically allocates memory for the
various transport function argument structures as specified below.
This function will allocate memory for the specified structure, and
will also allocate memory for buffers referenced by the structure.
.PP
The structure to allocate is specified by \f4struct_type\fP,
and can be one of the following:
.TP 17
\f4T_BIND\fP
\f4struct t_bind\fP
.TP
\f4T_CALL\fP
\f4struct t_call\fP
.TP
\f4T_OPTMGMT\fP
\f4struct t_optmgmt\fP
.TP
\f4T_DIS\fP
\f4struct t_discon\fP
.TP
\f4T_UNITDATA\fP
\f4struct t_unitdata\fP
.TP
\f4T_UDERROR\fP
\f4struct t_uderr\fP
.TP
\f4T_INFO\fP
\f4struct t_info\fP
.PP
where each of these structures may subsequently be
used as an argument to one or more transport functions.
.PP
Each of the above structures, except \f4T_INFO\fP, contains at least
one field of type \f4struct netbuf\fP.
\f4netbuf\f1 is described in \f4intro\fP(3).
For each field of this type, the user may specify that
the buffer for that field should be allocated as well.
The \f4fields\fP argument specifies this option, where the argument is the
bitwise-\c
.SM OR
of any of the following:
.TP 10
\f4T_ADDR\fP
The \f4addr\fP field of the \f4t_bind\fP, \f4t_call\fP, \f4t_unitdata\fP,
or \f4t_uderr\fP structures.
.TP
\f4T_OPT\fP
The \f4opt\fP field of the \f4t_optmgmt\fP, \f4t_call\fP, \f4t_unitdata\fP,
or \f4t_uderr\fP structures.
.TP
\f4T_UDATA\fP
The \f4udata\fP field of the \f4t_call\fP, \f4t_discon\fP, or
\f4t_unitdata\fP structures.
.TP
\f4T_ALL\fP
All relevant fields of the given structure.
.PP
For each field specified in \f4fields\fP, \f4t_alloc\fP
will allocate memory for the buffer associated with the field,
and initialize the \f4buf\fP pointer and \f4maxlen\fP
[see \f4netbuf\f1 in \f4intro\fP(3) for description of \f4buf\f1 and
\f4maxlen\f1] field accordingly.
The length of the buffer allocated will be based on the same size
information that is returned to the user on \f4t_open\fP and \f4t_getinfo\fP.
Thus, \f4fd\fP must refer to the transport endpoint through which the newly
allocated structure will be passed, so that the appropriate
size information can be accessed.
If the size value associated with any specified field is \-1 or \-2
(see \f4t_open\fP or \f4t_getinfo\fP), \f4t_alloc\fP will be unable
to determine the size of the buffer to allocate and will fail, setting
\f4t_errno\fP to \f4TSYSERR\fP and \f4errno\fP to \f4EINVAL\fP.
For any field not specified in \f4fields\fP, \f4buf\fP will be set to
.SM NULL
and \f4maxlen\fP will be set to zero.
.PP
Use of \f4t_alloc\fP to allocate structures will help ensure the
compatibility of user programs with future releases of the transport interface.
.P
On failure, \f4t_errno\f1 may be set to one of the following:
.TP 15
\f4[TBADF]\fP
The specified file descriptor does not refer to a transport
endpoint.
.TP
\f4[TSYSERR]\fP
A system error has occurred during execution of this function.
.SH SEE ALSO
\f4intro\fP(3), \f4t_free\fP(3N), \f4t_getinfo\fP(3N), \f4t_open\fP(3N).
.sp .2
\f2UNIX System V Network Programmer's Guide\f1.
.SH DIAGNOSTICS
On successful completion, \f4t_alloc\fP returns a pointer to the newly
allocated structure.
On failure,
.SM NULL
is returned.
.Ee
