NAME
	9lua
SYNOPSIS
	
DESCRIPTION
	In the following description, syntax is as follows:
	(a) enclosed strings by '[' and ']' such as
		read(fd [,size])
	are optional parts.
	(b) '|' such as
		dirstat(name | fd)
	are selection, which means
		both dirstat(name) and dirstat(fd) are OK (with different meaning)

	fd = p9.open(name [,mode])
	name: path to file
	mode: "r", "w", "rw", "wr", "rwt", the default "r"

	fd = p9.create(name [,mode])
	name: path to file
	mode:
	"r": read only
	"w": write (not truncated)
	"rw": read/write (not truncated)
	mode default: "w"
	return: the file descriptor
	the created file permission is set to 0666

	p9.read(fd [,size])
	fd: file descriptor returned by open()
	size: buffer size in reading
	size default: read all content
	return: read content
	if size is given, p9.read() behaved same as Plan9 read()

	p9.write(fd,string)
	fd: file descriptor returned by open()
	string: content to write
	return: byte size wrote

	p9.seek(fd [,offset [,how]])
	fd: file descriptor returned by open()
	offset:	integer. the default is 0
	how: "set","cur","end". the default is "set"
	return: new offset

	p9.close(fd)
	fd: file descriptor returned by open()
	return: nil
	same as Plan9 close()

	p9.bind(name,old [,how])
	name: path to file
	old: path to the target, look system manual for the meaning
	how: "a","b","c","ac","bc"
	return: true or false
	same ad Plan9 command bind
	look bind(2) for details of the how flags.

	p9.unmount([name,] old)
	name,old: path to file
	return: true or false
	name may be absent, then old is assumed
	same as Plan9 command unmount

	p9.dirstat(name | fd)
	same as Plan9 C function dirstat(path) or dirfstat(fd)
	name: path to file
	fd: fd: file descriptor.
	return: stat structure
	the structure is a Lua table with keys:
		"type","dev","qid","mode","atime","mtime","length","name","uid","gid","muid"
	note that
	- "qid" is modified from original one,
	- "mode" is a string expression of octal

	p9.dirwstat(name, stat)
	name: path to file
	stat: table returned by dirstat()
	return: nil
	stat is a Lua table with mode, mtime, uid, gid
	for example stat={mode="755", gid="glenda"}
	note: dirwstat() is only be examined for changing "mode","uid","gid","mtime"
	bug: we should return the result status

	p9.readdir(name [,flag]) -- returns table
	name: path to directory
	flag: true or false, the default is false
	if false, the returnd table contains only true or false for each name,
	which denotes dir or not.
	if true, the returnd table contains dir attributes for the names
	return: the stat info of all files in the directory
	the results are sorted by file names
	look MAN_9LUA for details.

	p9.mkdir(name [,mode])
	name: dir name to be created
	return: true
	mode default is "777". note that created dir mode follows the mode of parent dir.
	look mkdir(1) for "mode"
	note: mkdir() cause error in fail



	p9.bit(n,op,m)
	NB: now Lua support bit wise operation. p9.bit is gone.
	
	p9.popen(cmdlist)
	cmdlist: rc command list.
	return: file descriptor
	note: Plan9 pipe is bidirectional, thus we can read/write to the file
	the usage example is
		f = p9.popen("ps")
		s = p9.read(f)
		p9.close(f)
		print(s)

	p9.fork()
	return: pid (process id)
	NB: the fork() in this version is posix.
	the usage example is
		pid = p9.fork()
		if pid > 0 then -- parent
			print("I am parent. My child is "..pid)
			print("waiting child to finish")
			s = p9.wait(pid)
			print("msg="..s)
		else
			print("I am child. I don't know my parent")
			p9.sleep(3)
		end		

	p9.wait(pid)
	pid: process id
	return: user_mode_time,system_time,elapsed_time
		all in units of milliseconds

	p9.alarm(timeout)
	timeout: time for an alarm note in unit of seconds
	(internally Plan9 alarm is used)
	return: nil
	now timeout is extended to allow lua number

	p9.sleep(time)
	time: sleeping time in unit of seconds
	(internally Plan9 sleep is used)
	return: nil
	now secs is extended to allow lua number such as 0.1 (100ms)

	getpid()
	return: current process ID
	look getpid(2)


NOTE
	Lua's file name stands on loose manner.
	For example, io.open(0,"r") is same as io.open("0","r").
	Even an expression such as io.open(1/3,"w") is allowed,
	which creates a file named "0.33333333333333".
	I dislike such looseness.
	In supporting p9 library, I discarded looseness in file names. Now
		p9.open(0,"r")		--> error
		p9.dirstat("0")		--> OK. here "0" is a file name
		p9.dirstat(0)		--> OK. 0 is fd, this is dirfstat(0) in C lang.