man-pages-3.37 is released

man-pages-3.37 is released

[Michael Kerrisk (man-pages)]

Gidday,

I've released man-pages-3.37.tar.gz - man pages for Linux.

Now that I've sorted out kernel.org access, many of the release
artifacts are in the traditional locations, but there are a few
changes that are likely permanent as well. Details below.

Tarball download:
   http://www.kernel.org/pub/linux/docs/man-pages/
Git repository:
   http://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
Online changelog:
   http://man7.org/linux/man-pages/changelog.html#release_3.37

A short summary of the release is blogged at:
http://linux-man-pages.blogspot.com/2012/03/man-pages-337-is-released.html

The current version of the pages is browsable at:
http://man7.org/linux/man-pages/

A few changes in this release that may be of interest to readers of
this list are given below.

Cheers,

Michael

==================== Changes in man-pages-3.37 ====================

New and rewritten pages
-----------------------

getent.1
    Mark R. Bannister
        New page to document 'getent' binary provided by glibc


Changes to individual pages
---------------------------

bdflush.2
    Michael Kerrisk
        Note that bdflush() is deprecated, and does nothing

nfsservctl.2
    Michael Kerrisk
        Note that this system call was removed in Linux 3.1

ptrace.2
    Denys Vlasenko  [Oleg Nesterov, Tejun Heo]
        add extended description of various ptrace quirks
            Changes include:

            s/parent/tracer/g, s/child/tracee/g - ptrace interface now
            is sufficiently cleaned up to not treat tracing process
            as parent.

            Deleted several outright false statements:
            - pid 1 can be traced
            - tracer is not shown as parent in ps output
            - PTRACE_ATTACH is not "the same behavior as if tracee had done
              a PTRACE_TRACEME": PTRACE_ATTACH delivers a SIGSTOP.
            - SIGSTOP _can_ be injected.
            - Removed mentions of SunOS and Solaris as irrelevant.
            - Added a few more known bugs.

            Added a large block of text in DESCRIPTION which doesn't focus
            on mechanical description of each flag and operation, but rather
            tries to describe a bigger picture. The targeted audience is
            a person which is reasonably knowledgeable in Unix but did not
            spend years working with ptrace, and thus may be unaware of its
            quirks. This text went through several iterations of review by
            Oleg Nesterov and Tejun Heo.
            This block of text intentionally uses as little markup as possible,
            otherwise future modifications to it will be very hard to make.
    Michael Kerrisk
        Global clean-up of page
            * Wording and formatting fixes to existing text and
              Denys Vlasenko's new text.
            * Various technical amendments and improvements to
              Denys Vlasenko's new text.
            * Added FIXME for various problems with the current text.
    Michael Kerrisk
        Integrated changes after further review from Denys Vlasenko

syscalls.2
    Michael Kerrisk
        Note that nfsservctl(2) was removed in Linux 3.1
        Note that bdflush(2) is deprecated

capabilities.7
    Michael Kerrisk
        Add CAP_WAKE_ALARM
    Michael Kerrisk
        Add various operations under CAP_SYS_ADMIN
        Add perf_event_open(2) to CAP_SYS_ADMIN
        Add VM86_REQUEST_IRQ vm86(2) command to CAP_SYS_ADMIN
        Update CAP_NET_ADMIN with notes from include/linux/capability.h
        Add nfsservctl(2) to CAP_SYS_ADMIN
    Michael Kerrisk
        Add ioctl(FIBMAP) under CAP_SYS_RAWIO
    Michael Kerrisk
        Add virtual terminal ioctl()s under CAP_SYS_TTY_CONFIG
    Michael Kerrisk
        Update CAP_NET_RAW with notes from include/linux/capability.h
    Michael Kerrisk
        Add F_SETPIPE_SZ case to CAP_SYS_RESOURCE
        Add POSIX messages queues queues_max case to CAP_SYS_RESOURCE
        Update CAP_SYS_RESOURCE with notes from include/linux/capability.h
    Michael Kerrisk
        SEE ALSO: Add libcap(3)

ld.so.8
    Michael Kerrisk
        Add --audit command-line option


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/

Re: man-pages-3.37 is released

[Denys Vlasenko]

On Friday 09 March 2012 18:27, Michael Kerrisk (man-pages) wrote:
> ptrace.2
>     Denys Vlasenko  [Oleg Nesterov, Tejun Heo]
>         add extended description of various ptrace quirks

