Skip to content

Documentation for pcntl_waitid #3518

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Sep 22, 2024
Merged

Documentation for pcntl_waitid #3518

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
0fb1db3
Added function pcntl_waitid
vrza Jul 1, 2024
d3f1466
Added pcntl constants used by waitid
vrza Jul 1, 2024
f8238e0
Documented pcntl_get_last_error and pcntl_strerror
vrza Jul 1, 2024
88ba13b
Fixed typo (parameter name)
vrza Jul 5, 2024
011c09c
Trimmed trailing whitespace
vrza Jul 7, 2024
9b9b211
Formatting
vrza Jul 7, 2024
c7fa64b
Marked up parameters
vrza Jul 8, 2024
9220236
Rewrote a sentence, avoiding second person pronoun
vrza Sep 16, 2024
effa1f4
Improved variable list markup
vrza Sep 16, 2024
d3fcf2c
Limited paragraph width to 80 characters
vrza Sep 16, 2024
5d9406d
Addressed review comments
vrza Sep 17, 2024
8d62b6c
Nit
Girgias Sep 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 126 additions & 0 deletions reference/pcntl/constants.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,36 @@
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.wexited">
<term>
<constant>WEXITED</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.wstopped">
<term>
<constant>WSTOPPED</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.wnowait">
<term>
<constant>WNOWAIT</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
</variablelist>

<variablelist xml:id="pcntl.constants.sig">
Expand Down Expand Up @@ -1568,6 +1598,102 @@
</listitem>
</varlistentry>
</variablelist>
<variablelist xml:id="pcntl.constants.waitid">
<title>First argument to <literal>waitid</literal> (<literal>idtype</literal>)</title>
<varlistentry xml:id="constant.p-all">
<term>
<constant>P_ALL</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Select any children.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.p-pid">
<term>
<constant>P_PID</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Select by process ID.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.p-pgid">
<term>
<constant>P_PGID</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Select by process group ID.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.p-pidfd">
<term>
<constant>P_PIDFD</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Select by PID file descriptor.
Specific to Linux (since Linux 5.4).
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.p-uid">
<term>
<constant>P_UID</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Select by effective user ID.
Specific to NetBSD and FreeBSD.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.p-gid">
<term>
<constant>P_GID</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Select by effective group ID.
Specific to NetBSD and FreeBSD.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.p-sid">
<term>
<constant>P_SID</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Select by session ID.
Specific to NetBSD and FreeBSD.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.p-jailid">
<term>
<constant>P_JAILID</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Select by jail identifier.
Specific to FreeBSD.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</appendix>
<!-- Keep this comment at the end of the file
Local variables:
Expand Down
42 changes: 37 additions & 5 deletions reference/pcntl/functions/pcntl-get-last-error.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,10 @@
<void />
</methodsynopsis>
<para>

Retrieve the error number (<literal>errno</literal>) set by the last
pcntl function that failed. The system error message associated with
the error number may be checked with <function>pcntl_strerror</function>.
</para>

&warn.undocumented.func;

</refsect1>

<refsect1 role="parameters">
Expand All @@ -29,7 +28,40 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns error code.
Returns the error number (<literal>errno</literal>) set by the last
pcntl function that failed. If there was no error, 0 is returned.
</para>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>pcntl_get_last_error</function> example</title>
<para>
This example will attempt to wait on child processes
in a situation where no child process exists,
then will print out the corresponding error message.
</para>
<programlisting role="php">
<![CDATA[
<?php
$pid = pcntl_wait($status);
if ($pid === -1) {
$errno = pcntl_get_last_error();
$message = pcntl_strerror($errno);
fwrite(STDERR, 'pcntl_wait failed with errno ' . $errno
. ': ' . $message . PHP_EOL);
}
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
pcntl_wait failed with errno 10: No child processes
]]>
</screen>
</example>
</para>
</refsect1>

Expand Down
48 changes: 41 additions & 7 deletions reference/pcntl/functions/pcntl-strerror.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,24 +10,26 @@
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>pcntl_strerror</methodname>
<methodparam><type>int</type><parameter>error_code</parameter></methodparam>
<methodparam><type>int</type><parameter>error_number</parameter></methodparam>
</methodsynopsis>
<para>

Returns the system error message associated with the given <parameter>error_number</parameter>
(<literal>errno</literal>) of the last pcntl function that failed.
The <parameter>error_number</parameter> parameter may be obtained by calling
<function>pcntl_get_last_error</function>.
</para>

&warn.undocumented.func;

</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>error_code</parameter></term>
<term><parameter>error_number</parameter></term>
<listitem>
<para>

An error number (<literal>errno</literal>),
returned by <function>pcntl_get_last_error</function>.
</para>
</listitem>
</varlistentry>
Expand All @@ -37,7 +39,39 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns error description.
Returns the error message, as a string.
</para>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>pcntl_strerror</function> example</title>
<para>
This example will attempt to wait on child processes
in a situation where no child process exists,
then will print out the corresponding error message.
</para>
<programlisting role="php">
<![CDATA[
<?php
$pid = pcntl_wait($status);
if ($pid === -1) {
$errno = pcntl_get_last_error();
$message = pcntl_strerror($errno);
fwrite(STDERR, 'pcntl_wait failed with errno ' . $errno
. ': ' . $message . PHP_EOL);
}
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
pcntl_wait failed with errno 10: No child processes
]]>
</screen>
</example>
</para>
</refsect1>

Expand Down
Loading