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