Pulled current git and spotted a few broken places.

       The  following  kinds  of  ptrace-stops  exist:  signal-delivery-stops,
       group-stop,  PTRACE_EVENT   stops,   syscall-stops   PTRACE_SINGLESTEP,
       PTRACE_SYSEMU,  and  They  all  are  reported  by  waitpid(2) with WIF-
       STOPPED(status) true.

The text is broken after "syscall-stops" word. Corresponding source is:

group-stop, PTRACE_EVENT stops, syscall-stops
.BR PTRACE_SINGLESTEP ,
.BR PTRACE_SYSEMU ,
and
.BE PTRACE_SYSEMU_SINGLESTEP .



       Signal-delivery-stop  is observed by the tracer as waitpid(2) returning
       with WIFSTOPPED(status) true, with  the  stopping  signal  returned  by
       WSTOPSIG(status).   If  the  stopping  signal is SIGTRAP, this may be a
       different kind of ptrace-stop; ...

The two instances of word "stopping" above are wrong and need to be deleted:
ANY signal is reported this way, not only four signals which stop processes.
This is an especially bad disinformation because in the sentences below
we again use word "stopping":

       ... see  the  "Syscall-stops"  and  "execve"
       sections  below  for  details.   If WSTOPSIG(status) returns a stopping
       signal, this may be a group-stop; see below.

but here, we do mean "stopping" = "SIGSTOP/TSTP/TTIN/TTOU".



       Note  that  a  suppressed  signal  still  causes system calls to return
       prematurely.  Restartable system calls will be  restarted  (the  tracer
       will  observe  the  tracee  to execute restart_syscall(2) if the tracer
       uses PTRACE_SYSCALL); non-restartable system calls may fail with  EINTR
       even though no observable signal is injected to the tracee.

I learned more about this mechanism and the above text is wrong.
A better text would be:

       Note that a suppressed signal still causes system calls to return  pre-
       maturely.  In this case system calls will be restarted: the tracer will
       observe  the  tracee  to  re-execute  interrupted   system   call   (or
       restart_syscall(2) system call for a few syscalls which use a different
       mechanism for restarting) if the tracer uses PTRACE_SYSCALL.  Even sys-
       tem  calls (such as poll(2)) which are not restartable after signal are
       restarted after signal is suppressed; however, kernel bugs exist  which
       cause some syscalls to fail with EINTR even though no observable signal
       is injected to the tracee.



       *  All  other  threads  stop  in   PTRACE_EVENT_EXIT   stop,   if   the
          PTRACE_O_TRACEEXIT  option  was  turned  on.  Then all other threads
          except the thread group leader report death as if  they  exited  via
          _exit(2) with exit code 0.

       *  Then  a  PTRACE_EVENT_EXEC  stop  happens, if the PTRACE_O_TRACEEXEC
          option was turned on.

       *  The execing tracee  changes  its  thread  ID  while  it  is  in  the
          execve(2).   (Remember,  under ptrace, the "pid" returned from wait-
          pid(2), or fed into ptrace calls, is the tracee's thread ID.)   That
          is,  the  tracee's  thread ID is reset to be the same as its process
          ID, which is the same as the thread group leader's thread ID.

Above, bullet points 2 and 3 need to be swapped: thread ID change happens
before PTRACE_EVENT_EXEC.


       *  If the thread group leader has reported its death by this  time,  it
          appears  to  the  tracer that the dead thread leader "reappears from
          nowhere".

Thread group leader does not report its death until there is
at least one other live thread.



       The PTRACE_O_TRACEEXEC option is the recommended tool for dealing  with
       this situation.  It enables PTRACE_EVENT_EXEC stop, which occurs before
       execve(2) returns.  First,  it  enables  PTRACE_EVENT_EXEC-stop,  which
       occurs  before  execve(2)  returns.

Duplicate sentence.

       Currently, there is no way to retrieve the  former  thread  ID  of  the
       execing  tracee.   If  the  tracer  doesn't  keep track of its tracees'
       thread group relations, it may be unable to know  which  tracee  execed
       and  therefore no longer exists under the old thread ID due to a thread
       ID change.

Two paragraphs above, we just said "In  this  stop,  the   tracer   can   use
       PTRACE_GETEVENTMSG  to  retrieve  the tracee's former thread ID.  (This
       feature was introduced in Linux 3.0)."
