| blob | 100d57f43c5044ed973f567afd653b9238635c05 |
1 '\" te
2 .\" Copyright 1994, The X/Open Company Ltd., All Rights Reserved. Portions Copyright 1989 AT&T. Portions Copyright (c) 1998, Sun Microsystems, Inc. , All Rights Reserved
3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
4 .\" http://www.opengroup.org/bookstore/.
5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
6 .\" This notice shall appear on any product containing this material.
7 .\" 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.
8 .\" 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.
9 .\" 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]
10 .TH T_ALLOC 3NSL "May 7, 1998"
11 .SH NAME
12 t_alloc \- allocate a library structure
13 .SH SYNOPSIS
14 .LP
15 .nf
16 #include <xti.h>
21 \fBvoid *\fR\fBt_alloc\fR(\fBint\fR \fIfd\fR, \fBint\fR \fIstruct_type\fR, \fBint\fR \fIfields\fR);
22 .fi
24 .SH DESCRIPTION
25 .sp
26 .LP
27 This routine is part of the \fBXTI\fR interfaces which evolved from the
28 \fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these
29 interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When
30 using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, a
31 different header file, \fBtiuser.h\fR, must be used. Refer to the section,
32 \fBTLI\fR \fBCOMPATIBILITY\fR, for a description of differences between the two
33 interfaces.
34 .sp
35 .LP
36 The \fBt_alloc()\fR function dynamically allocates memory for the various
37 transport function argument structures as specified below. This function will
38 allocate memory for the specified structure, and will also allocate memory for
39 buffers referenced by the structure.
40 .sp
41 .LP
42 The structure to allocate is specified by \fIstruct_type\fR and must be one of
43 the following:
44 .sp
45 .in +2
46 .nf
47 T_BIND struct t_bind
48 T_CALL struct t_call
49 T_OPTMGMT struct t_optmgmt
50 T_DIS struct t_discon
51 T_UNITDATA struct t_unitdata
52 T_UDERROR struct t_uderr
53 T_INFO struct t_info
54 .fi
55 .in -2
57 .sp
58 .LP
59 where each of these structures may subsequently be used as an argument to one
60 or more transport functions.
61 .sp
62 .LP
63 Each of the above structures, except \fBT_INFO,\fR contains at least one field
64 of type \fBstruct\fR \fBnetbuf\fR. For each field of this type, the user may
65 specify that the buffer for that field should be allocated as well. The length
66 of the buffer allocated will be equal to or greater than the appropriate size
67 as returned in the \fIinfo\fR argument of \fBt_open\fR(3NSL) or
68 \fBt_getinfo\fR(3NSL). The relevant fields of the \fIinfo\fR argument are
69 described in the following list. The \fIfields\fR argument specifies which
70 buffers to allocate, where the argument is the bitwise-or of any of the
71 following:
72 .sp
73 .ne 2
74 .na
75 \fB\fBT_ADDR\fR \fR
76 .ad
77 .RS 12n
78 The \fIaddr\fR field of the \fBt_bind\fR, \fBt_call\fR, \fBt_unitdata\fR or
79 \fBt_uderr\fR structures.
80 .RE
82 .sp
83 .ne 2
84 .na
85 \fB\fBT_OPT\fR \fR
86 .ad
87 .RS 12n
88 The \fIopt\fR field of the \fBt_optmgmt\fR, \fBt_call\fR, \fBt_unitdata\fR or
89 \fBt_uderr\fR structures.
90 .RE
92 .sp
93 .ne 2
94 .na
95 \fB\fBT_UDATA\fR \fR
96 .ad
97 .RS 12n
98 The \fIudata\fR field of the \fBt_call\fR, \fBt_discon\fR or \fBt_unitdata\fR
99 structures.
100 .RE
102 .sp
103 .ne 2
104 .na
105 \fB\fBT_ALL\fR \fR
106 .ad
107 .RS 12n
108 All relevant fields of the given structure. Fields which are not supported by
109 the transport provider specified by \fIfd\fR will not be allocated.
110 .RE
112 .sp
113 .LP
114 For each relevant field specified in \fIfields\fR, \fBt_alloc()\fR will
115 allocate memory for the buffer associated with the field, and initialize the
116 \fIlen\fR field to zero and the \fIbuf\fR pointer and \fImaxlen\fR field
117 accordingly. Irrelevant or unknown values passed in fields are ignored. Since
118 the length of the buffer allocated will be based on the same size information
119 that is returned to the user on a call to \fBt_open\fR(3NSL) and
120 \fBt_getinfo\fR(3NSL), \fIfd\fR must refer to the transport endpoint through
121 which the newly allocated structure will be passed. In the case where a
122 \fBT_INFO\fR structure is to be allocated, \fIfd\fR may be set to any value. In
123 this way the appropriate size information can be accessed. If the size value
124 associated with any specified field is \fBT_INVALID,\fR \fBt_alloc()\fR will
125 be unable to determine the size of the buffer to allocate and will fail,
126 setting \fBt_errno\fR to \fBTSYSERR\fR and \fBerrno\fR to \fBEINVAL\fR. See
127 \fBt_open\fR(3NSL) or \fBt_getinfo\fR(3NSL). If the size value associated with
128 any specified field is \fBT_INFINITE,\fR then the behavior of \fBt_alloc()\fR
129 is implementation-defined. For any field not specified in \fIfields\fR,
130 \fIbuf\fR will be set to the null pointer and \fIlen\fR and \fImaxlen\fR will
131 be set to zero. See \fBt_open\fR(3NSL) or \fBt_getinfo\fR(3NSL).
132 .sp
133 .LP
134 The pointer returned if the allocation succeeds is suitably aligned so that it
135 can be assigned to a pointer to any type of object and then used to access such
136 an object or array of such objects in the space allocated.
137 .sp
138 .LP
139 Use of \fBt_alloc()\fR to allocate structures will help ensure the
140 compatibility of user programs with future releases of the transport interface
141 functions.
142 .SH RETURN VALUES
143 .sp
144 .LP
145 On successful completion, \fBt_alloc()\fR returns a pointer to the newly
146 allocated structure. On failure, a null pointer is returned.
147 .SH VALID STATES
148 .sp
149 .LP
150 ALL - apart from \fBT_UNINIT\fR
151 .SH ERRORS
152 .sp
153 .LP
154 On failure, \fBt_errno\fR is set to one of the following:
155 .sp
156 .ne 2
157 .na
158 \fB\fBTBADF\fR\fR
159 .ad
160 .RS 16n
161 \fBstruct_type\fR is other than \fBT_INFO\fR and the specified file descriptor
162 does not refer to a transport endpoint.
163 .RE
165 .sp
166 .ne 2
167 .na
168 \fB\fBTNOSTRUCTYPE\fR\fR
169 .ad
170 .RS 16n
171 Unsupported \fIstruct_type\fR requested. This can include a request for a
172 structure type which is inconsistent with the transport provider type
173 specified, that is, connection-mode or connectionless-mode.
174 .RE
176 .sp
177 .ne 2
178 .na
179 \fB\fBTPROTO\fR\fR
180 .ad
181 .RS 16n
182 This error indicates that a communication problem has been detected between XTI
183 and the transport provider for which there is no other suitable XTI error
184 \fB(t_errno)\fR.
185 .RE
187 .sp
188 .ne 2
189 .na
190 \fB\fBTSYSERR\fR\fR
191 .ad
192 .RS 16n
193 A system error has occurred during execution of this function.
194 .RE
196 .SH TLI COMPATIBILITY
197 .sp
198 .LP
199 The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use
200 different header files. This, and other semantic differences between the two
201 interfaces are described in the subsections below.
202 .SS "Interface Header"
203 .sp
204 .LP
205 The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces
206 should \fInot\fR use this header. They should use the header:
207 .sp
208 .LP
209 \fB#include\fR \fB<tiuser.h>\fR
210 .SS "Error Description Values"
211 .sp
212 .LP
213 The \fBt_errno\fR values that can be set by the \fBXTI\fR interface and cannot
214 be set by the \fBTLI\fR interface are:
215 .sp
216 .ne 2
217 .na
218 \fB\fBTPROTO\fR \fR
219 .ad
220 .RS 17n
222 .RE
224 .sp
225 .ne 2
226 .na
227 \fB\fBTNOSTRUCTYPE\fR \fR
228 .ad
229 .RS 17n
231 .RE
233 .SS "Special Buffer Sizes"
234 .sp
235 .LP
236 Assume that the value associated with any field of \fBstruct\fR \fBt_info\fR
237 (argument returned by \fBt_open()\fR or \fBt_getinfo()\fR\|) that describes
238 buffer limits is -1. Then the underlying service provider can support a buffer
239 of unlimited size. If this is the case, \fBt_alloc()\fR will allocate a buffer
240 with the default size 1024 bytes, which may be handled as described in the next
241 paragraph.
242 .sp
243 .LP
244 If the underlying service provider supports a buffer of unlimited size in the
245 \fBnetbuf\fR structure (see \fBt_connect\fR(3NSL)), \fBt_alloc()\fR will return
246 a buffer of size 1024 bytes. If a larger size buffer is required, it will need
247 to be allocated separately using a memory allocation routine such as
248 \fBmalloc\fR(3C). The \fBbuf\fR and \fBmaxlen\fR fields of the \fBnetbuf\fR
249 data structure can then be updated with the address of the new buffer and the
250 1024 byte buffer originally allocated by \fBt_alloc()\fR can be freed using
251 \fBfree\fR(3C).
252 .sp
253 .LP
254 Assume that the value associated with any field of \fBstruct\fR \fBt_info\fR
255 (argument returned by \fBt_open()\fR or \fBt_getinfo()\fR \fB\|)\fR that
256 describes nbuffer limits is \fB-2\fR\&. Then \fBt_alloc()\fR will set the
257 buffer pointer to \fINULL\fR and the buffer maximum size to \fB0\fR, and then
258 will return success (see \fBt_open\fR(3NSL) or \fBt_getinfo\fR(3NSL)).
259 .SH ATTRIBUTES
260 .sp
261 .LP
262 See \fBattributes\fR(5) for descriptions of the following attributes:
263 .sp
265 .sp
266 .TS
267 box;
268 c | c
269 l | l .
270 ATTRIBUTE TYPE ATTRIBUTE VALUE
271 _
272 MT Level Safe
273 .TE
275 .SH SEE ALSO
276 .sp
277 .LP
278 \fBfree\fR(3C), \fBmalloc\fR(3C), \fBt_connect\fR(3NSL), \fBt_free\fR(3NSL),
279 \fBt_getinfo\fR(3NSL), \fBt_open\fR(3NSL), \fBattributes\fR(5)