CPU Performance Counters Library Functions     pctxcapture(3CPC)



NAME
     pctxcapture, pctxcreate, pctxrun, pctxrelease -  process
     context library

SYNOPSIS
     cc [ flag... ] file... -lpctx [ library... ]
     #include 

     typedef void (pctxerrfnt)(const char *fn, const char *fmt, valist ap);


     pctxt *pctxcreate(const char *filename, char *const *argv, void *arg,
          int verbose, pctxerrfnt *errfn);


     pctxt *pctxcapture(pidt pid, void *arg, int verbose,
          pctxerrfnt *errfn);


     int pctxrun(pctxt *pctx, uintt sample, uintt nsamples,
          int (*tick)(pctx *, pidt, idt, void *));


     void pctxrelease(pctxt *pctx);


DESCRIPTION
     This family of functions allows a controlling  process  (the
     process  that  invokes them) to create or capture controlled
     processes.  The functions allow the  occurrence  of  various
     events  of  interest  in the controlled process to cause the
     controlled process to be stopped, and to cause callback rou-
     tines to be invoked in the controlling process.

  pctxcreate() and pctxcapture()
     There are two ways a process can be acquired by the  process
     context  functions.   First,  a  named  application  can  be
     invoked with the usual  argv[]  array  using  pctxcreate(),
     which  forks  the  caller  and  execs the application in the
     child. Alternatively, an existing process can be captured by
     its process ID using pctxcapture().


     Both functions accept a pointer to an  opaque  handle,  arg;
     this is saved and treated as a caller-private handle that is
     passed to the other functions in the  library.   Both  func-
     tions  accept  a  pointer to a printf(3C)-like error routine
     errfn; a default version is provided if NUL is specified.


     A freshly-created process is created stopped;  similarly,  a
     process  that  has  been successfully captured is stopped by



SunOS 5.11          Last change: 13 May 2003                    1






CPU Performance Counters Library Functions     pctxcapture(3CPC)



     the act of capturing it,  thereby  allowing  the  caller  to
     specify  the  handlers  that  should  be called when various
     events occur in the controlled process.  The set of handlers
     is listed on the pctxsetevents(3CPC) manual page.

  pctxrun()
     Once   the   callback   handlers   have   been   set    with
     pctxsetevents(),  the application can be set running using
     pctxrun(). This function starts the event handling loop; it
     returns  only when either the process has exited, the number
     of time samples has expired, or an error has  occurred  (for
     example,  if  the controlling process is not privileged, and
     the controlled process has exec-ed a setuid program).


     Every sample milliseconds the process  is  stopped  and  the
     tick()  routine  is called so that, for example, the perfor-
     mance counters can be sampled by  the  caller.  No  periodic
     sampling is performed if sample is 0.

  pctxrelease()
     Once  pctxrun() has returned, the process can  be  released
     and  the  underlying  storage  freed  using  pctxrelease().
     Releasing the process will either allow the controlled  pro-
     cess  to  continue (in the case of an existing captured pro-
     cess and its children) or kill the process (if  it  and  its
     children were created using pctxcreate()).

RETURN VALUES
     Upon successful completion, pctxcapture() and pctxcreate()
     return  a  valid  handle.   Otherwise, the functions print a
     diagnostic message and return NUL.


     Upon successful completion, pctxrun() returns  0  with  the
     controlled  process  either  stopped  or exited (if the con-
     trolled process  has  invoked  exit(2).)  If  an  error  has
     occurred (for example, if the controlled process has exec-ed
     a set-ID executable,  if  certain  callbacks  have  returned
     error  indications,  or if the process was unable to respond
     to proc(4) requests) an error message  is  printed  and  the
     function returns -1.

USAGE
     Within an event handler in the controlling process, the con-
     trolled  process can be made to perform various system calls
     on its behalf. No system calls  are  directly  supported  in
     this version of the API, though system calls are executed by
     the  cpcpctx  family  of  interfaces  in  libcpc  such   as
     cpcpctxbindevent(3CPC).  A specially created agent LWP is
     used to execute these system calls in  the  controlled  pro-
     cess. See proc(4) for more details.



SunOS 5.11          Last change: 13 May 2003                    2






CPU Performance Counters Library Functions     pctxcapture(3CPC)



     While executing the event  handler  functions,  the  library
     arranges for the signals SIGTERM, SIGQUIT, SIGABRT, and SIG-
     INT to be blocked to reduce the  likelihood  of  a  keyboard
     signal  killing the controlling process prematurely, thereby
     leaving the controlled process permanently stopped while the
     agent LWP is still alive inside the controlled process.

ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Evolving                    
    
     MT-Level                     Unsafe                      
    


SEE ALSO
     fork(2),  cpc(3CPC),  pctxsetevents(3CPC),  libpctx(3LIB),
     proc(4), attributes(5)






























SunOS 5.11          Last change: 13 May 2003                    3