CLIte/readme-libs.txt

CLIte libraries:

System libraries may be loaded into a program for use of their API using the
 io.include() function:

var stdio = io.include('stdio');

 This returns a reference to the library which can be stored in a variable as
 seen above. Calls to library functions can then be made using that reference:

var fd = stdio.open('/path/to/file',stdio.flags.O_RDONLY);

 There is no need to name the variable the same as the library name, however
 this is considered good practice.
 A library's 'header' name, as used in include() is not the same as its
 file name /lib/lib*.so. For instance, for the standard io library, you
 would include 'stdio' but the filename is libio.so

The libraries, and their API functions are listed below:

stdlib (libstd.so): io.include('stdlib')
 Provides a growing standard unix-like library.

 basename('path')
	 returns the base name of a file path:
	 '/usr/home/guest/file.txt' -> 'file.txt'

 dirname('path')
	 returns the directory name of a file path:
	 '/usr/home/guest/file.txt' -> '/usr/home/guest'

 uname()
	 returns an object containing system information:
	 {
		sysname:'CLIte',	// system name, always 'CLIte'
		nodename:'localhost',	// network hostname
		release:'0.1...',	// contains the current CLIte version as stored in clite.state.version
		version:'0.1...',	// same as release
		machine:navigator.userAgent // contains the browser user agent string
	}

	nodename is either the website domain, or 'localhost' if loaded
	 without a webserver. This allows programs to test if the system
	 is running locally or not (example is `cat -l' which does not
	 print unloaded files if running without a webserver).

 fork(env,io,call)
	 Creates a new process, with environment and io data passed to it.
	 Returns the pid of the new process, or 0 on failure.
	 call should be a function that accepts the env and io as
	  arguments, this is where the new process begins.

	 function newProc(env,io) {
		stdio.write(io.stdout,'this is a new process!\n');
		io.exit(0);
	 }
	 var pid = fork(env,io,newProc);

 exec(path,args,env,io)
	 Executes a new program, replacing the current one.
	 Returns 0 on success, non-zero on failure.
	 Unlike typical unix exec(), this always returns. On success the
	  original program should do nothing more, including not exiting.

	 path is the fully resolved file path of the program to be
	  executed, such as '/bin/ls'.
	 args is the argument array created by passing a command line to
	  strToArgs, see above.
	 env and io, are the current environment and io data.

	 var command = "ls -l";
	 var args = stdlib.strToArgs(command);
	 var path = stdlib.resolvePath(args[0],'/bin');
	 var r = stdlib.exec(path,args,env,io);
	 if (r == 0)
		return;

 wait(cb)
	Calls cb(pid,exit_status) once any child of the current process has exited.
	 Calls immediately if the are no child processes.
	Returns false on error.

 waitpid(pid,cb)
	Calls cb(pid,exit_status) when the process with id pid has exited. Calls
	 immediately if the process does not exist.
	If pid is less than 0, functions like wait(cb)
	Returns false on error.

 waitall(cb)
	Calls cb(pid,exit_status) once all child processes of the current process
	 group have exited. Calls immediately if the are no child processes.
	Returns false on error.

 getuid()
	Returns the (real) numeric user id of the current process.

 geteuid()
	Returns the effective numeric user id of the current process.

 getgid()
	Returns the (real) numeric group id of the current process.

 getegid()
	Returns the effective numeric group id of the current process.

 getpwuid(uid)
	Returns a pw object, containing the passwd file data of the user
	 who's numeric user id = uid

 getpwnam(name)
	Returns a pw object, containing the passwd file data of the user
	 who's username = name

 setpwent()
 getpwent()
 endpwent()
	Used for iterating over passwd file entries:
	let pw = null;
	setpwent();
	while ((pw = getpwent()) != null) {
		stdio.printf('username: %s\n',pw.pw_name);
	}
	endpwent();

 getgrgid(gid)
	Returns a gr object, containing the group file data of the group
	 who's numeric group id = gid

 getgrnam(name)
	Returns a gr object, containing the group file data of the group
	 who's groupname = name

 setgrent()
 getgrent()
 endgrent()
	Used for iterating over group file entries:
	let gr = null;
	setgrent();
	while ((gr = getgrent()) != null) {
		stdio.printf('group name: %s\n',gr.gr_name);
	}
	endgrent();

clite (libclite.so): io.include('clite')
 Provides provides special functions used in CLIte.

 resolvePath('path','base')
	Resolves a relative path to a full path, using the present
	 working directory or 'base':

	clite.resolvePath('file.txt') -> '/usr/home/guest/file.txt'
	clite.resolvePath('file.txt','/etc') -> '/etc/file.txt'
	clite.resolvePath('~/../file.txt') -> '/usr/home/file.txt'

 strToArgs('string')
	Splits a string into an array of arguments for passing to
	 exec(), supports quotes and so on:

	clite.strToArgs('ls -l /var') -> ['ls','-l','var']


 strmode(mode)
	returns a string representation of a file mode such as '-rw-rw-r--';

 modestr('string')
	returns a file mode generated from a permissions string.

	The permission string is a 9 or 10 character string describing the
	 file permissions. The optional first character describes the
	 file type, and cannot be changed by calls to chmod(). Attempting
	 to change the first character will not cause the function to
	 fail, but only the permissions will be changed.

	 10 character string: -rwxrwxrwx
	 9 character string: rwxrwxrwx

	After the optional first character, the mode string is comprised
	 of 3 sets of permissions for Read, Write, and eXecute, one each
	 for the user, group, and others.

	-		file type
	 rwx		permissions for the file's owner
	    rwx		permissions for users in the file's group
	       rwx	permissions for other users

	Replacing any of the permissions with a dash '-' indicate the
	 permission is not set:

	-rwxr-xr--
	The user has all permissions, the group has read and execute
	 permissions, others have only read permissions.

	setuid, setgid are represented by an 's' in the respective
	 execute field:

	-rwsr-sr-x
	The file is executable by all, and the new process will run with
	 uid and gid set to the file's owner and group ids.

	Sticky bits on directories are represented by a 't' in the other
	 execute field:

	drwxrwxrwt
	The directory is readable, writable, and searchable by all, but
	 only the file's owner may delete a file in the directory.

 cookienotice()
	Prints a standard cookie notice to stdout, because hurrah for
	 the web.
 getcookiestate()
	Get whether the current user has accepted cookies
	 true - accepted
	 false - rejected
	 null - user has not accepted or rejected cookies, default to
	  rejected

 setcookiestate(bool)
	Set whether the user has accepted cookies or not (true/false)

stdio (libio.so): io.include('stdio')
 Provides access to io functions and types for file access

 stdio.types:
  object for mapping values of stat.type:
	FT_UNKNOWN:	0 Unknown file type
	FT_TEXT:	1 Plain text file
	FT_BINARY:	2 Binary file, likely a javascript function
	FT_DIR:		3 Directory
	FT_LINK:	4 Symbolic link
	FT_DEV:		5 Device
	FT_REMOTE:	6 Unloaded remote data (will change after loading)
	FT_SCRIPT:	7 Plain text file beginning with #!
	FT_IMAGE:	8 Image file, specifically a javascript Image object

 stdio.flags:
  object containing flags for use in io functions
	O_EXEC:		open for executing only, no op on directories
	O_RDONLY:	open for reading only
	O_RDWR:		open for reading and writing
	O_SEARCH:	open for directory search only, no op on non-directories
	O_WRONLY:	open for writing only
	O_APPEND:	append to the file, sets pos to content.length, requires O_RDONLY or O_RDWR
	O_CLOEXEC:	close on exec
	O_CREAT:	create if file does not exist
	O_DIRECTORY:	only open if directory
	O_EXCL:		if O_CREAT is set, fail if file exists
	O_NOCTTY:	no op
	O_NOFOLLOW:	if file is a symlink, don't follow it
	AT_SYMLINK_NOFOLLOW:	if file is a symlink, don't follow it
	O_NONBLOCK:	no callbacks, return immediately
	O_SYNC:		write immediately (may fail on remote data)
	O_TRUNC:	set file size to 0 before writing, requires O_RDWR or O_WRONLY
	O_TTY_INIT:	no op

 stdio.modes:
  object containing values for creating file modes (permissions)
		These values may be combined via bitwise OR to create the file permission
	S_IRWXU:	Read, write, execute/search by owner.
	S_IRUSR:	Read permission, owner.
	S_IWUSR:	Write permission, owner.
	S_IXUSR:	Execute/search permission, owner.
	S_IRWXG:	Read, write, execute/search by group.
	S_IRGRP:	Read permission, group.
	S_IWGRP:	Write permission, group.
	S_IXGRP:	Execute/search permission, group.
	S_IRWXO:	Read, write, execute/search by others.
	S_IROTH:	Read permission, others.
	S_IWOTH:	Write permission, others.
	S_IXOTH:	Execute/search permission, others.
	S_ISUID:	Set-user-ID on execution.
	S_ISGID:	Set-group-ID on execution.
	S_ISVTX:	On directories, restricted deletion flag.
		A mode may contain one of these values to indicate the file type
	S_IFMT:		format (file type) mask
	S_IFBLK:	Block special
	S_IFCHR:	Character special
	S_IFIFO:	FIFO special
	S_IFREG:	Regular file
	S_IFDIR:	Directory
	S_IFLNK:	Symbolic link
	S_IFSOCK:	Socket

 creat('path','-')
	creates a new file at path
	returns true on success

 open('path',flags,callback)
	Open the file at path, returns a file descriptor.
	 On error returns null, and calls callback(null) if set.
	If callback is set, will call the function at callback with the
	 file descriptor, this allows remote data to be loaded for the
	 file before beginning read or write operations.
	If callback is false or not set, open will return directly, without loading
	 remote data. this is equivalent to setting stdio.flags.O_SYNC in flags.
	flags is a bitwise or group of flags from stdio.flags.O_*. Consisting
	 of at least one mode (O_RDONLY/O_RDWR/O_WRONLY/O_SEARCH/O_EXEC),
	 and any other flag or flags.

	 var fd = stdio.open('path',stdio.flags.O_RDONLY|stdio.flags.O_SYNC); // opens the file without loading data
	 var fd = stdio.open('path',stdio.flags.O_RDONLY,callback); // calls callback(fd) when data is loaded
	 var fd = stdio.open('path',stdio.flags.O_RDONLY|stdio.flags.O_NOFOLLOW,callback); // as above, but will not follow a link
	 var fd = stdio.open('path'); // fails without a valid mode (O_RDONLY/O_RDWR/O_WRONLY/O_SEARCH/O_EXEC)

 close(fd)
	Closes a file opened with open()

		stdio.close(fd);

 read(fd,callback)
	Reads a single character or keystroke from a file.
	callback is an optional callback function, used soley for
	 asynchronously reading from a tty.
	Returns null if there is no data to read.

	When reading from a regular file, will return a single character.
	When reading from a tty:
		Returns true on success or false on failure.
		Calls callback() and passes as an argument either:
			A full line of text as entered by the user.
			a special key value (such as escape).
			null if the tty cannot be read from.

	var c = stdio.read(fd);

 readLine(fd,callback)
	Reads a line from a file, up to the next newline, or end of file.
	Returns null if there is no data to read.

	When reading from a tty, functions the same as read().

	var line = stdio.readLine(fd);

 readAll(fd)
	Returns the entire content of a file.
	Returns null if there is no data to read.
	Works only on regular files (and some non-tty devices).

	var data = stdio.readAll(fd);

 write(fd,data)
	Write data to a file.
	Returns true on success.

	if (stdio.write(fd,'string')) {
		// it worked
	}else{
		// it failed
	}

 ftruncate(fd,length)
 truncate('path',length)
	Truncates a file's size to no more than length.
	Does not increase a file's size to length.
	Returns true on success.

	var result = stdio.ftruncate(fd,10);
	var result = stdio.truncate('/usr/home/guest/file.txt',10);

 seek(fd,pos)
	Moves the read/write position of an open file to pos.
	If pos is less than 0, then returns the current position without
	 changing, otherwise returns the new position.
	pos is always relative to the start of the file. When a file is
	 first opened, pos will be set to the start of the file.
	To set the position to the end of a file, first get the file size
	using stat() or fstat().

	var p = stdio.seek(fd,10);

 remove('path')
	Deletes a file or directory.
	Returns true on success.
	To delete a directory, the directory must be empty.

	if (stdio.remove('/usr/home/guest/file.txt'))
		// success!

 link('path','target')
	Creates a new symbolic link at 'path' which points to 'target'.
	'target' must exist.
	If 'path' exists, and is already a link, will update the link.
	Returns true on success.

	if (stdio.link('/usr/home/guest/logfile','/vr/logs'))
		// success!

 stat('path')
 lstat('path')
 fstatat(fd,flags)
	Returns a stat object with infomation about a file.
	Returns null on error.
	Editing the returned object does not change anything for the
	 actual file, it just means your stat object is now wrong.

	fstatat returns data for the file descriptor fd.
		flags may be either 0 or stdio.flags.AT_SYMLINK_NOFOLLOW

	stat returns data for the file specified by path, or if the file
	 is a symbolic link, for the file the link points to.
	 equivalent to:
		var fd = stdio.open('path',stdio.flags.O_RDONLY|stdio.flags.O_NOFOLLOW);
		var st = stdio.fstatat(fd,stdio.flags.AT_SYMLINK_NOFOLLOW);

	lstat returns data for the file specified by path, or if the file
	 is a symbolic link, for the link itself.
	 equivalent to:
		var fd = stdio.open('path',stdio.flags.O_RDONLY);
		var st = stdio.fstatat(fd,0);

	var st = stdio.stat('/usr/home/guest/file.txt');
	var st = stdio.lstat('/usr/home/guest/file.txt');
	var st = stdio.fstatat(fd,0);

	Stat object contents:
	st.name:	string containing the file namefd.node.name,
	st.type:	file type identifier, see stdio.types above for more info
	st.st_dev:	device id, always 0
	st.st_ino:	file serial number, always 0
	st.st_mode:	integer mode (permissions) value
	st.st_nlink:	number of hard links to the file, always 0
	st.st_uid:	numeric id of the file owner
	st.st_gid:	numeric id of the file group
	st.st_size:	file size, or 0 for non-text files
	st.st_atim:	timeval object, the file's last access time
	st.st_mtim:	timeval object, the file's last modify time
	st.st_ctim:	timeval object, the file's last change time

 chmod('path',mode)
 fchmod(fd,mode)
	Change a file's mode (permissions).
	Returns true on success.

	mode is an integer value made from a bitwise OR of values in
	 stdio.modes. Alternatively, the mode can be generated by passing
	 a permissions string to clite.modestr().

 isatty(fd)
	returns true if fd refers to a tty.

 vfprintf(fd,format,args)
	Print formatted text to the file at fd.
	args is an array of arguments for inserting into the formatted
	 output.
	Returns true on success.

 fprintf(fd,format,...)
	Similar to vfprintf, but accepts the format arguments as a
	 variable number of arguments to the function itself.

 printf(fmt,...)
	Equivalent to fprintf(io.stdout,fmt,...);


term (libterm.so): io.include('term')
 Provides access to raw terminal and tty functions.

 clear()
	Clears the current tty, equivalent to running `clear' from
	 the shell.

 ttyctrl(func,v)
	Special function for setting and accessing CLIte-specific tty
	 data, as well as providing special tty mode calls.
	func is a string containing the intended function.
	v is the value to set.
	Many functions of this are abstracted away in the curses library.
	Returns either the requested data, or false on error.


curses (libcurses.so): io.include('curses')
 provides an ncurses-like library, which functions for terminal management

 curses.types:
	A_NULL	0 NO OP / do nothing
	A_BOLD	1 apply a bold face to text

 initscr()
	Sets up the tty in addressable mode, ready for use by curses.

 endwin()
	Exits curses and switches the tty back to default mode.

 cbreak()
	Sets input to raw unbuffered mode, so that each key press is received
	 individually, rather than the usual line buffering.
 nocbreak()
	Returns the input to line buffered mode.

 clear()
	Clears the framebuffer.

 echo()
	Causes key strokes to be echoed to the terminal (default)
 noecho()
	Causes key strokes to not be echoed to the terminal

 printw(fmt)
	A printf-like function for writing to the alternate framebuffer

 getch(cb)
	Receive input from stdin

 refresh()
	No op function for ncurses compatibility

 attron(a)
	Enable attribute 'a' for future input, see curses.types

 attroff(a)
	Disable attribute 'a' for future input, see curses.types

 getmaxx()
	Returns the width of the frambuffer in characters.

 getmaxy()
	Returns the height of the framebuffer in characters/lines.

 getmaxyx(ptry,ptrx)
	Gets the width and height of the framebuffer, as per getmaxx()
	 and getmaxy(), but writes the results to the pointers passed
	 as arguments. See clite.ptr*() functions for how to create,
	 read, and write with pointers.

 move(y,x)
	Moves the cursor to the provided coordinates, where the next text
	 will be printed to.


time (libtime.so): io.include('time')
	Provides functions for interacting with system time.

 asctime(timeptr)
	Converts a time Object, as returned by gmtime() or localtime(),
	 into a human readable string.

 ctime(time)
	Converts a time, as returned by time(), into a human readable
	 string.

 gmtime(time)
	Converts an integer containing the number of seconds since epoch
	 into a time Object.
		tm_sec:0,	// seconds (0-60)
		tm_min:0,	// minutes (0-59)
		tm_hour:0,	// hour (0-23)
		tm_mday:0,	// day of month (0-31)
		tm_mon:0,	// month of year (0-11)
		tm_year:0,	// years since 1900
		tm_wday:0,	// day of week (0-6, sunday = 0)
		tm_yday:0,	// day of year (0-365)
		tm_isdst:0	// 1 if daylight savings

 localtime(time)
	Converts an integer containing the number of seconds since epoch
	 into a time Object, taking into account the current time zone.

 mktime(timeptr)
	Converts a time Object into an integer containing the number of
	 seconds since epoch.

 strftime(fmt,timeptr)
	Converts a time Object into a human readable string, using the
	 specified format.

 time()
	Returns the current time, as seconds since epoch.

auth (libauth.so): io.include('auth')
	Provides function for interacting with user accounts and groups.

 setpwentry(pw)
	Creates a new entry in the passwd file, creating a new account,
	 see getpw*() for details on the pw object.
	Returns true on success.

 removepw(uid)
	Removes the passwd file entry for the user with id uid, deleting
	 the account.
	Returns true on success.

 setgrentry(gr)
	Creates a new entry in the group file, creating a new group, see
	 getgr*() for details on the gr object.
	Returns true on success.

 removegr(gid)
	Removes the group file entry for the group with id gid, deleting
	 the group.
	Returns true on success.

 setpassuid(uid, pass)
	Sets the password for the user account with id uid.
	Returns true on success.

 setpassnam(name, pass)
	Sets the password for the user account with username name.
	Returns true on success.

 checkpassuid(uid, pass)
	Check if a password is the correct password for the user account
	 with id uid.
	Returns true on success.

 checkpassnam(name, pass)
	Check if a password is the correct password for the user account
	 with the username name.
	Returns true on success.