Manual Pages for UNIX Operating System command usage for man pthread_atfork

Standard C Library Functions                   pthread_atfork(3C)



NAME
     pthread_atfork - register fork handlers

SYNOPSIS
     #include 
     #include 

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


DESCRIPTION
     The pthread_atfork() function declares fork handlers  to  be
     called  prior  to  and  following fork(2), within the thread
     that called fork(). The order of calls  to  pthread_atfork()
     is significant.


     Before fork() processing begins, the prepare fork handler is
     called.  The prepare handler is not called if its address is
     NULL.


     The parent fork handler is called  after  fork()  processing
     finishes  in  the parent process, and the child fork handler
     is called after fork() processing finishes in the child pro-
     cess.  If  the address of parent or child is  NULL, then its
     handler is not called.


     The prepare fork handler is called in  LIFO (last-in  first-
     out)  order,  whereas the parent and child fork handlers are
     called in  FIFO (first-in  first-out)  order.  This  calling
     order allows applications to preserve locking order.

RETURN VALUES
     Upon successful completion, pthread_atfork() returns 0. Oth-
     erwise, an error number is returned.

ERRORS
     The pthread_atfork() function will fail if:

     ENOMEM     Insufficient table space  exists  to  record  the
                fork handler addresses.


USAGE
     Solaris threads do not offer pthread_atfork()  functionality
     (there  is  no  thr_atfork()  interface). However, a Solaris
     threads application  can  call  pthread_atfork()  to  ensure
     fork()-safety,  since the two thread APIs are interoperable.
     Seefork(2) for information relating to fork() in  a  Solaris



SunOS 5.11          Last change: 12 Dec 2003                    1






Standard C Library Functions                   pthread_atfork(3C)



     threads  environment  in  Solaris  10  relative  to previous
     releases.

EXAMPLES
     Example 1 Make a library safe with respect to fork().


     All multithreaded applications that call fork() in  a  POSIX
     threads  program and do more than simply call exec(2) in the
     child of the fork need to ensure that the child is protected
     from deadlock.



     Since the "fork-one" model results in duplicating  only  the
     thread  that  called fork(), it is possible that at the time
     of the call another thread in the parent owns a  lock.  This
     thread  is  not  duplicated  in the child, so no thread will
     unlock this lock in the child.  Deadlock occurs if the  sin-
     gle thread in the child needs this lock.



     The problem is more serious with locks in libraries.   Since
     a  library writer does not know if the application using the
     library calls fork(), the library must protect  itself  from
     such  a  deadlock  scenario.   If the application that links
     with this library calls fork() and does not call  exec()  in
     the  child,  and if it needs a library lock that may be held
     by some other thread  in  the  parent  that  is  inside  the
     library  at  the time of the fork, the application deadlocks
     inside the library.



     The following describes how to make  a  library   safe  with
     respect to fork() by using  pthread_atfork().


         1.   Identify all locks used by the library (for example
              {L1,...Ln}).  Identify  also  the locking order for
              these locks (for example {L1...Ln}, as well.)

         2.   Add a call to pthread_atfork(f1,  f2,  f3)  in  the
              library's .init section.  f1, f2, f3 are defined as
              follows:

       f1()
       {
               /* ordered in lock order */
               pthread_mutex_lock(L1);
               pthread_mutex_lock(...);



SunOS 5.11          Last change: 12 Dec 2003                    2






Standard C Library Functions                   pthread_atfork(3C)



               pthread_mutex_lock(Ln);
       }

       f2()
       {
               pthread_mutex_unlock(L1);
               pthread_mutex_unlock(...);
               pthread_mutex_unlock(Ln);
       }

       f3()
       {
               pthread_mutex_unlock(L1);
               pthread_mutex_unlock(...);
               pthread_mutex_unlock(Ln);
       }


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



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|
    | Standard                    | See standards(5).           |
    |_____________________________|_____________________________|


SEE ALSO
     exec(2), fork(2), atexit(3C), attributes(5), standards(5)


















SunOS 5.11          Last change: 12 Dec 2003                    3