Revision as of 17:45, 16 November 2007

Lua Posix

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

http://swoolley.org/man.cgi/access

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.

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

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

INPUT

PATH - path to executable. Binary or script
ARgs - the arguments to pass to the PATH

OUTPUT

0 for success
nil for failure

--Coding Example
require "posix"
posix.exec("/bin/ls")
This seems to have the script exit. May need to use io.popen

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

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())

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

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

Hard Links INPUT

Oldpath-
Newpath-

'OUTPUT If you want output 0 sucess, nil errors

bar = require "posix"
bobo = bar.link("/etc/passwd", "testfile")
-- 0 for success, nil for errors

mkdir

INPUT

PATH-path to new dir

OUTPUT If you are looking for output-

0 for success
nil for failure

bar = require "posix"
bar.mkdir("/home/user/bobo")
--set the above to a variable to get output

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

http://swoolley.org/man.cgi/pathconf

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")

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
- 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   16877
mode    rwxr-xr-x
ino     4
size    6208

symlink

INPUT

OLDPATH - Path to the thing to be linked
NEWPATH - Link name and location

OUPUT

0 if sucess
nil for failure

require "posix"
posix.symlink("/etc/","/home/user/bar")

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

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

INPUT

NONE

OUPUT

Just like running uname on command line

require "posix"
print(posix.uname())

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")

@@ Line 302: / Line 302: @@
 ===Description===
-The '''glob'''() function searches for all  the  pathnames  matching  ''pattern''
+The '''glob'''() function searches for all the pathnames matching ''pattern'' according to the rules used by the shell.
-       according  to  the  rules  used  by  the shell.
 ===Return Value===