Модуль popen

методы дескриптора popen

object popen_handle¶

popen_handle:read([opts])¶

Считывание данных из дочернего процесса.

Параметры:	ph (handle) – дескриптор дочернего процесса, созданный через popen.new() или popen.shell() opts (table) – параметры

Возможные элементы opts:

• opts.stdout (boolean, значение по умолчанию — true, при значении true выполняется считывание из stdout)
• opts.stderr (boolean, значение по умолчанию — false, при значении true выполняется считывание из stderr)
• opts.timeout (число, значение по умолчанию — 100 лет, временная квота в секундах)

In other words: by default read() reads from stdout, but reads from stderr if one sets opts.stderr to true. It is not legal to set both opts.stdout and opts.stderr to true.

возвращает:	(при успешном выполнении) строка со считанным значением, пустая строка при EOF (при неудачном выполнении) nil, err

Possible errors

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

• IllegalParams: некорректный тип или значение параметра
• IllegalParams: вызов дескриптора, который уже был закрыт
• IllegalParams: одновременно установлены opts.stdout и opts.stderr
• IllegalParams: запрашиваемая операция ввода-вывода не поддерживается дескриптором (вывод stdout / stderr не перенаправлен)
• IllegalParams: попытка произвести операцию над закрытым файловым дескриптором
• FiberIsCancelled: cancelled by external code

nil, err is returned on following failures:

• SocketError: ошибка ввода-вывода при выполнении read()
• TimedOut: превышение квоты opts.timeout
• OutOfMemory: недостаточно памяти для считывания в буфер
• LuajitError: («not enough memory»): недостаточно памяти для строки Lua

popen_handle:write(str[, opts])¶

Запись строки str в поток stdin дочернего процесса.

Параметры:	ph (handle) – дескриптор дочернего процесса, созданный через popen.new() или popen.shell() str (string) – строка для записи opts (table) – параметры
возвращает:	true on success, false on error
возвращаемое значение:
	(при успешном выполнении) boolean = true (при неудачном выполнении) nil, err

Possible opts items are: opts.timeout (number, default 100 years, time quota in seconds).

Возможные ошибки:

• IllegalParams: некорректный тип или значение параметра
• IllegalParams: вызов дескриптора, который уже был закрыт
• IllegalParams: длина строки превышает SSIZE_MAX
• IllegalParams: запрашиваемая операция ввода-вывода не поддерживается дескриптором (вывод stdin не перенаправлен)
• IllegalParams: попытка произвести операцию над закрытым файловым дескриптором
• FiberIsCancelled: файбер отменен во внешней программе

Возможные причины ошибок, когда возвращается nil, err:

• SocketError: ошибка ввода-вывода при выполнении write()
• TimedOut: превышение квоты opts.timeout

write() может передать управление (yield) и заблокировать файбер, если дочерний процесс не считывает данные из stdin и буфер канала заполнился. Размер буфера зависит от платформы. Если сомневаетесь, обратите внимание на опцию opts.timeout.

Когда опция opts.timeout не установлена, write() блокирует файбер до момента полной записи данных или возникновения ошибки записи.

popen_handle:shutdown([opts])¶

Закрытие канала с std* со стороны родителя.

Параметры:	ph (handle) – дескриптор дочернего процесса, созданный через popen.new() или popen.shell() opts (table) – параметры
возвращает:	true on success, false on error
возвращаемое значение:
	(при успешном выполнении) boolean = true

Возможные элементы opts:

• opts.stdin (boolean) закрыть stdin со стороны родителя
• opts.stdout (boolean) закрыть stdout со стороны родителя
• opts.stderr (boolean) закрыть stderr со стороны родителя

Мы можем использовать термин std* для указания на любой из этих элементов.

Возможные ошибки:

• IllegalParams: некорректный параметр дескриптора
• IllegalParams: вызов дескриптора, который уже был закрыт
• IllegalParams: не выбран ни один из потоков stdin, stdout или stderr
• IllegalParams: запрашиваемая операция ввода-вывода не поддерживается дескриптором (один из потоков std* не перенаправлен)

Основная цель использования shutdown() — отправка EOF в дочерний поток stdin. Однако stdout / stderr может быть уже закрыт со стороны родительского процесса.

shutdown() does not fail on already closed fds (idempotence). However, it fails on an attempt to close the end of a pipe that never existed. In other words, only those std* options that were set to popen.opts.PIPE during handle creation may be used here (for popen.shell(): 'r' corresponds to stdout, 'R' to stderr and 'w' to stdin).

shutdown() не закрывает никакие файловые дескрипторы при завершении с ошибкой: либо закрываются все запрашиваемые дескрипторы (при успешном выполнении), либо ни один из них.

Пример:

