/lua-process

process module

Primary LanguageC

lua-process

process module.

Installation

luarocks install process --from=http://mah0x211.github.io/rocks/

Constants

these constants defined at the process.*

Use for waitpid API

  • WNOHANG
  • WUNTRACED
  • WCONTINUED
  • WNOWAIT

Environment

env = getenv()

get environment variables.

Returns

  • env:table: environment variables.

Process ID

pid = getpid()

get calling process id.

Returns

  • pid:number: process id.

pid = getppid()

get parent process id.

Returns

  • pid:number: parent process id.

Group ID

gid = getgid( [gname] )

get real group id of a calling process or a specified group-name.

Parameters

  • gname:string: group name.

Returns

  • gid:number: group id.

gid = getegid()

get effective group id of calling process.

Returns

  • gid:number: group id.

gname = getgname( [gid] )

get group name of a calling process or specified group id.

Parameters

  • gid:number: group id.

Returns

  • gname:string: group name.

err = setgid( gid or gname )

set real group id.

Parameters

  • gid:number: group id.
  • gname:string: group name.

Returns

  • err:string: nil on succes, or error string on failure.

err = setegid( gid or gname )

set effective group id.

Parameters

  • gid:number: group id.
  • gname:string: group name.

Returns

  • err:string: nil on succes, or error string on failure.

err = setregid( rgid or gname, egid or gname )

set real and effective group id.

Parameters

  • rgid:number: real group id.
  • egid:number: effective group id.
  • gname:string: group name.

Returns

  • err:string: nil on succes, or error string on failure.

User ID

uid = getuid( [uname] )

get real user id of a calling process or a specified user-name.

Parameters

  • uname:string: user name.

Returns

  • uid:number: user id.

uid = geteuid()

get effective user id of calling process.

Returns

  • uid:number: user id.

uname = getuname( [uid] )

get user name of calling process or a specified user id.

Parameters

  • uid:number: user id.

Returns

  • uname:string: user name.

err = setuid( uid or uname )

set real user id.

Parameters

  • uid:number: user id.
  • uname:string: user name.

Returns

  • err:string: nil on succes, or error string on failure.

err = seteuid( uid or uname )

set effective user id.

Parameters

  • uid:number: user id.
  • uname:string: user name.

Returns

  • err:string: nil on succes, or error string on failure.

err = setreuid( ruid or uname, euid or uname )

set real and effective user id.

Parameters

  • ruid:number: real user id.
  • euid:number: effective user id.
  • uname:string: user name.

Returns

  • err:string: nil on succes, or error string on failure.

Session ID

sid, err = getsid( pid )

get session id of the specified process.

Parameters

  • pid:number: process id.

Returns

  • sid:number: session id.
  • err:string: nil on succes, or error string on failure.

sid, err = setsid()

creates a new session.

Returns

  • sid:number: session id.
  • err:string: nil on succes, or error string on failure.

Resource Utilization

usage, err = getrusage()

get information about resource utilization.

Returns

  • usage:table: table of struct rusage.
  • err:string: nil on success, or error string on failure.

Current Working Directory

path, err = getcwd()

get working directory pathname.

Returns

  • path:string: working directory pathname.
  • err:string: nil on success, or error string on failure

err = chdir( path )

change current working directory.

Parameters

  • path:string: valid directory path string.

Returns

  • err:string: nil on success, or error string on failure.

Child Process

pid, err, again = fork()

create child process.

Returns

  • pid:number: 0 to the child process, and a child process id to the calling process on success, or nil on failure.
  • err:string: nil on success, or error string on failure.
  • again:boolean: true if got EAGAIN.

status, err = waitpid( pid [, ...] )

wait for process termination.
please refer to man 2 waitpid for more details.

Parameters

  • pid:number: process id (default: -1).
  • ...: to use the following options;
    • WNOHANG
    • WUNTRACED
    • WCONTINUED
    • WNOWAIT

