Re: [LTP] [PATCH v2 1/2] doc: Document process_state

Petr Vorel
2025-12-16T11:27:34Z

> Signed-off-by: Cyril Hrubis <chrubis@suse.cz>
> ---
> doc/developers/api_c_tests.rst | 5 ++++
> include/tst_process_state.h | 55 +++++++++++++++++++++-------------
> 2 files changed, 40 insertions(+), 20 deletions(-)

> New in v2.

> diff --git a/doc/developers/api_c_tests.rst b/doc/developers/api_c_tests.rst
> index 2ca0f0464..13fc8651b 100644
> --- a/doc/developers/api_c_tests.rst
> +++ b/doc/developers/api_c_tests.rst
> @@ -43,6 +43,11 @@ Kernel
> .. kernel-doc:: ../../include/tst_kernel.h
> .. kernel-doc:: ../../include/tst_kvercmp.h

> +Process state
> +-------------
> +
> +.. kernel-doc:: ../../include/tst_process_state.h
> +
> NUMA
> ----
> .. kernel-doc:: ../../include/tst_numa.h
> diff --git a/include/tst_process_state.h b/include/tst_process_state.h
> index b1d83e109..3691bba7a 100644
> --- a/include/tst_process_state.h
> +++ b/include/tst_process_state.h
> @@ -15,39 +15,54 @@

> #ifdef TST_TEST_H__

> -/*
> - * Waits for process state change.
> +/**
> + * TST_PROCESS_STATE_WAIT() - Waits for a process state change.
> + *
> + * Polls `/proc/$PID/state` for a process state changes.
> *
> - * The state is one of the following:
> + * @pid: A process pid.
> + * @state: A state to wait for.
> + * @msec_timeout: A timeout for the wait.
> *
> - * R - process is running
> - * S - process is sleeping
> - * D - process sleeping uninterruptibly
> - * Z - zombie process
> - * T - process is traced
> + * Possible process states:
Maybe: use link to https://man7.org/linux/man-pages/man1/ps.1.html ?

-* Possible process states:
+* Possible process states (see :man1:`ps`):

> + *
> + * - **R** Process is running.
> + * - **S** Process is sleeping.
> + * - **D** Process sleeping uninterruptibly.
> + * - **Z** Zombie process.
> + * - **T** Process is traced.
> + * - **t** Tracing stopped.
> + * - **X** Process id dead.

Process state is outdated, man ps(1) lists:

D uninterruptible sleep (usually I/O)
I idle kernel thread
R running or runnable (on run queue)
S interruptible sleep (waiting for an
event to complete)
T stopped by job control signal
t stopped by debugger during the tracing
W paging (not valid since Linux 2.6)
X dead (should never be seen)
Z defunct (“zombie”) process, terminated
but not reaped by its parent

We miss:
* I (from kernel 4.2, maybe not relevant when we use it for a child which
is userspace)
* W (irrelevant as it is not valid)
* Z

Also, do we want specify the process states in both TST_PROCESS_STATE_WAIT() and
TST_THREAD_STATE_WAIT(), or just specify it in one and mention in the other that
they specify it? (via :ref: or c:func:).

Otherwise LGTM.
Reviewed-by: Petr Vorel <pvorel@suse.cz>

Kind regards,
Petr