local popen = require('popen')
local ph = popen.shell('sed s/foo/bar/', 'rw')
ph:write('lorem foo ipsum')
ph:shutdown({stdin = true})
local res = ph:read()
ph:close()
print(res) -- lorem bar ipsum

popen_handle:terminate()¶

Отправка сигнала SIGTERM дочернему процессу.

Параметры:	ph (handle) – дескриптор дочернего процесса, созданный через popen.new() или popen.shell()
возвращает:	для получения информации об ошибках и возвращаемых значениях смотрите popen_handle:signal()

terminate() просто отправляет сигнал SIGTERM. Он не освобождает никакие ресурсы (такие как память для дескрипторов popen и файловые дескрипторы).

popen_handle:kill()¶

Отправка сигнала SIGKILL дочернему процессу.

Параметры:	ph (handle) – дескриптор дочернего процесса, созданный через popen.new() или popen.shell()
возвращает:	для получения информации об ошибках и возвращаемых значениях смотрите popen_handle:signal()

kill() просто отправляет сигнал SIGKILL. Он не освобождает никакие ресурсы (такие как память для дескрипторов popen и файловые дескрипторы).

popen_handle:signal(signo)¶

Отправка сигнала дочернему процессу.

Параметры:	ph (handle) – дескриптор дочернего процесса, созданный через popen.new() или popen.shell() signo (number) – отправляемый сигнал
возвращает:	(при успешном выполнении) true (сигнал отправлен) (при неудачном выполнении) nil, err

Возможные ошибки:

• IllegalParams: некорректный параметр дескриптора
• IllegalParams: вызов дескриптора, который уже был закрыт

Возможные значения ошибок при возвращении nil, err:

