usr/src/man/man3nsl/t_free.3nsl

   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_FREE 3NSL "May 7, 1998"
  11 .SH NAME
  12 t_free \- free a library structure
  13 .SH SYNOPSIS
  14 .LP
  15 .nf
  16 #include <xti.h>
  17
  18
  19
  20
  21 \fBint\fR \fBt_free\fR(\fBvoid *\fR\fIptr\fR, \fBint\fR \fIstruct_type\fR);
  22 .fi
  23
  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, the
  31 \fBtiuser.h\fR header file must be used.  Refer to the  \fBTLI\fR
  32 \fBCOMPATIBILITY\fR section for a description of differences between the two
  33 interfaces.
  34 .sp
  35 .LP
  36 The \fBt_free()\fR function frees memory previously allocated by
  37 \fBt_alloc\fR(3NSL). This function will free memory for the specified
  38 structure, and will also free memory for buffers referenced by the structure.
  39 .sp
  40 .LP
  41 The argument \fIptr\fR points to one of the seven structure types described for
  42 \fBt_alloc\fR(3NSL), and \fIstruct_type\fR identifies the type of that
  43 structure which must be one of 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
  56
  57 .sp
  58 .LP
  59 where each of these structures is used as an argument to one or more transport
  60 functions.
  61 .sp
  62 .LP
  63 The function \fBt_free()\fR will check the \fIaddr\fR, \fIopt\fR and
  64 \fIudata\fR fields of the given structure, as appropriate, and free the buffers
  65 pointed to by the \fIbuf\fR field of the \fBnetbuf\fR structure. If \fIbuf\fR
  66 is a null pointer, \fBt_free()\fR will not attempt to free memory.  After all
  67 buffers are freed, \fBt_free()\fR will free the memory associated with the
  68 structure pointed to by \fIptr\fR.
  69 .sp
  70 .LP
  71 Undefined results will occur if \fIptr\fR or any of the \fIbuf\fR pointers
  72 points to a block of memory that was not previously allocated by
  73 \fBt_alloc\fR(3NSL).
  74 .SH RETURN VALUES
  75 .sp
  76 .LP
  77 Upon successful completion, a value of  \fB0\fR is returned.  Otherwise, a
  78 value of  -1 is returned and \fBt_errno\fR is set to indicate an error.
  79 .SH VALID STATES
  80 .sp
  81 .LP
  82 ALL - apart from \fBT_UNINIT\fR.
  83 .SH ERRORS
  84 .sp
  85 .LP
  86 On failure, \fBt_errno\fR is set to the following:
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBTNOSTRUCTYPE\fR\fR
  91 .ad
  92 .RS 16n
  93 Unsupported \fIstruct_type\fR requested.
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fBTPROTO\fR\fR
 100 .ad
 101 .RS 16n
 102 This error indicates that a communication problem has been detected between XTI
 103 and the transport provider for which there is no other suitable XTI error
 104 \fI(t_errno)\fR.
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBTSYSERR\fR\fR
 111 .ad
 112 .RS 16n
 113 A system error has occurred during execution of this function.
 114 .RE
 115
 116 .SH TLI COMPATIBILITY
 117 .sp
 118 .LP
 119 The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use
 120 different header files. This, and other semantic differences between the two
 121 interfaces are described in the subsections below.
 122 .SS "Interface Header"
 123 .sp
 124 .LP
 125 The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces
 126 should \fInot\fR use this header.  They should use the header:
 127 .sp
 128 .in +2
 129 .nf
 130 #include <tiuser.h>
 131 .fi
 132 .in -2
 133
 134 .SS "Error Description Values"
 135 .sp
 136 .LP
 137 The \fBt_errno\fR value that can be set by the \fBXTI\fR interface and cannot
 138 be set by the \fBTLI\fR interface is:
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBTPROTO\fR \fR
 143 .ad
 144 .RS 11n
 145
 146 .RE
 147
 148 .SH ATTRIBUTES
 149 .sp
 150 .LP
 151 See \fBattributes\fR(5)  for descriptions of the following attributes:
 152 .sp
 153
 154 .sp
 155 .TS
 156 box;
 157 c | c
 158 l | l .
 159 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 160 _
 161 MT Level        Safe
 162 .TE
 163
 164 .SH SEE ALSO
 165 .sp
 166 .LP
 167 \fBt_alloc\fR(3NSL), \fBattributes\fR(5)