share/man/man3cpc/pctx_set_events.3cpc

   1 '\" te
   2 .\" Copyright (C) 2003, 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 PCTX_SET_EVENTS 3CPC "May 13, 2003"
   7 .SH NAME
   8 pctx_set_events \- associate callbacks with process events
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 cc [ \fIflag\fR... ] \fIfile\fR... \(milpctx [ \fIlibrary\fR... ]
  13 #include <libpctx.h>
  14
  15 typedef enum {
  16         PCTX_NULL_EVENT = 0,
  17         PCTX_SYSC_EXEC_EVENT,
  18         PCTX_SYSC_FORK_EVENT,
  19         PCTX_SYSC_EXIT_EVENT,
  20         PCTX_SYSC_LWP_CREATE_EVENT,
  21         PCTX_INIT_LWP_EVENT,
  22         PCTX_FINI_LWP_EVENT,
  23         PCTX_SYSC_LWP_EXIT_EVENT
  24 } pctx_event_t;
  25
  26 \fBtypedef int\fR \fBpctx_sysc_execfn_t\fR(\fBpctx_t *\fR\fIpctx\fR, \fBpid_t\fR \fIpid\fR, \fBid_t\fR \fIlwpid\fR,
  27      \fBchar *\fR\fIcmd\fR, \fBvoid *\fR\fIarg\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBtypedef void\fR \fBpctx_sysc_forkfn_t\fR(\fBpctx_t *\fR\fIpctx\fR,
  33      \fBpid_t\fR \fIpid\fR, \fBid_t\fR \fIlwpid\fR, \fBpid_t\fR \fIchild\fR, \fBvoid *\fR\fIarg\fR);
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBtypedef void\fR \fBpctx_sysc_exitfn_t\fR(\fBpctx_t *\fR\fIpctx\fR, \fBpid_t\fR \fIpid\fR, \fBid_t\fR \fIlwpid\fR,
  39      \fBvoid *\fR\fIarg\fR);
  40 .fi
  41
  42 .LP
  43 .nf
  44 \fBtypedef int\fR \fBpctx_sysc_lwp_createfn_t\fR(\fBpctx_t *\fR\fIpctx\fR, \fBpid_t\fR \fIpid\fR, \fBid_t\fR \fIlwpid\fR,
  45      \fBvoid *\fR\fIarg\fR);
  46 .fi
  47
  48 .LP
  49 .nf
  50 \fBtypedef int\fR \fBpctx_init_lwpfn_t\fR(\fBpctx_t *\fR\fIpctx\fR, \fBpid_t\fR \fIpid\fR, \fBid_t\fR \fIlwpid\fR,
  51      \fBvoid *\fR\fIarg\fR);
  52 .fi
  53
  54 .LP
  55 .nf
  56 \fBtypedef int\fR \fBpctx_fini_lwpfn_t\fR(\fBpctx_t *\fR\fIpctx\fR, \fBpid_t\fR \fIpid\fR, \fBid_t\fR \fIlwpid\fR,
  57      \fBvoid *\fR\fIarg\fR);
  58 .fi
  59
  60 .LP
  61 .nf
  62 \fBtypedef int\fR \fBpctx_sysc_lwp_exitfn_t\fR(\fBpctx_t *\fR\fIpctx\fR, \fBpid_t\fR \fIpid\fR, \fBid_t\fR \fIlwpid\fR,
  63      \fBvoid *\fR\fIarg\fR);
  64 .fi
  65
  66 .LP
  67 .nf
  68 \fBint\fR \fBpctx_set_events\fR(\fBpctx_t *\fR\fIpctx\fR...);
  69 .fi
  70
  71 .SH DESCRIPTION
  72 .sp
  73 .LP
  74 The \fBpctx_set_events()\fR function allows the caller (the controlling
  75 process) to express interest in various events in the controlled process.  See
  76 \fBpctx_capture\fR(3CPC) for information about how the controlling process is
  77 able to create, capture and manipulate the controlled process.
  78 .sp
  79 .LP
  80 The \fBpctx_set_events()\fR function takes a \fBpctx_t\fR handle, followed by a
  81 variable length list of pairs of \fBpctx_event_t\fR tags and their
  82 corresponding handlers, terminated by a \fBPCTX_NULL_EVENT\fR tag.
  83 .sp
  84 .LP
  85 Most of the events correspond closely to various classes of system calls,
  86 though two additional pseudo-events (\fIinit_lwp\fR and \fIfini_lwp\fR) are
  87 provided to allow callers to perform various housekeeping tasks.  The
  88 \fIinit_lwp\fR handler is called as soon as the library identifies a new
  89 \fBLWP\fR, while \fIfini_lwp\fR is called just before the \fBLWP\fR disappears.
  90 Thus the classic "hello world" program would see an \fIinit_lwp\fR event, a
  91 \fIfini_lwp\fR event and (process) \fIexit\fR event, in that order.   The table
  92 below displays the interactions between the states of the controlled process
  93 and the handlers executed by users of the library.
  94 .sp
  95
  96 .sp
  97 .TS
  98 box;
  99 c | c | c
 100 c | c | c .
 101 System Calls and pctx Handlers
 102 _
 103 System call     Handler Comments
 104 _
 105 \fBexec\fR,\fBexecve\fR \fIfini_lwp\fR  T{
 106 Invoked serially on all lwps in the process.
 107 T}
 108         \fIexec\fR      T{
 109 Only invoked if the \fBexec()\fR system call succeeded.
 110 T}
 111         \fIinit_lwp\fR  T{
 112 If the exec succeeds, only invoked on lwp 1. If the exec fails, invoked serially on all lwps in the process.
 113 T}
 114 _
 115 \fBfork\fR, \fBvfork\fR, \fBfork1\fR    \fIfork\fR      T{
 116 Only invoked if the \fBfork()\fR system call succeeded.
 117 T}
 118 _
 119 \fBexit\fR      \fIfini_lwp\fR  Invoked on all lwps in the process.
 120         \fIexit\fR      Invoked on the exiting lwp.
 121 .TE
 122
 123 .sp
 124 .LP
 125 Each of the handlers is passed the caller's opaque handle, a \fBpctx_t\fR
 126 handle, the pid, and lwpid of the process and lwp generating the event. The
 127 \fIlwp_exit\fR, and (process) \fBexit\fR events are delivered \fIbefore\fR the
 128 underlying system calls begin, while the \fBexec\fR, \fIfork\fR, and
 129 \fIlwp_create\fR events are only delivered after the relevant system calls
 130 complete successfully. The \fBexec\fR handler is passed a string that describes
 131 the command being executed. Catching the \fIfork\fR event causes the calling
 132 process to \fBfork\fR(2), then capture the child of the controlled process
 133 using \fBpctx_capture\fR(\|) before handing control to the \fIfork\fR handler.
 134 The process is released on return from the handler.
 135 .SH RETURN VALUES
 136 .sp
 137 .LP
 138 Upon successful completion, \fBpctx_set_events\fR(\|) returns 0.  Otherwise,
 139 the function returns -1.
 140 .SH EXAMPLES
 141 .LP
 142 \fBExample 1 \fRHandleExec example.
 143 .sp
 144 .LP
 145 This example captures an existing process whose process identifier is
 146 \fIpid\fR, and arranges to call the \fIHandleExec\fR routine when the process
 147 performs an \fBexec\fR(2).
 148
 149 .sp
 150 .in +2
 151 .nf
 152 static void
 153 HandleExec(pctx_t *pctx, pid_t pid, id_t lwpid, char *cmd, void *arg)
 154 {
 155      (void) printf("pid %d execed '%s'\en", (int)pid, cmd);
 156 }
 157 int
 158 main()
 159 {
 160      ...
 161      pctx = pctx_capture(pid, NULL, 1, NULL);
 162      (void) pctx_set_events(pctx,
 163            PCTX_SYSC_EXEC_EVENT, HandleExec,
 164            ...
 165            PCTX_NULL_EVENT);
 166      (void) pctx_run(pctx, 0, 0, NULL);
 167      pctx_release(pctx);
 168 }
 169 .fi
 170 .in -2
 171
 172 .SH ATTRIBUTES
 173 .sp
 174 .LP
 175 See \fBattributes\fR(5) for descriptions of the following attributes:
 176 .sp
 177
 178 .sp
 179 .TS
 180 box;
 181 c | c
 182 l | l .
 183 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 184 _
 185 Interface Stability     Evolving
 186 _
 187 MT-Level        Unsafe
 188 .TE
 189
 190 .SH SEE ALSO
 191 .sp
 192 .LP
 193 \fBexec\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBvfork\fR(2), \fBfork1\fR(2),
 194 \fBcpc\fR(3CPC), \fBlibpctx\fR(3LIB), \fBproc\fR(4), \fBattributes\fR(5)