LuaPosix

This is a list of the Lua Posix functions. Included is helpful snippets of code.
Install lua posix. To get this list do:
 require "posix"
 for a in pairs(posix) do 
 print(a)
 end
=access=
check real user's permissions for a file
====Synopsis====
 posix.access(pathname, mode)
====Description====
access() checks whether the calling process can access the file pathname. If pathname is a symbolic link, it is dereferenced.
The mode specifies the accessibility check(s) to be performed, and is either the string "f", or one or more of "r", "w", and "x". "f" tests for the existence of the file. "r", "w", and "x" test whether the file exists and grants read, write, and execute permissions, respectively.
====Return Value====
On success (all requested permissions granted), zero is returned. On error (at least one char in mode asked for a permission that is denied, or some other error occurred), nil, errorstr and errno is returned.
====Examples====
 status, errstr, errno = posix.access("/etc/passwd", "rw")
 if not posix.access("/foo", "f") then
 print("/foo does not exist")
 end
====References====
https://man7.org/linux/man-pages/man2/access.2.html
=chdir=
change working directory
====Synopsis====
 posix.chdir(path)
====Return Value====
On success, zero is returned. On error, nil, an error string and errno is returned.
====Examples====
 status, errstr, errno = posix.chdir("/tmp")
 if posix.chdir("/tmp") then
 print("Changed current working dir to:", posix.getpwd())
 fi
=chmod=
change permissions of a file
====Synopsis====
 posix.chmod(path, mode)
====Description====
The mode of the file given by path is changed.
Modes are specified in one of the following formats
* "rwxrwxrwx" (i.e "rw-rw-w--")
* "ugoa+-=rwx" (i.e "u+w")
* "+-=rwx" (i.e "+w")
====Return Value====
On success, zero is returned. On error, nil, errstr and errno is returned.
====Examples====
 posix.chmod("/tmp", "a+rwx")
 status, errstr = posix.chmod(file, "-w")
 if not status then
 print(errstr)
 fi