• SystemError: процесс больше не существует (также может возвращаться для зомби-процессов или когда все процессы в группе являются зомби-процессами (но см. примечание для Mac OS ниже)
• SystemError: неправильный номер сигнала
• SystemError: нет разрешения на отправку сигнала процессу или группе процессов (возвращается на Mac OS, когда сигнал отправляется группе процессов, где лидер группы является зомби-процессом (или все процессы являются зомби-процессами, детали неясны) (эта ошибка также может возникнуть по другим причинам, детали неясны)

Если для дескриптора установлены opts.setsid и opts.group_signal, сигнал отправляется группе процессов, а не отдельному процессу. Для подробной информации по групповым сигналам смотрите popen.new(). Внимание: на Mac OS процесс в группе может не получить сигнал, особенно если он только что был разветвлен (возможно это происходит из-за состояния гонки).

Примечание: Некоторые сигналы имеют разные номера на разных платформах. Поэтому в этом модуле мы предлагаем константы popen.signal.SIG*.

popen_handle:info()¶

Получение информации о дескрипторе popen.

Параметры:	ph (handle) – дескриптор дочернего процесса, созданный через popen.new() или popen.shell() signo (number) – отправляемый сигнал
возвращает:	(при успешном выполнении) отформатированный результат
возвращаемое значение:
	res

Возможные ошибки:

• IllegalParams: некорректный параметр дескриптора
• IllegalParams: вызов дескриптора, который уже был закрыт

Результат выводится в следующем формате:

{
    pid = <number> or <nil>,
    command = <string>,
    opts = <table>,
    status = <table>,
    stdin = one-of(
        popen.stream.OPEN   (== 'open'),
        popen.stream.CLOSED (== 'closed'),
        nil,
    ),
    stdout = one-of(
        popen.stream.OPEN   (== 'open'),
        popen.stream.CLOSED (== 'closed'),
        nil,
    ),
    stderr = one-of(
        popen.stream.OPEN   (== 'open'),
        popen.stream.CLOSED (== 'closed'),
        nil,
    ),
}

pid — это идентификатор процесса, когда тот находится в рабочем состоянии; для завершенного процесса pid имеет значение nil.

command — это конкатенация аргументов, разделенных пробелами, которые были переданы в execve(). Аргументы, состоящие из нескольких слов, заключаются в кавычки. Кавычки внутри аргументов не экранируются.

opts – это таблица параметров дескриптора, описанная в разделе opts функции popen.new(). opts.env здесь не отображается, потому что карта переменных среды не хранится в дескрипторе.

status — это таблица, отображающая состояние процесса в следующем формате:

{
    state = one-of(
        popen.state.ALIVE    (== 'alive'),
        popen.state.EXITED   (== 'exited'),
        popen.state.SIGNALED (== 'signaled'),
    )
    -- Отображается при состоянии процесса 'завершенный'.
    exit_code = <number>,
    -- Отображается при состоянии процесса 'принимающий сигнал'.
    signo = <number>,
    signame = <string>,
}

stdin, stdout, and stderr reflect the status of the parent’s end of a piped stream. If a stream is not piped, the field is not present (nil). If it is piped, the status may be either popen.stream.OPEN (== 'open') or popen.stream.CLOSED (== 'closed'). The status may be changed from 'open' to 'closed' by a popen_handle:shutdown({std… = true}) call.

Пример 1

(в консоли Tarantool)

tarantool> require('popen').new({'/usr/bin/touch', '/tmp/foo'})
---
- command: /usr/bin/touch /tmp/foo
  status:
    state: alive
  opts:
    stdout: inherit
    stdin: inherit
    group_signal: false
    keep_child: false
    close_fds: true
    restore_signals: true
    shell: false
    setsid: false
    stderr: inherit
  pid: 9499
...

Пример 2

(в консоли Tarantool)

tarantool> require('popen').shell('grep foo', 'wrR')
---
- stdout: open
  command: sh -c 'grep foo'
  stderr: open
  status:
    state: alive
  stdin: open
  opts:
    stdout: pipe
    stdin: pipe
    group_signal: true
    keep_child: false
    close_fds: true
    restore_signals: true
    shell: true
    setsid: true
    stderr: pipe
  pid: 10497
...

popen_handle:wait()¶

Ожидание, пока дочерний процесс не завершится или не получит сигнал.

Параметры:	ph (handle) – дескриптор дочернего процесса, созданный через popen.new() или popen.shell() signo (number) – отправляемый сигнал
возвращает:	(при успешном выполнении) отформатированный результат
возвращаемое значение:
	res

Возможные ошибки:

• IllegalParams: некорректный параметр дескриптора
• IllegalParams: вызов дескриптора, который уже был закрыт
• FiberIsCancelled: файбер отменен во внешней программе

Отформатированный результат представляет собой таблицу состояний процесса (аналогично компоненту status таблицы, возвращаемой через popen_handle:info()).

popen_handle:close()¶

Закрытие дескриптора popen.

Параметры:	ph (handle) – дескриптор дочернего процесса, созданный через popen.new() или popen.shell()
возвращает:	(при успешном выполнении) true (при неудачном выполнении) nil, err

Возможные ошибки:

• IllegalParams: некорректный параметр дескриптора

Возможные результаты диагностики, когда возвращается nil, err (не рассматривайте эти случаи как ошибки):

• SystemError: нет разрешения на отправку сигнала процессу или группе процессов (это сообщение диагностики может появиться из-за особенностей обработки зомби-процессов в Mac OS, когда установлен opts.group_signal, см. popen_handle:signal(). Оно также может появиться по другим причинам, детали неясны).

Если известно, что процесс был завершен, то в результате всегда возвращается true (например, после выполнения popen_handle:wait() не будет отправлено никакого сигнала, так что никакой ошибки не может возникнуть).

close() принудительно завершает процесс через SIGKILL и освобождает все ресурсы, связанные с дескриптором popen.

Подробная информация об отправке сигналов:

• Сигнал отправляется только когда поле opts.keep_child не установлено.
• Сигнал отправляется только когда процесс находится в рабочем состоянии согласно информации, доступной на текущей итерации цикла событий. (Здесь есть слабое место: сигнал может быть отправлен зомби-процессу, но это не представляет никакой угрозы).
• Сигнал отправляется процессу или группе процессов в зависимости от opts.group_signal. (Для подробной информации о групповых сигналах смотрите popen.new()).

Ресурсы освобождаются вне зависимости от того, успешно ли отправился сигнал: дескрипторы файлов закрываются, память освобождается, а дескриптор popen помечается как закрытый.

Над закрытым дескриптором невозможно выполнять никакие операции кроме close(), которая всегда выполняется успешно над закрытым дескриптором (идемпотентность).

close() может вернуть true или nil, err, но она всегда освобождает ресурсы дескриптора. Поэтому для того, кто отправил сигнал, любое возвращаемое значение означает успешное выполнение. Возвращаемые значения только дают информацию для логирования или составления отчетов.

Поля дескриптора

popen_handle.pid
popen_handle.command
popen_handle.opts
popen_handle.status
popen_handle.stdin
popen_handle.stdout
popen_handle.stderr

За более подробной информацией обратитесь к popen_handle:info().

Константы модуля

- popen.opts
  - INHERIT (== 'inherit')
  - DEVNULL (== 'devnull')
  - CLOSE   (== 'close')
  - PIPE    (== 'pipe')

- popen.signal
  - SIGTERM (== 9)
  - SIGKILL (== 15)
  - ...

- popen.state
  - ALIVE    (== 'alive')
  - EXITED   (== 'exited')
  - SIGNALED (== 'signaled')

- popen.stream
  - OPEN    (== 'open')
  - CLOSED  (== 'closed')