1t_alloc(3NSL) Networking Services Library Functions t_alloc(3NSL)
2
6 t_alloc - allocate a library structure
7
9 #include <xti.h>
10 void *t_alloc(int fd, int struct_type, int fields);
15
18 This routine is part of the XTI interfaces which evolved from the TLI
19 interfaces. XTI represents the future evolution of these interfaces.
20 However, TLI interfaces are supported for compatibility. When using a
21 TLI routine that has the same name as an XTI routine, a different
22 header file, tiuser.h, must be used. Refer to the section, TLI COMPAT‐
23 IBILITY, for a description of differences between the two interfaces.
24 The t_alloc() function dynamically allocates memory for the various
27 transport function argument structures as specified below. This func‐
28 tion will allocate memory for the specified structure, and will also
29 allocate memory for buffers referenced by the structure.
30 The structure to allocate is specified by struct_type and must be one
33 of the following:
34 T_BIND struct t_bind
36 T_CALL struct t_call
37 T_OPTMGMT struct t_optmgmt
38 T_DIS struct t_discon
39 T_UNITDATA struct t_unitdata
40 T_UDERROR struct t_uderr
41 T_INFO struct t_info
42 where each of these structures may subsequently be used as an argument
46 to one or more transport functions.
47 Each of the above structures, except T_INFO, contains at least one
50 field of type struct netbuf. For each field of this type, the user may
51 specify that the buffer for that field should be allocated as well. The
52 length of the buffer allocated will be equal to or greater than the
53 appropriate size as returned in the info argument of t_open(3NSL) or
54 t_getinfo(3NSL). The relevant fields of the info argument are described
55 in the following list. The fields argument specifies which buffers to
56 allocate, where the argument is the bitwise-or of any of the following:
57 T_ADDR The addr field of the t_bind, t_call, t_unitdata or t_uderr
59 structures.
60 T_OPT The opt field of the t_optmgmt, t_call, t_unitdata or
63 t_uderr structures.
64 T_UDATA The udata field of the t_call, t_discon or t_unitdata
67 structures.
68 T_ALL All relevant fields of the given structure. Fields which
71 are not supported by the transport provider specified by fd
72 will not be allocated.
73 For each relevant field specified in fields, t_alloc() will allocate
77 memory for the buffer associated with the field, and initialize the len
78 field to zero and the buf pointer and maxlen field accordingly. Irrele‐
79 vant or unknown values passed in fields are ignored. Since the length
80 of the buffer allocated will be based on the same size information that
81 is returned to the user on a call to t_open(3NSL) and t_getinfo(3NSL),
82 fd must refer to the transport endpoint through which the newly allo‐
83 cated structure will be passed. In the case where a T_INFO structure
84 is to be allocated, fd may be set to any value. In this way the appro‐
85 priate size information can be accessed. If the size value associated
86 with any specified field is T_INVALID, t_alloc() will be unable to
87 determine the size of the buffer to allocate and will fail, setting
88 t_errno to TSYSERR and errno to EINVAL. See t_open(3NSL) or t_get‐
89 info(3NSL). If the size value associated with any specified field is
90 T_INFINITE, then the behavior of t_alloc() is implementation-defined.
91 For any field not specified in fields, buf will be set to the null
92 pointer and len and maxlen will be set to zero. See t_open(3NSL) or
93 t_getinfo(3NSL).
94 The pointer returned if the allocation succeeds is suitably aligned so
97 that it can be assigned to a pointer to any type of object and then
98 used to access such an object or array of such objects in the space
99 allocated.
100 Use of t_alloc() to allocate structures will help ensure the compati‐
103 bility of user programs with future releases of the transport interface
104 functions.
105
107 On successful completion, t_alloc() returns a pointer to the newly
108 allocated structure. On failure, a null pointer is returned.
109
111 ALL - apart from T_UNINIT
112
114 On failure, t_errno is set to one of the following:
115 TBADF struct_type is other than T_INFO and the specified
117 file descriptor does not refer to a transport endpoint.
118 TNOSTRUCTYPE Unsupported struct_type requested. This can include a
121 request for a structure type which is inconsistent with
122 the transport provider type specified, that is, connec‐
123 tion-mode or connectionless-mode.
124 TPROTO This error indicates that a communication problem has
127 been detected between XTI and the transport provider
128 for which there is no other suitable XTI error
129 (t_errno).
130 TSYSERR A system error has occurred during execution of this
133 function.
134
137 The XTI and TLI interface definitions have common names but use differ‐
138 ent header files. This, and other semantic differences between the two
139 interfaces are described in the subsections below.
140 Interface Header
142 The XTI interfaces use the header file, xti.h. TLI interfaces should
143 not use this header. They should use the header:
144 #include <tiuser.h>
147 Error Description Values
149 The t_errno values that can be set by the XTI interface and cannot be
150 set by the TLI interface are:
151 TPROTO
153 TNOSTRUCTYPE
156 Special Buffer Sizes
159 Assume that the value associated with any field of struct t_info (argu‐
160 ment returned by t_open() or t_getinfo()) that describes buffer limits
161 is -1. Then the underlying service provider can support a buffer of
162 unlimited size. If this is the case, t_alloc() will allocate a buffer
163 with the default size 1024 bytes, which may be handled as described in
164 the next paragraph.
165 If the underlying service provider supports a buffer of unlimited size
168 in the netbuf structure (see t_connect(3NSL)), t_alloc() will return a
169 buffer of size 1024 bytes. If a larger size buffer is required, it will
170 need to be allocated separately using a memory allocation routine such
171 as malloc(3C). The buf and maxlen fields of the netbuf data structure
172 can then be updated with the address of the new buffer and the 1024
173 byte buffer originally allocated by t_alloc() can be freed using
174 free(3C).
175 Assume that the value associated with any field of struct t_info (argu‐
178 ment returned by t_open() or t_getinfo() ) that describes nbuffer lim‐
179 its is -2. Then t_alloc() will set the buffer pointer to NULL and the
180 buffer maximum size to 0, and then will return success (see
181 t_open(3NSL) or t_getinfo(3NSL)).
182
184 See attributes(5) for descriptions of the following attributes:
185 ┌─────────────────────────────┬─────────────────────────────┐
190 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
191 ├─────────────────────────────┼─────────────────────────────┤
192 │MT Level │Safe │
193 └─────────────────────────────┴─────────────────────────────┘
194
196 free(3C), malloc(3C), t_connect(3NSL), t_free(3NSL), t_getinfo(3NSL),
197 t_open(3NSL), attributes(5)
198SunOS 5.11 7 May 1998 t_alloc(3NSL)