Re: [PATCH] proc.5: document /proc/[pid]/task/[tid]/children

[Jann Horn <jann-XZ1E9jl8jIdeoWH0uzbU5w@public.gmane.org>]

[-- Attachment #1: Type: text/plain, Size: 3459 bytes --]

On Thu, Aug 04, 2016 at 08:46:03AM +1000, Michael Kerrisk (man-pages) wrote:
> [Adding a few people to CC, who may also be interested]
> 
> Hi Jann,
> 
> On 08/02/2016 10:25 AM, Jann Horn wrote:
> >Document the /proc/[pid]/task/[tid]/children interface from CRIU, and more
> >importantly, document why it's usually not a good interface.
> >---
> > man5/proc.5 | 23 +++++++++++++++++++++--
> > 1 file changed, 21 insertions(+), 2 deletions(-)
> >
> >diff --git a/man5/proc.5 b/man5/proc.5
> >index 0970c72..ddb14cc 100644
> >--- a/man5/proc.5
> >+++ b/man5/proc.5
> >@@ -2325,14 +2325,33 @@ the corresponding files under
> > .I task/[tid]
> > may have different values (e.g., various fields in each of the
> > .I task/[tid]/status
> >-files may be different for each thread).
> >-
> >+files may be different for each thread),
> >+.\" in particular: "children" :/
> >+or they might not exist in
> >+.I /proc/[pid]
> >+at all.
> > .\" The following was still true as at kernel 2.6.13
> > In a multithreaded process, the contents of the
> > .I /proc/[pid]/task
> > directory are not available if the main thread has already terminated
> > (typically by calling
> > .BR pthread_exit (3)).
> >+
> >+.TP
> >+.IR /proc/[pid]/task/[tid]/children " (since Linux 3.5)"
> >+.\" commit 818411616baf46ceba0cff6f05af3a9b294734f7
> >+A space-separated list of child tasks of this task.
> >+Each child task is represented by its TID.
> >+
> >+.\" see comments in get_children_pid() in fs/proc/array.c
> >+This does not work properly if children of the target task exit while
> >+the file is being read!
> >+Exiting children may cause non-exiting children to be omitted from
> >+the list.
> >+This makes this interface even more unreliable than classic PID-based
> >+approaches if the inspected task and its children aren't frozen, and
> >+most code should probably not use this interface.
> >+
> > .TP
> > .IR /proc/[pid]/timers " (since Linux 3.10)"
> > .\" commit 5ed67f05f66c41e39880a6d61358438a25f9fee5
> 
> Thanks for this! I tweaked your text somewhat, and added some
> details about kernel configuration options, so that now the text
> reads:
> 
>        /proc/[pid]/task/[tid]/children (since Linux 3.5)
>               A  space-separated  list  of child tasks of this task.
>               Each child task is represented by its TID.
> 
>               This option is intended for  use  by  the  checkpoint-
>               restore (CRIU) system, and reliably provides a list of
>               children only  if  all  of  the  child  processes  are
>               stopped or frozen.  It does not work properly if chil‐
>               dren of the target task exit while the file  is  being
>               read!  Exiting children may cause non-exiting children
>               to be omitted from the list.  This makes  this  inter‐
>               face  even  more  unreliable  than  classic  PID-based
>               approaches if the  inspected  task  and  its  children
>               aren't  frozen,  and most code should probably not use
>               this interface.
> 
>               Until Linux 4.2, the presence of this  file  was  gov‐
>               erned by the CONFIG_CHECKPOINT_RESTORE kernel configu‐
>               ration option.  Since Linux 4.2, it it is governed  by
>               the CONFIG_PROC_CHILDREN option.
> 
> Look okay?

Looks good to me.

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]