Skip to content

Fixes incorrect error description #5101

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 3 commits into from
May 13, 2025
Merged

Fixes incorrect error description #5101

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
282ca7c
Fixes incorrect error description
AArdeev May 12, 2025
e9416ab
Document inherit_fds option of popen.new
AArdeev May 12, 2025
254b4ad
Changed formatting of the close_fds flag to code.
AArdeev May 13, 2025
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
35 changes: 18 additions & 17 deletions doc/reference/reference_lua/popen.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -165,20 +165,19 @@ Below is a list of all ``popen`` functions and handle methods.

(if failure) ``nil, err``

Possible raised errors are:
Possible raised errors:

* IllegalParams: incorrect type or value of a parameter
* IllegalParams: group signal is set, while setsid is not
* ``IllegalParams``: incorrect type or value of a parameter
* ``IllegalParams``: group signal is set, while setsid is not

Possible error reasons when ``nil, err`` is returned are:
Possible error reasons when ``nil, err`` is returned:

* SystemError: dup(), fcntl(), pipe(), vfork() or close() fails in the
* ``SystemError``: dup(), fcntl(), pipe(), vfork() or close() fails in the
parent process
* SystemError: (temporary restriction) the parent process has closed stdin,
* ``SystemError``: (temporary restriction) the parent process has closed stdin,
stdout or stderr
* OutOfMemory: unable to allocate the handle or a temporary buffer

Possible ``opts`` items are:
Possible ``opts`` items:

* ``opts.stdin`` (action on STDIN_FILENO)
* ``opts.stdout`` (action on STDOUT_FILENO)
Expand Down Expand Up @@ -252,14 +251,17 @@ Below is a list of all ``popen`` functions and handle methods.
| | | or when Lua GC collects the handle. |
+----------------------+----------------+-------------------------------------------+


The returned ``ph`` handle provides a
:ref:`popen_handle:close() <popen-close>` method for explicitly
releasing all occupied resources, including the child process
itself if ``opts.keep_child`` is not set). However, if the ``close()``
method is not called for a handle during its lifetime, the
Lua GC will trigger the same freeing actions.

Since version 3.2.0, the ``inherit.fds`` option is added to the ``opts``
table. The option allows define file descriptor numbers that should be
left open in the child process if the ``close_fds`` flag is set to ``true``.

Tarantool recommends using ``opts.setsid`` plus ``opts.group_signal``
if a child process may spawn its own children and if they should all
be killed together.
Expand Down Expand Up @@ -397,7 +399,7 @@ Below is a list of all ``popen`` functions and handle methods.
:ref:`popen.shell() <popen-shell>`
:param table opts: options

Possible ``opts`` items are:
Possible ``opts`` items:

* ``opts.stdout`` (boolean, default ``true``, if ``true`` then read from stdout)
* ``opts.stderr`` (boolean, default ``false``, if ``true`` then read from stderr)
Expand All @@ -415,19 +417,18 @@ Below is a list of all ``popen`` functions and handle methods.

These errors are raised on incorrect parameters or when the fiber is cancelled:

* IllegalParams: incorrect type or value of a parameter
* IllegalParams: called on a closed handle
* IllegalParams: opts.stdout and opts.stderr are both set
* IllegalParams: a requested IO operation is not supported by
* ``IllegalParams``: incorrect type or value of a parameter
* ``IllegalParams``: called on a closed handle
* ``IllegalParams``: opts.stdout and opts.stderr are both set
* ``IllegalParams``: a requested IO operation is not supported by
the handle (stdout / stderr is not piped)
* IllegalParams: attempt to operate on a closed file descriptor
* FiberIsCancelled: cancelled by external code
* ``IllegalParams``: attempt to operate on a closed file descriptor
* ``FiberIsCancelled``: cancelled by external code

``nil, err`` is returned on following failures:

* SocketError: an IO error occurs at read()
* TimedOut: exceeded the opts.timeout quota
* OutOfMemory: no memory space for a buffer to read into
* LuajitError: ("not enough memory"): no memory space for the Lua string

.. _popen-write:
Expand Down