139 lines
4.3 KiB
Plaintext
139 lines
4.3 KiB
Plaintext
'\"macro stdmacro
|
|
.if n .pH g3n.t_alloc @(#)t_alloc 40.9 of 5/23/91
|
|
.\" Copyright 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1989, 1990 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#ifdef _XOPEN_SOURCE\f1
|
|
.br
|
|
\f4#include <xti.h>\f1
|
|
.br
|
|
\f4#else\f1
|
|
.br
|
|
\f4#include <tiuser.h>\f1
|
|
.br
|
|
\f4#endif\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(3N).
|
|
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
|
|
\f4OR\f1
|
|
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(3N) 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
|
|
\f4NULL\f1
|
|
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
|
|
This function resides within both the X/Open compliant \f4libxnet\f1 and
|
|
the SVR4 compliant \f4libnsl\f1 Network Services libraries. Network Services
|
|
applications which require X/Open compliance must link-load with \f4-lxnet\f1.
|
|
Network Services applications which require SVR4 compliance must link-load
|
|
with \f4-lnsl\f1.
|
|
.P
|
|
On failure, \f4t_errno\f1 may be set to one of the following:
|
|
.TP 15
|
|
\f4TBADF\fP
|
|
The specified file descriptor does not refer to a transport
|
|
endpoint.
|
|
.TP
|
|
\f4TSYSERR\fP
|
|
A system error has occurred during execution of this function.
|
|
.TP
|
|
\f4TNOSTRUCTYPE\fP
|
|
Unsupported \f4struct_type\f1 requested. This can include a request for a
|
|
structure type which is inconsistent with the transport provider type
|
|
specified, that is, connection-oriented or connectionless.
|
|
.SH SEE ALSO
|
|
\f4intro\fP(3N), \f4t_free\fP(3N), \f4t_getinfo\fP(3N), \f4t_open\fP(3N)
|
|
.SH DIAGNOSTICS
|
|
On successful completion, \f4t_alloc\fP returns a pointer to the newly
|
|
allocated structure.
|
|
On failure,
|
|
\f4NULL\f1
|
|
is returned.
|
|
.Ee
|