lib/libc/gen/pthread_atfork.3

   1 .\"     $NetBSD: pthread_atfork.3,v 1.7 2014/07/19 14:58:50 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2003 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Nathan J. Williams.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd July 18, 2014
  31 .Dt PTHREAD_ATFORK 3
  32 .Os
  33 .Sh NAME
  34 .Nm pthread_atfork
  35 .Nd register handlers to be called when process forks
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In pthread.h
  40 .Ft int
  41 .Fn pthread_atfork "void (*prepare)(void)" "void (*parent)(void)" "void (*child)(void)"
  42 .Sh DESCRIPTION
  43 The
  44 .Fn pthread_atfork
  45 function registers the provided handler functions to be called when the
  46 .Xr fork 2
  47 function is called.
  48 Each of the three handlers is called at a different place in the
  49 .Xr fork 2
  50 sequence.
  51 The
  52 .Ar prepare
  53 handler is called in the parent process before the fork happens, the
  54 .Ar parent
  55 handler is called in the parent process after the fork has happened, and the
  56 .Ar child
  57 handler is called in the child process after the fork has happened.
  58 The
  59 .Ar parent
  60 and
  61 .Ar child
  62 handlers are called in the order in which they were registered, while the
  63 .Ar prepare
  64 handlers are called in reverse of the order in which they were registered.
  65 .Pp
  66 Any of the handlers given may be
  67 .Dv NULL .
  68 .Pp
  69 The intended use of
  70 .Fn pthread_atfork
  71 is to provide a consistent state to a child process from a multithreaded parent
  72 process where locks may be acquired and released asynchronously with respect to the
  73 .Xr fork 2
  74 call.
  75 Each subsystem with locks that are used in a child process should register
  76 handlers with
  77 .Fn pthread_atfork
  78 that acquires those locks in the
  79 .Ar prepare
  80 handler and releases them in the
  81 .Ar parent
  82 handler.
  83 .Sh RETURN VALUES
  84 The
  85 .Fn pthread_atfork
  86 function returns 0 on success and an error number on failure.
  87 .Sh ERRORS
  88 The following error code may be returned:
  89 .Bl -tag -width Er
  90 .It Bq Er ENOMEM
  91 Insufficient memory exists to register the fork handlers.
  92 .El
  93 .Sh SEE ALSO
  94 .Xr fork 2 ,
  95 .Xr pthread_mutex 3 ,
  96 .Xr signal 7
  97 .Sh STANDARDS
  98 The
  99 .Fn pthread_atfork
 100 function conforms to
 101 .St -p1003.1c-95 .
 102 .Sh HISTORY
 103 The
 104 .Fn pthread_atfork
 105 function first appeared in
 106 .Nx 2.0 .
 107 .Sh CAVEATS
 108 After calling
 109 .Xr fork 2
 110 from a multithreaded process, it is only safe to call
 111 async-signal-safe functions until calling one of the
 112 .Xr exec 3
 113 functions.
 114 The
 115 .Fn pthread_*
 116 functions are not async-signal-safe, so it is not safe to use such functions
 117 in the
 118 .Ar child
 119 handler.
 120 POSIX does not mandate that
 121 .Fn pthread_mutex_unlock
 122 be async-signal-safe, but it is in
 123 .Nx
 124 and thus safe to use within the
 125 .Ar child
 126 handler.
 127 .Sh BUGS
 128 There is no way to unregister a handler registered with
 129 .Fn pthread_atfork .