=chown=
INPUT
*Path-location of file or directory
* UID - User id number
* GID - Group id number
OUPUT
*String - 0 is success and nil for failure
 bar = require "posix"
 print(bar.chown("/etc/passwd",100,200)
 --above will give back nil. Since we printed it will also give back the system errors.
=clock_getres=
TODO
=clock_gettime=
TODO
=crypt=
password and data encryption
====Synopsis====
 posix.crypt(string, salt)
====Return Value====
On success, zero is returned. On error, nil, an error string and errno is returned.
=ctermid=
INPUT
*NONE- DISPLAYS the terminal id
OUTPUT
*String with the terminal id
 bar = require "posix"
 print(bar.ctermid())
=dir=
read a directory
====Synopsis====
 posix.dir(path)
====Description====
Reads directory path, and returns a table with all the files. If path is omitted, current working dir is read.
====Return Value====
posix.dir() returns a table with all filenames on succes. On error, nil, an error string and errno is returned.
====Examples====
 files, errstr, errno = posix.dir("/var/log")
 if files then
 for a,b in ipairs(files) do
 print(b)
 end
 else
 print(errstr)
 end
=dup=
duplicate a file descriptor
====Synopsis====
 posix.dup(oldfd[, newfd])
====Description====
posix.dup() creates a copy of the file descriptor oldfd.
newfd will be the copy of oldfd, closing newfd first if necessary. 
If newfd is omitted, the lowest-numbered unused descriptor will be used for the new descriptor.
====Return Value====
posix.dup() returns the new descriptor, or nil, an error string and errno if an error occured.
=errno=
Display the error information
INPUT
*NONE
OUPUT
*Success, or Error message
 bar = require "posix"
 a,b = bar.dir("/var/foo"), bar.errno()
 print(a,b)
 -- a will be nil or 0, b will be No such file or directory or Success
=exec=
execute a file
====Synopsis====
 posix.exec(path,[args])
====Description====
exec() replaces the current process image with a new process image.
====Return Value====
On success exec() will not return. On error nil, errstr and errno is returned.
=execp=
execute a file using PATH environment variable
====Synopsis====
 posix.execp(path,[args])
====Description====
execp() replaces the current process image with a new process image. If path does not contain a slash (/) character the file wil be searched for in PATH environment variable.
====Return Value====
On success execp() will not return. On error nil, errstr and errno is returned.
=mkfifo=
INPUT
*PATH- where to make the fifo
OUPUT
* 0 for success, nil for failure
 bar = require "posix"
 print(bar.mkfifo("/tmp/bobo"))
 --Returns 0 for success, nil for failure
=files=
Returns an interator function that loops over each file in the given directory
INPUT
*PATH- Directory
OUPUT
 require "posix"
 for name in posix.files("/etc") do
 print (name)
 end
=fork=
INPUT
*None
OUTPUT
returns: -1 on error, 0 to the child process, and the pid of the child to the parent.
 require("posix")
 
 print ("parent: my pid is: " .. posix.getpid("pid")) 
 
 local pid = posix.fork () 
 
 if ( pid == -1 ) then
 print ("parent: The fork failed.")
 elseif ( pid == 0 ) then
 print ("child: Hello World! I am pid: " .. posix.getpid("pid") )
 print ("child: I'll sleep for 1 second ... ")
 posix.sleep(1)
 print ("child: Good bye");
 else
 print ("parent: While the child sleeps, I'm still running.")
 print ("parent: waiting for child (pid:" .. pid .. ") to die...")
 posix.wait(pid)
 print ("parent: child died, but I'm still alive.")
 print ("parent: Good bye")
 end
 parent: my pid is: 11050
 child: Hello World! I am pid: 11051
 child: I'll sleep for 1 second ... 
 parent: While the child sleeps, I'm still running.
 parent: waiting for child (pid:11051) to die...
 child: Good bye
 parent: child died, but I'm still alive.
 parent: Good bye
=gmtime=
TODO
=getcwd=
Get current working directory
INPUT
*NONE
OUTPUT
*String- contents of which is the current working directory
 require "posix"
 print(posix.getcwd())
=getenv=
INPUT
*NONE
OUPUT
*Table - Current Environment settings
 bar = require "posix"
 bobo = bar.getenv()
 for a,b in pairs(bobo) do print(b) end
 -- Varible - Value
=getgroup=
INPUT
*GID, or groupname
OUPUT
*TABLE -contents of which hold the group name,gid, and users
 bar = require "posix"
 bobo = bar.getgroup(1000)
 for a,b in pairs(bobo) do print(a,b) end
 --if you use pairs then bobo will print also the name and gid or the group
 --if you use ipairs then just the group members
 1 user1
 2 user2
 name wheel
 gid 1
=getlogin=
get user name
====Synopsis====
 posix.getlogin()
====Description====
getlogin() returns a string containing the name of the user logged in on the controlling terminal of the process, or nil if this information cannot be determined.
====Examples====
 print(posix.getlogin())
=getrlimit=
TODO
=getpasswd=
get password file entry
====Synopsis====
 posix.getpasswd(user, field)
====Description====
getpasswd() queries the local /etc/passwd database. user can be either an uid or a username. field is a string of one of "uid", "name", "gid", "password", "gecos", "dir" or "shell".
====Return Value====
Returns the value of field for user. If field is omitted, a table with all fields is returned.
====Examples====
 for a,b in pairs(posix.getpasswd("root")) do
 print(a,b)
 end
Output:
 uid 0
 name root
 gid 0
 passwd x
 gecos root
 dir /root
 shell /bin/bash
 print(posix.getpasswd("root", "shell"))
Output:
 /bin/sh
=getprocessid=
INPUT
*Selector - either [egid,euid,gid,uid,pgrp,pid,ppid,NULL]
OUPUT
*Number that matches the current process and the selector
 bar = require "posix"
 print(bar.getprocessid("gid"))
 18456 
 --it just printed the current process id for the script or interactive lua.
Is there a version difference here? AL 1.7.7 calls this "getpid" Nangel
=gettimeofday=
TODO
=glob=
find pathnames matching a pattern
====Synopsis====
 posix.glob(pattern)
====Description====
The glob() function searches for all the pathnames matching pattern according to the rules used by the shell.
====Return Value====
On successful comlpetion, glob() returns a table with the filenames. On error glob() returns nil, errstr and errno.
====Examples====
 for i,j in pairs(posix.glob("/proc/[0-9]*/exe")) do
 local f = posix.readlink(j)
 if f then
 print(f)
 end
 end
=kill=
INPUT
*PID- process identifier
*Signal- to send to the process
OUPUT
 bar = require "posix"
 --kill your current process
 bobo = bar.getprocessid("pid")
 bar.kill(bobo,9)
 ---Signals looks to be the number signals accepted in Unix
=link=
make a new name for a file
====Synopsis====
 posix.dup(oldpath, newpath[, symbolic])
====Description====
Creates a new name to an existing file. If symbolic is true the new name will be a symbolic link (soft link), otherwise it will be a hard link.
====Return Value====
On success, zero is returned. On error link() returns nil, errstr and errno.
====Examples====
 require "posix"
 source="/etc/passwd"
 dest="testfile"
 status, errstr = posix.link(source, dest, true)
 if status == nil then
 io.stderr:write(dest..": "..errstr.."\n")
 end
=localtime=
TODO
=mkdir=
create a directory
====Synopsis====
 posix.dup(pathname)
====Descritption====
mkdir() attempts to create a directory named pathname.
====Return Value====
glob() returns 0 on success, or nil, errstr and errno on error.
====Example====
 require "posix"
 newdir = "/home/user/bobo"
 status, errstr = posix.mkdir(newdir)
 if status == nil then
 io.stderr:write(newdir..": "..errstr.."\n")
 end
=pathconf=
get configuration values for files
====Synopsis====
 posix.pathconf(path, name)
====Description====
posix.pathconf() gets a value for configuration option name for the filename path. Setting name equal to one of the following strings returns the following configuration options:
* link_max
** returns the maximum number of links to the file. If path refer to a directory, then the value applies to the whole directory.
* max_canon
** returns the maximum length of a formatted input line, where path must refer to a terminal.
* max_input
** returns the maximum length of an input line, where path must refer to a terminal.
* name_max
** returns the maximum length of a filename in the directory path the process is allowed to create.
* path_max
** returns the maximum length of a relative pathname when path is the current working directory.
* pipe_buf
** returns the size of the pipe buffer, where path must refer to a FIFO.
* chown_restricted
** returns non-zero if the chown(2) call may not be used on this file. If path refer to a directory, then this applies to all files in that directory.
* no_trunc
** returns non-zero if accessing filenames longer than name_max generates an error.
* vdisable
** returns non-zero if special character processing can be disabled, where path must refer to a terminal.
====Return Value====
The limit is returned, if one exists. If name is omitted, a table of all limits is returned.
====Examples====
 for i,j in pairs(posix.pathconf("/dev/tty" )) do
 print(i, j)
 end
Will ouput:
 pipe_buf 4096
 link_max 127
 path_max 4096
 max_canon 255
 chown_restricted 1
 no_trunc 1
 max_input 255
 name_max 255
 vdisable 0
====References====
https://man7.org/linux/man-pages/man3/pathconf.3.html
=pipe=
TODO
====Example====
 require "posix"
 rd, wr = posix.pipe()
 wr:write("hello, world\n")
 wr:close()
 print(rd:read("*all"))
 rd:close()
=putenv=
INPUT
*STRING-
OUPUT
* 0 if success, nil if not
 require "posix"
 posix.putenv("DISPLAY=localhost:0")
=readlink=
INPUT
*PATH-path to link
OUPUT
* 0 if success, nil if failure
 require "posix"
 posix.readlink("/etc/rc.d/postfix")
 --0 if sucess, nil if failed
=rmdir=
INPUT
*PATH- path to directory
OUPUT
* 0 for sucess
* nil for failure
 require "posix"
 posix.rmdir("/home/testdir")
 -- 0 for success, nil for failure
=setgid=
INPUT
*Group
** Name or GID
OUPUT
* 0 for sucess
* nil for failure
 require "posix"
 posix.setgid("1000")
=setlogmask=
TODO
=setrlimit=
TODO
=setuid=
INPUT
*User
** Name or UID
OUPUT
*0 for sucess, nil for failure
 
 require "posix"
 posix.setuid("1000")
 -- 0 for sucess, nil for failure
=sleep=
INPUT
*SECONDS
OUPUT
*0 for sucess, nil for failure
 require "posix"
 posix.sleep(5)
 -- will sleep for 5 seconds, usually will not fail
=stat=
INPUT
*PATH - location of file or direcory
*Selector - 
**dev
**type
**ctime
**nlink
**atime
**uid
**mtime
**gid
**mode
**ino
**size
OUPUT
*If no mode will output as a table with each of the above set
*If mode is set then will give a string with value
 
 require "posix"
 bar = posix.stat("/etc/")
 for a,b in pairs(bar) do print(a,b) end
 dev 769
 type directory
 ctime 1194624026
 nlink 113
 atime 1194866712
 uid 0
 mtime 1194624026
 gid 0
 mode rwxr-xr-x
 ino 4
 size 6208
=sysconf=
INPUT
*Accept a selector if given anything
**tzname_max
**clk_tck
**stream_max
**ngroups_max
**child_max
**open_max
**saved_ids
**job_control
**version
**arg_max
OUPUT
*TABLE - if no selector
*STRING - if 1 selector
 require "posix"
 bar = posix.stat()
 for a,b in pairs(bar) do print(a,b) end
 tzname_max 6
 clk_tck 100
 stream_max 16
 ngroups_max 65536
 child_max 999
 open_max 1024
 saved_ids 1
 job_control 1
 version 200112
 arg_max 131072
=strftime=
TODO
=time=
TODO
=times=
INPUT
*
**utime
**cstime
**elapsed
**cutime
**stime
OUPUT
*TABLE - if non specified output all values in a table
*STING - if one of the above is specified string output
 
 require "posix"
 bar = posix.times()
 for a,b in pairs(bar) do print(a,b) end
 --Maybe takes function calls to see how long they run
=ttyname=
INPUT
*NONE
OUPUT
*STRING - what tty am I on
 require "posix"
 print(posix.ttyname())
=umask=
INPUT
*NONE
** or mode, what to change the umask to
OUPUT
*STRING - what is the current umask set to
** or mode, what to change is to
 require "posix"
 print(posix.umask)
 -- rwxr-xr-x
 --or change it
 posix.umask("a=rwx")
 print(posix.umask())
 -- rwxrwxrwx
= uname =
get name and information about current kernel
====Synopsis====
 posix.access([format])
====Description====
uname() returns the string format with directives prefixed by '%' replaced with specified systrem information. If format is not specified or is nil, then the string "%s %n %r %v %m" will be used.
The format string directives are:
 %s - kernel name
 %n - network node hostname
 %r - kernel release
 %v - kernel version
 %m - machine hardware name
====Return Value====
A string with the formatted system information.
====Examples====
 print("Kernel version is: "..posix.uname("%v"))
====References====
https://man7.org/linux/man-pages/man2/uname.2.html
=utime=
INPUT
*Path-location of file or directory
**atime - access time
**mtime - modification time
OUPUT
* 0 for sucess
* nil for failure
 require "posix"
 posix.utime("/var/log/test",atime,mtime)
=wait=
INPUT
*PID - process id
OUPUT
* 0 for success
* nil for failure
 
 require "posix"
 posix.wait(10)
 
----
If you are using this under linux also get 
=setenv=
INPUT
*Name- Name of Varible
*Value- What the Name varible should be set to
**overwrite- is this overwriting one already set
OUPUT
* 0 for sucess, nil for failure
 require "posix"
 posix.setenv("BAR","YES")
=unsetenv=
INPUT
*NAME - name of the varible to unset
OUPUT
* 0 for sucess, nil for failure
 require "posix"
 posix.unsetenv("BAR")
Category:Lua
Category:ACF