Returns

  • status:table: status table if succeeded.
    • pid = pid:number.
    • exit = exit_status:number if WIFEXITED is true.
    • termsig = signo:number if WIFSIGNALED is true.
    • stopsig = signo:number if WIFSIGNALED is true.
    • continue = true if WIFCONTINUED is true
    • nochild = true if errno is ECHILD.
  • err:string: nil on success, or error string on failure.

child, err = exec( path [, args [, env [, cwd [, nonblock]]]] )

execute a specified file.

please refer to man 2 execve for more details.

Parameters

  • path:string: filepath.
  • args:table: argument array table.
  • env:table: argument key-value pair table.
  • cwd:string: custom working directory.
  • nonblock:boolean: if set to true, child:stdin, child:stdout and child:stderr are in non-blocking mode.

Returns

  • child:process.child: instantance of process.child module.
  • err:string: nil on success, or error string on failure.

Suspend execution for an interval of time

rc = sleep( sec )

suspend execution of the calling process until specified seconds.

Parameters

  • sec:number: unsigned integer number.

Returns

  • rc:number: 0 on success, and >0 if an error occurs.

rc = nsleep( nsec )

suspend execution of the calling process until specified nanoseconds.

Parameters

  • nsec:number: unsigned integer.

Returns

  • rc:number: 0 on success, and >0 if an error occurs.

Errors

errno = errno()

getting current process/thread errno.

Returns

  • errno:number: current process/thread errno.

err = strerror( [errno:number] )

getting message string corresponding to errno.

Parameters

  • errno:number: error number that defined in errno.h.
    if passed argument is nil then to use global errno.

Returns

  • err:string: error string.

Date and Time

sec, err = gettimeofday()

get the time as well as a timezone.

Returns

  • sec:number: current time.
  • err:string: nil on success, or error string on failure.

Descriptors

newfd, err = dup( oldfd )

create a copy of the file descriptor oldfd.
please refer to man 2 dup for more details.

Parameters

  • oldfd:number: file descriptor.

Returns

  • newfd:number: new file descriptor.
  • err:string: nil on success, or error string on failure.

newfd, err = dup2( oldfd, newfd )

create a copy of the file descriptor oldfd.
please refer to man 2 dup2 for more details.

Parameters

  • oldfd:number: file descriptor.
  • newfd:number: file descriptor.

Returns

  • newfd:number: new file descriptor.
  • err:string: nil on success, or error string on failure.

ok, err = close( fd )

close a existing file descriptor.

Parameters

  • fd:number: file descriptor.

Returns

  • ok:boolean: true on success, or false on failure.
  • err:string: error string on failure.

Instance of process.child module

process.exec API return this instance on success.

Example

local exec = require('process').exec;
local cmd = exec( 'echo', { 'hello world' } );
-- read from stdout
print( cmd:stdout() ); -- 'hello world\n'

pid = child:pid()

get process id.

Returns

  • pid:number: process id.

fdin, fdout, fderr = child:fds()

get file descriptors of stdin, stdout and stderr.

Returns

  • fdin:number: stdin file descriptor.
  • fdout:number: stdout file descriptor.
  • fderr:number: stderr file descriptor.

data, err, again = child:stdout()

read the data from stdout of child process.

Returns

  • data:string: data as string.
  • err:string: nil on success, or error string on failure.
  • again:boolean: true if got a EAGAIN or EWOULDBLOCK.

data, err, again = child:stderr()

read the data from stderr of child process.

Returns

  • data:string: data as string.
  • err:string: nil on success, or error string on failure.
  • again:boolean: true if got a EAGAIN or EWOULDBLOCK.

len, err, again = child:stdin( data )

write the data to stdin of child process.

Parameters

  • data:string: data string.

Returns

  • len:number: number of bytes written.
  • err:string: nil on success, or error string on failure.
  • again:boolean: true if got a EAGAIN or EWOULDBLOCK.

err = child:kill( [signo] )

send signal to a child process.

Parameters

  • signo:number: signal number. default SIGTERM.

Returns

  • err:string: nil on success, or error string on failure.