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

   1 '\" te
   2 .\"  Copyright (c) 2004 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_INTERNAL_OPEN 3TNF "Mar 1, 2004"
   7 .SH NAME
   8 tnfctl_internal_open \- create handle for internal process probe control
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ]
  13 #include <tnf/tnfctl.h>
  14
  15
  16
  17 \fBtnfctl_errcode_t\fR \fBtnfctl_internal_open\fR(\fBtnfctl_handle_t **\fR\fIret_val\fR);
  18 .fi
  19
  20 .SH DESCRIPTION
  21 .sp
  22 .LP
  23 \fBtnfctl_internal_open()\fR returns in \fIret_val\fR a pointer to an opaque
  24 handle that can be used to control probes in the same process as the caller
  25 (internal process probe control). The process must have  \fBlibtnfprobe.so.1\fR
  26 loaded. Probes in libraries that are brought in by \fBdlopen\fR(3C) will be
  27 visible after the library has been opened. Probes in libraries closed by a
  28 \fBdlclose\fR(3C) will not be visible after the library has been disassociated.
  29 See the \fBNOTES\fR section for more details.
  30 .SH RETURN VALUES
  31 .sp
  32 .LP
  33 \fBtnfctl_internal_open()\fR returns \fBTNFCTL_ERR_NONE\fR upon success.
  34 .SH ERRORS
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR
  39 .ad
  40 .RS 28n
  41 A memory allocation failure occurred.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fBTNFCTL_ERR_BUSY\fR\fR
  48 .ad
  49 .RS 28n
  50 Another client is already tracing this program (internally or externally).
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR
  57 .ad
  58 .RS 28n
  59 \fBlibtnfprobe.so.1\fR is not linked in the target process.
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fBTNFCTL_ERR_INTERNAL\fR\fR
  66 .ad
  67 .RS 28n
  68 An internal error occurred.
  69 .RE
  70
  71 .SH ATTRIBUTES
  72 .sp
  73 .LP
  74 See \fBattributes\fR(5) for descriptions of the following attributes:
  75 .sp
  76
  77 .sp
  78 .TS
  79 box;
  80 c | c
  81 l | l .
  82 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  83 _
  84 MT Level        MT-Safe
  85 .TE
  86
  87 .SH SEE ALSO
  88 .sp
  89 .LP
  90 \fBld\fR(1), \fBprex\fR(1), \fBTNF_PROBE\fR(3TNF), \fBdlopen\fR(3C),
  91 \fBdlclose\fR(3C), \fBlibtnfctl\fR(3TNF), \fBtracing\fR(3TNF),
  92 \fBattributes\fR(5)
  93 .sp
  94 .LP
  95 \fILinker and Libraries Guide\fR
  96 .SH NOTES
  97 .sp
  98 .LP
  99 \fBlibtnfctl\fR interposes on \fBdlopen\fR(3C) and \fBdlclose\fR(3C) in order
 100 to be notified of libraries being dynamically opened and closed. This
 101 interposition is necessary for internal process probe control to update its
 102 list of probes. In these interposition functions, a lock is acquired to
 103 synchronize on traversal of the library list maintained by the runtime linker.
 104 To avoid deadlocking on this lock, \fBtnfctl_internal_open()\fR should not be
 105 called from within the init section of a library that can be opened by
 106 \fBdlopen\fR(3C).
 107 .sp
 108 .LP
 109 Since interposition does not work as expected when a library is opened
 110 dynamically, \fBtnfctl_internal_open()\fR should not be used if the client
 111 opened  \fBlibtnfctl\fR through  \fBdlopen\fR(3C). In this case, the client
 112 program should be built with a static dependency on \fBlibtnfctl.\fR Also, if
 113 the client program is explicitly linking in \fB-ldl\fR, it should link
 114 \fB-ltnfctl\fR before \fB-ldl\fR.
 115 .sp
 116 .LP
 117 Probes in filtered libraries (see \fBld\fR(1)) will not be seen because the
 118 filtee (backing library) is loaded lazily on the first symbol reference and not
 119 at process startup or \fBdlopen\fR(3C) time. A workaround is to call
 120 \fBtnfctl_check_libs\fR(3TNF) once the caller is sure that the filtee has been
 121 loaded.