pctx_create man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

PCTX_CAPTURE(3CPC)					    PCTX_CAPTURE(3CPC)

NAME
       pctx_capture,  pctx_create,  pctx_run,  pctx_release  - process context
       library

SYNOPSIS
       cc [ flag... ] file... −lpctx [ library... ]
       #include <libpctx.h>

       typedef void (pctx_errfn_t)(const char *fn, const char *fmt, va_list ap);

       pctx_t *pctx_create(const char *filename, char *const *argv, void *arg,
	    int verbose, pctx_errfn_t *errfn);

       pctx_t *pctx_capture(pid_t pid, void *arg, int verbose,
	    pctx_errfn_t *errfn);

       int pctx_run(pctx_t *pctx, uint_t sample, uint_t nsamples,
	    int (*tick)(pctx *, pid_t, id_t, void *));

       void pctx_release(pctx_t *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 routines to be invoked in the controlling process.

   pctx_create() and pctx_capture()
       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 pctx_create(), which forks the caller and execs  the
       application  in	the  child.  Alternatively, an existing process can be
       captured by its process ID using pctx_capture().

       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  functions  accept  a	pointer	 to  a
       printf(3C)-like	error  routine errfn; a default version is provided if
       NULL is specified.

       A freshly-created process is created stopped; similarly, a process that
       has  been  successfully captured is stopped by 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 pctx_set_events(3CPC) manual page.

   pctx_run()
       Once the callback handlers have been set	 with  pctx_set_events(),  the
       application  can	 be set running using pctx_run(). 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 performance counters can be sampled
       by the caller. No periodic sampling is performed if sample is 0.

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

RETURN VALUES
       Upon  successful	 completion, pctx_capture() and pctx_create() return a
       valid handle.  Otherwise, the functions print a diagnostic message  and
       return NULL.

       Upon  successful	 completion,  pctx_run() returns 0 with the controlled
       process either stopped or exited (if the controlled 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 controlled
       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  cpc_pctx  family  of	interfaces  in
       libcpc such as cpc_pctx_bind_event(3CPC). A specially created agent LWP
       is used to execute these system calls in the  controlled	 process.  See
       proc(4) for more details.

       While  executing	 the event handler functions, the library arranges for
       the signals SIGTERM, SIGQUIT, SIGABRT, and  SIGINT  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.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Evolving	      │
       ├────────────────────┼─────────────────┤
       │MT-Level	    │ Unsafe	      │
       └────────────────────┴─────────────────┘

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

				 May 13, 2003		    PCTX_CAPTURE(3CPC)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net