So it is no longer true.



Also, I propose the following additon to BUGS:

       Some syscalls return with EINTR if a signal was sent to a  tracee,  but
       delivery was suppressed by the tracer. (This is very typical operation:
       it is usually done by debuggers on every attach, in order to not intro-
       duce  a  bogus  SIGSTOP).   As of Linux-3.2, the following syscalls are
       affected: epoll_wait(2), read(2) from inotify file descriptor. The list
       is likely incomplete.


The patch against current git is below.
-- 
vda



diff --git a/man2/ptrace.2 b/man2/ptrace.2
index 37c4dff..7f3c219 100644
--- a/man2/ptrace.2
+++ b/man2/ptrace.2
@@ -722,11 +722,7 @@ Example:
 .\"     describe how wait notifications queue (or not queue)
 .LP
 The following kinds of ptrace-stops exist: signal-delivery-stops,
-group-stop, PTRACE_EVENT stops, syscall-stops
-.BR PTRACE_SINGLESTEP ,
-.BR PTRACE_SYSEMU ,
-and
-.BE PTRACE_SYSEMU_SINGLESTEP .
+group-stop, PTRACE_EVENT stops, syscall-stops.
 They all are reported by
 .BR waitpid (2)
 with
@@ -766,9 +762,9 @@ Signal-delivery-stop is observed by the tracer as
 .BR waitpid (2)
 returning with
 .I WIFSTOPPED(status)
-true, with the stopping signal returned by
+true, with the signal returned by
 .IR WSTOPSIG(status) .
-If the stopping signal is
+If the signal is
 .BR SIGTRAP ,
 this may be a different kind of ptrace-stop;
 see the "Syscall-stops" and "execve" sections below for details.
@@ -802,12 +798,17 @@ value: the tracer can cause a different signal to be injected.
 .LP
 Note that a suppressed signal still causes system calls to return
 prematurely.
-Restartable system calls will be restarted (the tracer will
-observe the tracee to execute
+In this case system calls will be restarted: the tracer will
+observe the tracee to re-execute interrupted system call (or
 .BR restart_syscall(2)
-if the tracer uses
-.BR PTRACE_SYSCALL );
-non-restartable system calls may fail with
+system call for a few syscalls which use a different mechanism
+for restarting) if the tracer uses
+.BR PTRACE_SYSCALL .
+Even system calls (such as
+.BR poll(2) )
+which are not restartable after signal are restarted after
+signal is suppressed; however, kernel bugs exist which cause
+some syscalls to fail with
 .B EINTR
 even though no observable signal is injected to the tracee.
 .LP
@@ -1406,12 +1407,6 @@ death as if they exited via
 .BR _exit (2)
 with exit code 0.
 .IP *
