usr/src/man/man3tnf/tnfctl_buffer_alloc.3tnf

   1 '\" te
   2 .\"  Copyright (c) 1996 Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH TNFCTL_BUFFER_ALLOC 3TNF "Mar 4, 1997"
   7 .SH NAME
   8 tnfctl_buffer_alloc, tnfctl_buffer_dealloc \- allocate or deallocate a buffer
   9 for trace data
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ]
  14 #include <tnf/tnfctl.h>
  15 \fBtnfctl_errcode_t\fR \fBtnfctl_buffer_alloc\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
  16      \fBconst char *\fR\fItrace_file_name\fR, \fBsize_t\fR \fItrace_buffer_size\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fB\fR\fBtnfctl_buffer_dealloc\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR);
  22 .fi
  23
  24 .SH DESCRIPTION
  25 .sp
  26 .LP
  27 \fBtnfctl_buffer_alloc()\fR allocates a buffer to which trace events are
  28 logged. When tracing a process using a  \fBtnfctl\fR handle returned by
  29 \fBtnfctl_pid_open\fR(3TNF), \fBtnfctl_exec_open\fR(3TNF),
  30 \fBtnfctl_indirect_open\fR(3TNF), and \fBtnfctl_internal_open\fR(3TNF)),
  31 \fItrace_file_name\fR is the name of the trace file to which trace events
  32 should be logged. It can be an absolute path specification or a relative path
  33 specification. If it is relative, the current working directory of the process
  34 that is calling  \fBtnfctl_buffer_alloc()\fR is prefixed to
  35 \fItrace_file_name\fR. If the named trace file already exists, it is
  36 overwritten. For kernel tracing, that is, for a tnfctl handle returned by
  37 \fBtnfctl_kernel_open\fR(3TNF), trace events are logged to a trace buffer in
  38 memory; therefore, \fItrace_file_name\fR is ignored.  Use \fBtnfxtract\fR(1) to
  39 extract a kernel buffer into a file.
  40 .sp
  41 .LP
  42 \fItrace_buffer_size\fR is the size in bytes of the trace buffer that should be
  43 allocated. An error is returned if an attempt is made to allocate a buffer when
  44 one already exists.   \fBtnfctl_buffer_alloc()\fR affects the trace attributes;
  45 use  \fBtnfctl_trace_attrs_get\fR(3TNF) to get the latest trace attributes
  46 after a buffer is allocated.
  47 .sp
  48 .LP
  49 \fBtnfctl_buffer_dealloc()\fR is used to deallocate a kernel trace buffer that
  50 is no longer needed. \fIhndl\fR must be a kernel handle, returned by
  51 \fBtnfctl_kernel_open\fR(3TNF). A process's trace file cannot be deallocated
  52 using \fBtnfctl_buffer_dealloc()\fR. Instead, once the trace file is no longer
  53 needed for analysis and after  the process being traced exits, use \fBrm\fR(1)
  54 to remove the trace file. Do not remove the trace file while the process being
  55 traced is still alive. \fBtnfctl_buffer_dealloc()\fR affects the trace
  56 attributes; use  \fBtnfctl_trace_attrs_get\fR(3TNF) to get the latest trace
  57 attributes after a buffer is deallocated.
  58 .sp
  59 .LP
  60 For a complete discussion of  \fBtnf tracing\fR, see \fBtracing\fR(3TNF).
  61 .SH RETURN VALUES
  62 .sp
  63 .LP
  64 \fBtnfctl_buffer_alloc()\fR and \fBtnfctl_buffer_dealloc()\fR return
  65 \fBTNFCTL_ERR_NONE\fR upon success.
  66 .SH ERRORS
  67 .sp
  68 .LP
  69 The following error codes apply to \fBtnfctl_buffer_alloc()\fR:
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fBTNFCTL_ERR_BUFEXISTS\fR\fR
  74 .ad
  75 .RS 27n
  76 A buffer already exists.
  77 .RE
  78
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fBTNFCTL_ERR_ACCES\fR\fR
  83 .ad
  84 .RS 27n
  85 Permission denied; could not create a trace file.
  86 .RE
  87
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fBTNFCTL_ERR_SIZETOOSMALL\fR\fR
  92 .ad
  93 .RS 27n
  94 The  \fItrace_buffer_size\fR requested is smaller than the minimum trace buffer
  95 size needed. Use \fBtrace_min_size\fR of trace attributes in
  96 \fBtnfctl_trace_attrs_get\fR(3TNF) to determine the minimum size of the buffer.
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBTNFCTL_ERR_SIZETOOBIG\fR\fR
 103 .ad
 104 .RS 27n
 105 The requested trace file size is too big.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBTNFCTL_ERR_BADARG\fR\fR
 112 .ad
 113 .RS 27n
 114 \fItrace_file_name\fR is  \fINULL\fR or the absolute path name is longer than
 115 \fBMAX\fR\fBPATH\fR\fBLEN.\fR
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR
 122 .ad
 123 .RS 27n
 124 A memory allocation failure occurred.
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBTNFCTL_ERR_INTERNAL\fR\fR
 131 .ad
 132 .RS 27n
 133 An internal error occurred.
 134 .RE
 135
 136 .sp
 137 .LP
 138 The following error codes apply to \fBtnfctl_buffer_dealloc()\fR:
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBTNFCTL_ERR_BADARG\fR\fR
 143 .ad
 144 .RS 25n
 145 \fIhndl\fR is not a kernel handle.
 146 .RE
 147
 148 .sp
 149 .ne 2
 150 .na
 151 \fB\fBTNFCTL_ERR_NOBUF\fR\fR
 152 .ad
 153 .RS 25n
 154 No buffer exists to deallocate.
 155 .RE
 156
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fBTNFCTL_ERR_BADDEALLOC\fR\fR
 161 .ad
 162 .RS 25n
 163 Cannot deallocate a trace buffer unless tracing is stopped. Use
 164 \fBtnfctl_trace_state_set\fR(3TNF) to stop tracing.
 165 .RE
 166
 167 .sp
 168 .ne 2
 169 .na
 170 \fB\fBTNFCTL_ERR_INTERNAL\fR\fR
 171 .ad
 172 .RS 25n
 173 An internal error occurred.
 174 .RE
 175
 176 .SH ATTRIBUTES
 177 .sp
 178 .LP
 179 See \fBattributes\fR(5) for descriptions of the following attributes:
 180 .sp
 181
 182 .sp
 183 .TS
 184 box;
 185 c | c
 186 l | l .
 187 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 188 _
 189 MT Level        MT-Safe
 190 .TE
 191
 192 .SH SEE ALSO
 193 .sp
 194 .LP
 195 \fBprex\fR(1), \fBrm\fR(1), \fBtnfxtract\fR(1), \fBTNF_PROBE\fR(3TNF),
 196 \fBlibtnfctl\fR(3TNF), \fBtnfctl_exec_open\fR(3TNF),
 197 \fBtnfctl_indirect_open\fR(3TNF), \fBtnfctl_internal_open\fR(3TNF),
 198 \fBtnfctl_kernel_open\fR(3TNF), \fBtnfctl_pid_open\fR(3TNF),
 199 \fBtnfctl_trace_attrs_get\fR(3TNF), \fBtracing\fR(3TNF), \fBattributes\fR(5)