-- Copyright 2007-2020 Mitchell. See LICENSE.
-- This is a DUMMY FILE used for making LuaDoc for built-in functions in the
-- os table.

--- Extends Lua's `os` library to provide process spawning capabilities.
module('os')

---
-- Spawns an interactive child process *cmd* in a separate thread, returning
-- a handle to that process.
-- On Windows, *cmd* is passed to `cmd.exe`: `%COMSPEC% /c [cmd]`.
-- At the moment, only the Windows terminal version spawns processes in the same
-- thread.
-- @param cmd A command line string that contains the program's name followed by
--   arguments to pass to it. `PATH` is searched for program names.
-- @param cwd Optional current working directory (cwd) for the child
--   process. When omitted, the parent's cwd is used.
-- @param env Optional table of environment variables for the child process.
--   When omitted, the parent's environment is used.
-- @param stdout_cb Optional Lua function that accepts a string parameter for a
--   block of standard output read from the child. Stdout is read asynchronously
--   in 1KB or 0.5KB blocks (depending on the platform), or however much data is
--   available at the time.
--   At the moment, only the Win32 terminal version sends all output, whether it
--   be stdout or stderr, to this callback after the process finishes.
-- @param stderr_cb Optional Lua function that accepts a string parameter for a
--   block of standard error read from the child. Stderr is read asynchronously
--   in 1KB or 0.5kB blocks (depending on the platform), or however much data is
--   available at the time.
-- @param exit_cb Optional Lua function that is called when the child process
--   finishes. The child's exit status is passed.
-- @return proc or nil plus an error message on failure
-- @usage os.spawn('lua ' .. buffer.filename, print)
-- @usage proc = os.spawn('lua -e "print(io.read())"', print)
--        proc:write('foo\n')
-- @class function
-- @name os.spawn
local spawn

---
-- Returns the status of process *spawn_proc*, which is either "running" or
-- "terminated".
-- @return "running" or "terminated"
function spawn_proc:status() end

---
-- Blocks until process *spawn_proc* finishes (if it has not already done so)
-- and returns its status code.
-- @return integer status code
function spawn_proc:wait() end

---
-- Reads and returns stdout from process *spawn_proc*, according to string
-- format or number *arg*.
-- Similar to Lua's `io.read()` and blocks for input. *spawn_proc* must still be
-- running. If an error occurs while reading, returns `nil`, an error code, and
-- an error message.
-- Ensure any read operations read all stdout available, as the stdout callback
-- function passed to `os.spawn()` will not be called until the stdout buffer is
-- clear.
-- @param arg Optional argument similar to those in Lua's `io.read()`, but "n"
--   is not supported. The default value is "l", which reads a line.
-- @return string of bytes read
function spawn_proc:read(arg) end

---
-- Writes string input to the stdin of process *spawn_proc*.
-- Note: On Linux, if more than 65536 bytes (64K) are to be written, it is
-- possible those bytes need to be written in 65536-byte (64K) chunks, or the
-- process may not receive all input. However, it is also possible that there is
-- a limit on how many bytes can be written in a short period of time, perhaps
-- 196608 bytes (192K).
-- @param ... Standard input for *spawn_proc*.
function spawn_proc:write(...) end

---
-- Closes standard input for process *spawn_proc*, effectively sending an EOF
-- (end of file) to it.
function spawn_proc:close() end

---
-- Kills running process *spawn_proc*, or sends it Unix signal *signal*.
-- @param signal Optional Unix signal to send to *spawn_proc*. The default value
--   is 9 (`SIGKILL`), which kills the process.
function spawn_proc:kill() end