-Then a
-.B PTRACE_EVENT_EXEC
-stop happens, if the
-.BR PTRACE_O_TRACEEXEC
-option was turned on.
-.IP *
 The execing tracee changes its thread ID while it is in the
 .BR execve (2).
 (Remember, under ptrace, the "pid" returned from
@@ -1420,9 +1415,22 @@ or fed into ptrace calls, is the tracee's thread ID.)
 That is, the tracee's thread ID is reset to be the same as its process ID,
 which is the same as the thread group leader's thread ID.
 .IP *
-If the thread group leader has reported its death by this time,
+Then a
+.B PTRACE_EVENT_EXEC
+stop happens, if the
+.BR PTRACE_O_TRACEEXEC
+option was turned on.
+.IP *
+If the thread group leader has reported its
+.B PTRACE_EVENT_EXIT
+stop by this time,
 it appears to the tracer that
 the dead thread leader "reappears from nowhere".
+(Note: thread group leader does not report death via
+.I WIFEXITED(status)
+until there is at least one other live thread.
+This eliminates possibility that tracer will see
+it dying and then reappearing.)
 If the thread group leader was still alive,
 for the tracer this may look as if thread group leader
 returns from a different system call than it entered,
@@ -1440,11 +1448,6 @@ the thread ID change in the tracee.
 The
 .B PTRACE_O_TRACEEXEC
 option is the recommended tool for dealing with this situation.
-It enables
-.B PTRACE_EVENT_EXEC
-stop, which occurs before
-.BR execve (2)
-returns.
 First, it enables
 .BR PTRACE_EVENT_EXEC -stop,
 which occurs before
@@ -1475,13 +1478,7 @@ data structures describing the threads of this process,
 and retain only one data structure\(emone which
 describes the single still running tracee, with
 
-    thread ID == thread group ID == process id.
-.LP
-Currently, there is no way to retrieve the former
-thread ID of the execing tracee.
-If the tracer doesn't keep track of its tracees' thread group relations,
-it may be unable to know which tracee execed and therefore no longer
-exists under the old thread ID due to a thread ID change.
+    thread ID == thread group ID == process ID.
 .LP
 Example: two threads call
 .BR execve (2)
@@ -1499,10 +1496,6 @@ PID2 execve("/bin/bar", "bar" <unfinished ...>
 PID0 <... execve resumed> )             = 0
 .fi
 .LP
-In this situation, there is no way to know which
-.BR execve (2)
-succeeded.
-.LP
 If the
 .B PTRACE_O_TRACEEXEC
 option is
@@ -1713,6 +1706,17 @@ This may be changed in the future;
 .B SIGKILL
 is meant to always immediately kill tasks even under ptrace.
 Last confirmed on 2.6.38.6.
+.LP
+Some syscalls return with
+.B EINTR
+if a signal was sent to a tracee, but delivery was suppressed
+by the tracer. (This is very typical operation: it is usually
+done by debuggers on every attach, in order to not introduce
+a bogus SIGSTOP).
+As of linux 3.2.9, the following syscalls are affected:
+.BR epoll_wait (2),
+.BR read (2)
+from inotify file descriptor. The list is likely incomplete.
 .SH "SEE ALSO"
 .BR gdb (1),
 .BR strace (1),

Re: man-pages-3.37 is released

[Michael Kerrisk (man-pages)]

Hello Denys,

On Sat, Mar 17, 2012 at 1:16 PM, Denys Vlasenko
<vda.linux@googlemail.com> wrote:
> On Friday 09 March 2012 18:27, Michael Kerrisk (man-pages) wrote:
>> ptrace.2
>>     Denys Vlasenko  [Oleg Nesterov, Tejun Heo]
>>         add extended description of various ptrace quirks
>
> Pulled current git and spotted a few broken places.

I made a few light edits to your patch, but basically applied it as
given for man-pages-3.38.

Thanks for checking the page over one more time!

Cheers,

Michael



>       The  following  kinds  of  ptrace-stops  exist:  signal-delivery-stops,
>       group-stop,  PTRACE_EVENT   stops,   syscall-stops   PTRACE_SINGLESTEP,
>       PTRACE_SYSEMU,  and  They  all  are  reported  by  waitpid(2) with WIF-
>       STOPPED(status) true.
>
> The text is broken after "syscall-stops" word. Corresponding source is:
>
> group-stop, PTRACE_EVENT stops, syscall-stops
> .BR PTRACE_SINGLESTEP ,
> .BR PTRACE_SYSEMU ,
> and
> .BE PTRACE_SYSEMU_SINGLESTEP .
>
>
>
>       Signal-delivery-stop  is observed by the tracer as waitpid(2) returning
>       with WIFSTOPPED(status) true, with  the  stopping  signal  returned  by
>       WSTOPSIG(status).   If  the  stopping  signal is SIGTRAP, this may be a
>       different kind of ptrace-stop; ...
>
> The two instances of word "stopping" above are wrong and need to be deleted:
> ANY signal is reported this way, not only four signals which stop processes.
> This is an especially bad disinformation because in the sentences below
> we again use word "stopping":
>
>       ... see  the  "Syscall-stops"  and  "execve"
>       sections  below  for  details.   If WSTOPSIG(status) returns a stopping
>       signal, this may be a group-stop; see below.
>
> but here, we do mean "stopping" = "SIGSTOP/TSTP/TTIN/TTOU".
>
>
>
>       Note  that  a  suppressed  signal  still  causes system calls to return
>       prematurely.  Restartable system calls will be  restarted  (the  tracer
>       will  observe  the  tracee  to execute restart_syscall(2) if the tracer
>       uses PTRACE_SYSCALL); non-restartable system calls may fail with  EINTR
>       even though no observable signal is injected to the tracee.
>
> I learned more about this mechanism and the above text is wrong.
> A better text would be:
>
>       Note that a suppressed signal still causes system calls to return  pre-
>       maturely.  In this case system calls will be restarted: the tracer will
>       observe  the  tracee  to  re-execute  interrupted   system   call   (or
>       restart_syscall(2) system call for a few syscalls which use a different
>       mechanism for restarting) if the tracer uses PTRACE_SYSCALL.  Even sys-
>       tem  calls (such as poll(2)) which are not restartable after signal are
>       restarted after signal is suppressed; however, kernel bugs exist  which
>       cause some syscalls to fail with EINTR even though no observable signal
>       is injected to the tracee.
>
>
>
>       *  All  other  threads  stop  in   PTRACE_EVENT_EXIT   stop,   if   the
>          PTRACE_O_TRACEEXIT  option  was  turned  on.  Then all other threads
>          except the thread group leader report death as if  they  exited  via
>          _exit(2) with exit code 0.
>
>       *  Then  a  PTRACE_EVENT_EXEC  stop  happens, if the PTRACE_O_TRACEEXEC
>          option was turned on.
>
>       *  The execing tracee  changes  its  thread  ID  while  it  is  in  the
>          execve(2).   (Remember,  under ptrace, the "pid" returned from wait-
>          pid(2), or fed into ptrace calls, is the tracee's thread ID.)   That
>          is,  the  tracee's  thread ID is reset to be the same as its process
>          ID, which is the same as the thread group leader's thread ID.
>
> Above, bullet points 2 and 3 need to be swapped: thread ID change happens
> before PTRACE_EVENT_EXEC.
>
>
>       *  If the thread group leader has reported its death by this  time,  it
>          appears  to  the  tracer that the dead thread leader "reappears from
>          nowhere".
>
> Thread group leader does not report its death until there is
> at least one other live thread.
>
>
>
>       The PTRACE_O_TRACEEXEC option is the recommended tool for dealing  with
>       this situation.  It enables PTRACE_EVENT_EXEC stop, which occurs before
>       execve(2) returns.  First,  it  enables  PTRACE_EVENT_EXEC-stop,  which
>       occurs  before  execve(2)  returns.
>
> Duplicate sentence.
>
>       Currently, there is no way to retrieve the  former  thread  ID  of  the
>       execing  tracee.   If  the  tracer  doesn't  keep track of its tracees'
>       thread group relations, it may be unable to know  which  tracee  execed
>       and  therefore no longer exists under the old thread ID due to a thread
>       ID change.
>
> Two paragraphs above, we just said "In  this  stop,  the   tracer   can   use
>       PTRACE_GETEVENTMSG  to  retrieve  the tracee's former thread ID.  (This
>       feature was introduced in Linux 3.0)."
> So it is no longer true.
>
>
>
> Also, I propose the following additon to BUGS:
>
>       Some syscalls return with EINTR if a signal was sent to a  tracee,  but
>       delivery was suppressed by the tracer. (This is very typical operation:
>       it is usually done by debuggers on every attach, in order to not intro-
>       duce  a  bogus  SIGSTOP).   As of Linux-3.2, the following syscalls are
>       affected: epoll_wait(2), read(2) from inotify file descriptor. The list
>       is likely incomplete.
>
>
> The patch against current git is below.
> --
> vda
>
>
>
> diff --git a/man2/ptrace.2 b/man2/ptrace.2
> index 37c4dff..7f3c219 100644
> --- a/man2/ptrace.2
> +++ b/man2/ptrace.2
> @@ -722,11 +722,7 @@ Example:
>  .\"     describe how wait notifications queue (or not queue)
>  .LP
>  The following kinds of ptrace-stops exist: signal-delivery-stops,
> -group-stop, PTRACE_EVENT stops, syscall-stops
> -.BR PTRACE_SINGLESTEP ,
> -.BR PTRACE_SYSEMU ,
> -and
> -.BE PTRACE_SYSEMU_SINGLESTEP .
> +group-stop, PTRACE_EVENT stops, syscall-stops.
>  They all are reported by
>  .BR waitpid (2)
>  with
> @@ -766,9 +762,9 @@ Signal-delivery-stop is observed by the tracer as
>  .BR waitpid (2)
>  returning with
>  .I WIFSTOPPED(status)
> -true, with the stopping signal returned by
> +true, with the signal returned by
>  .IR WSTOPSIG(status) .
> -If the stopping signal is
> +If the signal is
>  .BR SIGTRAP ,
>  this may be a different kind of ptrace-stop;
>  see the "Syscall-stops" and "execve" sections below for details.
> @@ -802,12 +798,17 @@ value: the tracer can cause a different signal to be injected.
>  .LP
>  Note that a suppressed signal still causes system calls to return
>  prematurely.
> -Restartable system calls will be restarted (the tracer will
> -observe the tracee to execute
> +In this case system calls will be restarted: the tracer will
> +observe the tracee to re-execute interrupted system call (or
>  .BR restart_syscall(2)
> -if the tracer uses
> -.BR PTRACE_SYSCALL );
> -non-restartable system calls may fail with
> +system call for a few syscalls which use a different mechanism
> +for restarting) if the tracer uses
> +.BR PTRACE_SYSCALL .
> +Even system calls (such as
> +.BR poll(2) )
> +which are not restartable after signal are restarted after
> +signal is suppressed; however, kernel bugs exist which cause
> +some syscalls to fail with
>  .B EINTR
>  even though no observable signal is injected to the tracee.
>  .LP
> @@ -1406,12 +1407,6 @@ death as if they exited via
>  .BR _exit (2)
>  with exit code 0.
>  .IP *
> -Then a
> -.B PTRACE_EVENT_EXEC
> -stop happens, if the
> -.BR PTRACE_O_TRACEEXEC
> -option was turned on.
> -.IP *
>  The execing tracee changes its thread ID while it is in the
>  .BR execve (2).
>  (Remember, under ptrace, the "pid" returned from
> @@ -1420,9 +1415,22 @@ or fed into ptrace calls, is the tracee's thread ID.)
>  That is, the tracee's thread ID is reset to be the same as its process ID,
>  which is the same as the thread group leader's thread ID.
>  .IP *
> -If the thread group leader has reported its death by this time,
> +Then a
> +.B PTRACE_EVENT_EXEC
> +stop happens, if the
> +.BR PTRACE_O_TRACEEXEC
> +option was turned on.
> +.IP *
> +If the thread group leader has reported its
> +.B PTRACE_EVENT_EXIT
> +stop by this time,
>  it appears to the tracer that
>  the dead thread leader "reappears from nowhere".
> +(Note: thread group leader does not report death via
> +.I WIFEXITED(status)
> +until there is at least one other live thread.
> +This eliminates possibility that tracer will see
> +it dying and then reappearing.)
>  If the thread group leader was still alive,
>  for the tracer this may look as if thread group leader
>  returns from a different system call than it entered,
> @@ -1440,11 +1448,6 @@ the thread ID change in the tracee.
>  The
>  .B PTRACE_O_TRACEEXEC
>  option is the recommended tool for dealing with this situation.
> -It enables
> -.B PTRACE_EVENT_EXEC
> -stop, which occurs before
> -.BR execve (2)
> -returns.
>  First, it enables
>  .BR PTRACE_EVENT_EXEC -stop,
>  which occurs before
> @@ -1475,13 +1478,7 @@ data structures describing the threads of this process,
>  and retain only one data structure\(emone which
>  describes the single still running tracee, with
>
> -    thread ID == thread group ID == process id.
> -.LP
> -Currently, there is no way to retrieve the former
> -thread ID of the execing tracee.
> -If the tracer doesn't keep track of its tracees' thread group relations,
> -it may be unable to know which tracee execed and therefore no longer
> -exists under the old thread ID due to a thread ID change.
> +    thread ID == thread group ID == process ID.
>  .LP
>  Example: two threads call
>  .BR execve (2)
> @@ -1499,10 +1496,6 @@ PID2 execve("/bin/bar", "bar" <unfinished ...>
>  PID0 <... execve resumed> )             = 0
>  .fi
>  .LP
> -In this situation, there is no way to know which
> -.BR execve (2)
> -succeeded.
> -.LP
>  If the
>  .B PTRACE_O_TRACEEXEC
>  option is
> @@ -1713,6 +1706,17 @@ This may be changed in the future;
>  .B SIGKILL
>  is meant to always immediately kill tasks even under ptrace.
>  Last confirmed on 2.6.38.6.
> +.LP
> +Some syscalls return with
> +.B EINTR
> +if a signal was sent to a tracee, but delivery was suppressed
> +by the tracer. (This is very typical operation: it is usually
> +done by debuggers on every attach, in order to not introduce
> +a bogus SIGSTOP).
> +As of linux 3.2.9, the following syscalls are affected:
> +.BR epoll_wait (2),
> +.BR read (2)
> +from inotify file descriptor. The list is likely incomplete.
>  .SH "SEE ALSO"
>  .BR gdb (1),
>  .BR strace (1),



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/

Re: man-pages-3.37 is released

[Denys Vlasenko]

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

Hi Michael,

On Mon, Mar 19, 2012 at 7:29 PM, Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
> On Sat, Mar 17, 2012 at 1:16 PM, Denys Vlasenko
> <vda.linux@googlemail.com> wrote:
>> On Friday 09 March 2012 18:27, Michael Kerrisk (man-pages) wrote:
>>> ptrace.2
>>>     Denys Vlasenko  [Oleg Nesterov, Tejun Heo]
>>>         add extended description of various ptrace quirks
>>
>> Pulled current git and spotted a few broken places.
>
> I made a few light edits to your patch, but basically applied it as
> given for man-pages-3.38.

Thanks! I found one tiny markup bug.

Also, I want to add info about PTRACE_GETEVENTMSG on
PTRACE_EVENT_EXEC. We document PTRACE_GETEVENTMSG
on all other PTRACE_EVENT_foo's, except EXEC.
That's not fair :)

Please find the patch attached.

-- 
vda

[-- Attachment #2: ptrace.2.diff --]
[-- Type: text/x-patch, Size: 928 bytes --]

diff --git a/man2/ptrace.2 b/man2/ptrace.2
index 5a8b648..0e7ca08 100644
--- a/man2/ptrace.2
+++ b/man2/ptrace.2
@@ -374,6 +374,10 @@ value such that
   status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8))
 .fi
 
+If execing thread is not a thread group leader, thread ID
+is reset to thread group leader's ID before this stop.
+Since Linux 3.0, the former thread ID can be retrieved with
+.BR PTRACE_GETEVENTMSG .
 .TP
 .BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)"
 Stop the tracee at the completion of the next
@@ -1018,6 +1022,9 @@ can be used to retrieve the new thread's ID.
 .B PTRACE_EVENT_EXEC
 Stop before return from
 .BR execve (2).
+Since Linux 3.0,
+.BR PTRACE_GETEVENTMSG
+returns the former thread ID.
 .TP
 .B PTRACE_EVENT_EXIT
 Stop before exit (including death from
@@ -1039,7 +1046,8 @@ to finish exiting.
 on
 .B PTRACE_EVENT
 stops returns
-.B SIGTRAP in
+.B SIGTRAP
+in
 .IR si_signo ,
 with
 .I si_code

Re: man-pages-3.37 is released

[Michael Kerrisk (man-pages)]

On Sat, Mar 24, 2012 at 1:51 AM, Denys Vlasenko
<vda.linux@googlemail.com> wrote:
> Hi Michael,
>
> On Mon, Mar 19, 2012 at 7:29 PM, Michael Kerrisk (man-pages)
> <mtk.manpages@gmail.com> wrote:
>> On Sat, Mar 17, 2012 at 1:16 PM, Denys Vlasenko
>> <vda.linux@googlemail.com> wrote:
>>> On Friday 09 March 2012 18:27, Michael Kerrisk (man-pages) wrote:
>>>> ptrace.2
>>>>     Denys Vlasenko  [Oleg Nesterov, Tejun Heo]
>>>>         add extended description of various ptrace quirks
>>>
>>> Pulled current git and spotted a few broken places.
>>
>> I made a few light edits to your patch, but basically applied it as
>> given for man-pages-3.38.
>
> Thanks! I found one tiny markup bug.
>
> Also, I want to add info about PTRACE_GETEVENTMSG on
> PTRACE_EVENT_EXEC. We document PTRACE_GETEVENTMSG
> on all other PTRACE_EVENT_foo's, except EXEC.
> That's not fair :)
>
> Please find the patch attached.

Thanks Denys. Applied for 3.38. ptrace.2 keeps getting better and better!

I appreciate that you like send the patch as an attachment so it
arrives intact, but it'd be helpful for review if you *also* posted a
copy inline.

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/