NAME    [Toc]    [Back]

       pthread_atfork  -  Declares  fork  handler  routines to be
       called when the calling thread's  process  forks  a  child
       process

SYNOPSIS    [Toc]    [Back]

       #include <pthread.h>

       int pthread_atfork(
               void (*prepare)(void),
               void (*parent)(void),
               void (*child)(void) );

LIBRARY    [Toc]    [Back]

       Standard C Library (libc.so, libc.a)

STANDARDS    [Toc]    [Back]

       Interfaces  documented  on  this reference page conform to
       industry standards as follows:

       IEEE Std 1003.1c-1995, POSIX  System  Application  Program
       Interface

PARAMETERS    [Toc]    [Back]

       Address  of  a  routine that performs the fork preparation
       handling. This routine is called  in  the  parent  process
       before  creating  the child process.  Address of a routine
       that performs the fork parent handling.  This  routine  is
       called in the parent process after creating the child process
 and  before  returning  to  the  caller  of  fork(2).
       Address  of  a  routine  that performs the fork child handling.
 This routine is called in the child process  before
       returning to the caller of fork(2).

DESCRIPTION    [Toc]    [Back]

       This  routine  allows a main program or library to control
       resources during a fork(2)  operation  by  declaring  fork
       handler  routines,  as  follows:  The fork handler routine
       specified in the prepare argument is called before fork(2)
       executes.   The fork handler routine specified in the parent
 argument is called after fork(2) executes  within  the
       parent process.  The fork handler routine specified in the
       child argument is called in the new  child  process  after
       fork(2) executes.

       Your  program (or library) can use fork handlers to ensure
       that program context in the child  process  is  consistent
       and  meaningful.  After  fork() executes, only the calling
       thread exists in the child process, and the state  of  all
       memory  in  the  parent process is replicated in the child
       process, including the states of  any  mutexes,  condition
       variables, and so on.

       For  example,  in  the new child process there might exist
       locked mutexes that are copies of mutexes that were locked
       in  the parent process by threads that do not exist in the
       child process. Therefore,  any  associated  program  state
       might be inconsistent in the child process.

       The   program   can   avoid   this   problem   by  calling
       pthread_atfork  to  provide  routines  that  acquire   and
       release  resources that are critical to the child process.
       For example, the prepare handler should lock  all  mutexes
       that  you want to be usable in the child process. The parent
 handler just unlocks those mutexes. The child  handler
       will  also  unlock them all--and might also create threads
       or reset any program state for the child process.

       If no fork handling is desired, you can set  any  of  this
       routine's arguments to NULL.

NOTES    [Toc]    [Back]

       It  is not legal to call pthread_atfork from within a fork
       handler routine. Doing so could cause a deadlock.

RETURN VALUES    [Toc]    [Back]

       If an error condition  occurs,  this  routine  returns  an
       integer  value  indicating  the  type  of  error. Possible
       return values are as follows: Successful completion Insufficient
 table space exists to record the fork handler routines'
 addresses.

ERRORS    [Toc]    [Back]

       None

EXAMPLES    [Toc]    [Back]

       For example, if your library uses a  mutex  my_mutex,  you
       might  provide  pthread_atfork  handler  routines coded as
       follows:

        void  my_prepare(void)
              {
              pthread_mutex_lock(&my_mutex);
              }

        void  my_parent(void)
              {
              pthread_mutex_unlock(&my_mutex);
              }

        void  my_child(void)
              {
              pthread_mutex_unlock(&my_mutex);
              /* Reinitialize  state  that  doesn't  apply...like
       heap owned */
              /* by other threads         */
              }

           {
              .
              .
              .

            pthread_atfork(my_prepare, my_parent, my_child);
              .
              .
            fork();
           }

SEE ALSO    [Toc]    [Back]

       Functions: pthread_create(3)

       Manuals: Guide to DECthreads, Programmer's Guide



                                                pthread_atfork(3)