docs/68201: [patch] pthread_atfork(3) man page

[Alex Vasylenko]

>Number:         68201
>Category:       docs
>Synopsis:       [patch] pthread_atfork(3) man page
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Jun 22 15:00:41 GMT 2004
>Closed-Date:
>Last-Modified:
>Originator:     Alex Vasylenko
>Release:        FreeBSD 5.2-CURRENT i386
>Organization:
>Environment:
System: FreeBSD 5.2-CURRENT #16: Sun Jun 20 09:18:35 EDT 2004


	
>Description:
	pthread_atfork(3) needs a man page, not mentioned in pthread(3)

>How-To-Repeat:
	man 3 pthread_atfork
	
	
>Fix:
	Apply the following patches in /usr/src/share/man/man3:

--- Makefile.orig	Sat Jun  5 11:49:32 2004
+++ Makefile	Tue Jun 22 10:29:40 2004
@@ -142,6 +142,7 @@
 
 .if !defined(NOLIBC_R) || !defined(NOLIBPTHREAD) || !defined(NOLIBTHR)
 PTHREAD_MAN=	pthread.3 \
+		pthread_atfork.3 \
 		pthread_attr.3 \
 		pthread_attr_get_np.3 \
 		pthread_attr_setcreatesuspend_np.3 \


--- pthread.3.orig	Thu Apr  8 19:04:54 2004
+++ pthread.3	Mon Jun 21 23:58:30 2004
@@ -30,7 +30,7 @@
 .\"
 .\" $FreeBSD: src/share/man/man3/pthread.3,v 1.26 2004/04/08 23:04:54 simon Exp $
 .\"
-.Dd January 15, 2004
+.Dd June 21, 2004
 .Dt PTHREAD 3
 .Os
 .Sh NAME
@@ -447,6 +447,15 @@
 .Ss Cleanup Routines
 .Bl -tag -width indent
 .It Xo
+.Ft int
+.Fo pthread_atfork
+.Fa "void \*[lp]*prepare\*[rp]\*[lp]void\*[rp]"
+.Fa "void \*[lp]*parent\*[rp]\*[lp]void\*[rp]"
+.Fa "void \*[lp]*child\*[rp]\*[lp]void\*[rp]"
+.Fc
+.Xc
+Register fork handlers
+.It Xo
 .Ft void
 .Fn pthread_cleanup_pop "int execute"
 .Xc
@@ -472,6 +481,7 @@
 functions and the thread functions.
 Threaded applications are linked with one of these libraries.
 .Sh SEE ALSO
+.Xr pthread_atfork 3 ,
 .Xr pthread_cleanup_pop 3 ,
 .Xr pthread_cleanup_push 3 ,
 .Xr pthread_condattr_destroy 3 ,


--- pthread_atfork.3.orig	Mon Jun 21 23:59:52 2004
+++ pthread_atfork.3	Tue Jun 22 10:48:52 2004
@@ -0,0 +1,77 @@
+.\"
+.\" $FreeBSD: src/share/man/man3/pthread_atfork.3,v 1.0 2004/06/21 15:59:00 xx Exp $
+.\"
+.Dd June 21, 2004
+.Dt PTHREAD_ATFORK 3
+.Os
+.Sh NAME
+.Nm pthread_atfork
+.Nd register fork handlers
+.Sh LIBRARY
+.Lb libpthread
+.Sh SYNOPSIS
+.In pthread.h
+.Ft int
+.Fo pthread_atfork
+.Fa "void \*[lp]*prepare\*[rp]\*[lp]void\*[rp]"
+.Fa "void \*[lp]*parent\*[rp]\*[lp]void\*[rp]"
+.Fa "void \*[lp]*child\*[rp]\*[lp]void\*[rp]"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn pthread_atfork
+function declares fork handlers to be called before and after
+.Xr fork 2 ,
+in the context of the thread that called
+.Xr fork 2 .
+The
+.Fa prepare
+fork handler will be called before
+.Xr fork 2
+processing commences.
+The
+.Fa parent
+fork handle will be called after
+.Xr fork 2
+processing completes in the parent process.
+The
+.Fa child
+fork handler will be called after
+.Xr fork 2
+processing completes in the child process.
+If no handling is desired at one or more of these three points, the
+corresponding fork handler address(es) may be set to NULL.
+.Pp
+The order of calls to 
+.Fn pthread_atfork
+is significant.
+The
+.Fa parent
+and
+.Fa child
+fork handlers will be called in the order in which they were 
+established by calls to
+.Fn pthread_atfork .
+The
+.Fa prepare
+fork handlers will be called in the opposite order.
+.Sh RETURN VALUES
+Upon successful completion,
+.Fn pthread_atfork
+returns a value of zero; otherwise, an error number is returned
+to indicate the error.
+.Sh ERRORS
+The
+.Fn pthread_atfork
+function will fail if:
+.Bl -tag -width Er
+.It Bq Er ENOMEM
+Insufficient table space exists to record the fork handler addresses.
+.Sh SEE ALSO
+.Xr fork 2 ,
+.Xr pthread 3
+.Sh STANDARDS
+The
+.Fn pthread_atfork
+function is expected to conform to
+.St -p1003.1 .
>Release-Note:
>Audit-Trail:
>Unformatted: