Standard C Library Functions                   pthreadatfork(3C)



NAME
     pthreadatfork - register fork handlers

SYNOPSIS
     #include 
     #include 

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


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


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


     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  NUL, 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, pthreadatfork() returns 0. Oth-
     erwise, an error number is returned.

ERORS
     The pthreadatfork() function will fail if:

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


USAGE
     Solaris threads do not offer pthreadatfork()  functionality
     (there  is  no  thratfork()  interface). However, a Solaris
     threads application  can  call  pthreadatfork()  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                   pthreadatfork(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  pthreadatfork().


         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 pthreadatfork(f1,  f2,  f3)  in  the
              library's .init section.  f1, f2, f3 are defined as
              follows:

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



SunOS 5.11          Last change: 12 Dec 2003                    2






Standard C Library Functions                   pthreadatfork(3C)



                       pthreadmutexlock(Ln);
               }

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

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


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



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Standard                    
    
     MT-Level                     MT-Safe                     
    


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




















SunOS 5.11          Last change: 12 Dec 2003                    3