pctx_set_events 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_SET_EVENTS(3CPC)					 PCTX_SET_EVENTS(3CPC)

NAME
       pctx_set_events - associate callbacks with process events

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

       typedef	 enum {
	       PCTX_NULL_EVENT = 0,
	       PCTX_SYSC_EXEC_EVENT,
	       PCTX_SYSC_FORK_EVENT,
	       PCTX_SYSC_EXIT_EVENT,
	       PCTX_SYSC_LWP_CREATE_EVENT,
	       PCTX_INIT_LWP_EVENT,
	       PCTX_FINI_LWP_EVENT,
	       PCTX_SYSC_LWP_EXIT_EVENT
       } pctx_event_t;

       typedef int pctx_sysc_execfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
	    char *cmd, void *arg);

       typedef void pctx_sysc_forkfn_t(pctx_t *pctx,
	    pid_t pid, id_t lwpid, pid_t child, void *arg);

       typedef void pctx_sysc_exitfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
	    void *arg);

       typedef int pctx_sysc_lwp_createfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
	    void *arg);

       typedef int pctx_init_lwpfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
	    void *arg);

       typedef int pctx_fini_lwpfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
	    void *arg);

       typedef int pctx_sysc_lwp_exitfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
	    void *arg);

       int pctx_set_events(pctx_t *pctx...);

DESCRIPTION
       The  pctx_set_events()  function	 allows	 the  caller  (the controlling
       process) to express  interest  in  various  events  in  the  controlled
       process.	 See pctx_capture(3CPC) for information about how the control‐
       ling process is able to create, capture and manipulate  the  controlled
       process.

       The  pctx_set_events()  function	 takes	a pctx_t handle, followed by a
       variable length list of pairs of pctx_event_t  tags  and	 their	corre‐
       sponding handlers, terminated by a PCTX_NULL_EVENT tag.

       Most  of	 the  events  correspond  closely to various classes of system
       calls, though two additional pseudo-events (init_lwp and fini_lwp)  are
       provided	 to  allow callers to perform various housekeeping tasks.  The
       init_lwp handler is called as soon as the library identifies a new LWP,
       while  fini_lwp	is  called  just  before the LWP disappears.  Thus the
       classic "hello world" program would see an init_lwp event,  a  fini_lwp
       event  and  (process) exit event, in that order.	  The table below dis‐
       plays the interactions between the states of the controlled process and
       the handlers executed by users of the library.

       ┌───────────────────────────────┬──────────┬─────────────────────────────────────┐
       │System Calls and pctx Handlers │	  │					│
       ├───────────────────────────────┼──────────┼─────────────────────────────────────┤
       │	 System call	       │ Handler  │		 Comments		│
       ├───────────────────────────────┼──────────┼─────────────────────────────────────┤
       │	 exec,execve	       │ fini_lwp │ Invoked serially on all lwps in the │
       │			       │	  │ process.				│
       │			       │   exec	  │ Only invoked if the	 exec()	 system │
       │			       │	  │ call succeeded.			│
       │			       │ init_lwp │ If	the exec succeeds, only invoked │
       │			       │	  │ on	lwp  1.	 If  the  exec	 fails, │
       │			       │	  │ invoked serially on all lwps in the │
       │			       │	  │ process.				│
       ├───────────────────────────────┼──────────┼─────────────────────────────────────┤
       │      fork, vfork, fork1       │   fork	  │ Only invoked if the	 fork()	 system │
       │			       │	  │ call succeeded.			│
       ├───────────────────────────────┼──────────┼─────────────────────────────────────┤
       │	     exit	       │ fini_lwp │ Invoked on all lwps in the process. │
       │			       │   exit	  │	Invoked on the exiting lwp.	│
       └───────────────────────────────┴──────────┴─────────────────────────────────────┘

       Each  of	 the  handlers	is passed the caller's opaque handle, a pctx_t
       handle, the pid, and lwpid of the process and lwp generating the event.
       The lwp_exit, and (process) exit events are delivered before the under‐
       lying system calls begin, while the exec, fork, and  lwp_create	events
       are  only  delivered  after the relevant system calls complete success‐
       fully. The exec handler is passed a string that describes  the  command
       being  executed.	 Catching the fork event causes the calling process to
       fork(2), then  capture  the  child  of  the  controlled	process	 using
       pctx_capture() before handing control to the fork handler.  The process
       is released on return from the handler.

RETURN VALUES
       Upon successful completion, pctx_set_events()  returns  0.   Otherwise,
       the function returns -1.

EXAMPLES
       Example 1 HandleExec example.

       This  example  captures an existing process whose process identifier is
       pid, and arranges to call the HandleExec routine when the process  per‐
       forms an exec(2).

	 static void
	 HandleExec(pctx_t *pctx, pid_t pid, id_t lwpid, char *cmd, void *arg)
	 {
	      (void) printf("pid %d execed '%s'\n", (int)pid, cmd);
	 }
	 int
	 main()
	 {
	      ...
	      pctx = pctx_capture(pid, NULL, 1, NULL);
	      (void) pctx_set_events(pctx,
		    PCTX_SYSC_EXEC_EVENT, HandleExec,
		    ...
		    PCTX_NULL_EVENT);
	      (void) pctx_run(pctx, 0, 0, NULL);
	      pctx_release(pctx);
	 }

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

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

SEE ALSO
       exec(2),	   exit(2),    fork(2),	   vfork(2),	fork1(2),   cpc(3CPC),
       libpctx(3LIB), proc(4), attributes(5)

				 May 13, 2003		 PCTX_SET_EVENTS(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