From 9338d37b764ac17e575c22d5f057b04afebaa7b6 Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Thu, 13 Jul 2017 07:05:28 +0200
Subject: [PATCH] getpid.2: More tidy-ups in discussion of removal of getpid()
 PID caching

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 man2/getpid.2 | 30 +++++++++++++++++-------------
 1 file changed, 17 insertions(+), 13 deletions(-)

diff --git a/man2/getpid.2 b/man2/getpid.2
index 0aced3bae..b9bb1d230 100644
--- a/man2/getpid.2
+++ b/man2/getpid.2
@@ -61,25 +61,25 @@ If the caller's parent is in a different PID namespace (see
 returns 0.
 .\"
 .SS C library/kernel differences
-Since glibc version 2.3.4,
+From glibc version 2.3.4 up to and including version 2.24,
 the glibc wrapper function for
 .BR getpid ()
-caches PIDs,
-so as to avoid additional system calls when a process calls
+cached PIDs,
+with the goal of avoiding additional system calls when a process calls
 .BR getpid ()
 repeatedly.
-Normally this caching is invisible,
-but its correct operation relies on support in the wrapper functions for
+Normally this caching was invisible,
+but its correct operation relied on support in the wrapper functions for
 .BR fork (2),
 .BR vfork (2),
 and
 .BR clone (2):
-if an application bypasses the glibc wrappers for these system calls by using
+if an application bypassed the glibc wrappers for these system calls by using
 .BR syscall (2),
 then a call to
 .BR getpid ()
-in the child will return the wrong value
-(to be precise: it will return the PID of the parent process).
+in the child would return the wrong value
+(to be precise: it would return the PID of the parent process).
 .\" The following program demonstrates this "feature":
 .\"
 .\" #define _GNU_SOURCE
@@ -105,16 +105,20 @@ in the child will return the wrong value
 .\"    }
 .\"    wait(NULL);
 .\"}
-See also
-.BR clone (2)
-for discussion of a case where
+In addition, there were cases where
 .BR getpid ()
-may return the wrong value even when invoking
+could return the wrong value even when invoking
 .BR clone (2)
 via the glibc wrapper function.
+(For a discussion of one such case, see BUGS in
+.BR clone (2).)
+Furthermore, the complexity of the caching code had been
+the source of a few bugs within glibc over the years.
 .PP
-Since glibc version 2.25, the PID cache is removed:
+Because of the aforementioned problems,
+since glibc version 2.25, the PID cache is removed:
 .\" commit c579f48edba88380635ab98cb612030e3ed8691e
+.\" https://sourceware.org/glibc/wiki/Release/2.25#pid_cache_removal
 calls to
 .BR getpid ()
 always invoke the actual system call, rather than returning a cached value.