From be72d029b5f0ba73349e947210a96b6322420c38 Mon Sep 17 00:00:00 2001 From: Lisa Milne Date: Wed, 13 Dec 2023 19:18:50 +1000 Subject: [PATCH] documentation update --- readme-internals.txt | 28 ++++++++++++----- readme-libs.txt | 75 +++++++++++++++++++++++++++++++++----------- readme-programs.txt | 17 +++++----- 3 files changed, 85 insertions(+), 35 deletions(-) diff --git a/readme-internals.txt b/readme-internals.txt index 8dcdec4..62a7e98 100644 --- a/readme-internals.txt +++ b/readme-internals.txt @@ -16,6 +16,15 @@ This means that some areas are still very much a work in progress, but At its core, CLIte is made up of the follow parts: +The BIOS: + The basic input and output system of CLIte, the bios provides a simplified + api for reading input (keyboard, mouse, etc) and writing output ( + displaying text, playing sound) as well as uploading and downloading + files to and from the CLIte system. It provides a basic interface for + reading in keyboard input, as well as setting up the browser to provide + a VGA textmode style graphics display, ensuring CLIte and its programs + need never directly interact with HTML or raw events. + The Core: Effectively CLIte's 'kernel', this consists of functions needed to do basic tasks, such as loading files, loading scripts, safely running @@ -23,13 +32,18 @@ The Core: Most of this is either abstracted away to higher level functions, or otherwise need never be used by user-level programs. -The Terminal: - The terminal handles user input, and displays program output. Most of - which is abstracted away to standard io calls on /dev/tty, and even - further abstracted to standard io calls on the standard input, output, - and error filedescriptors that every program has. Additionally the - term library offers some advanced functionality which is subject to - change. +The Console: + The console provides an interface between the BIOS graphics system, and + CLIte's TTY subystem. Handling input and output to and from the currently + active TTY. The console is located at /dev/console + +The TTY: + The tty provides a Posix-compatible terminal interface, and is linked to + the process manager to maintain the controlling tty for each process + group. + Each process can interact directly with /dev/tty as a shortcut for its + own controlling tty, which can also be found at /dev/ttyN, where N is + the internal tty id. The VFS: (Virtual File Sytem) CLIte's virtual file system bares no relation to the file system of the diff --git a/readme-libs.txt b/readme-libs.txt index 58a5a0e..7c08351 100644 --- a/readme-libs.txt +++ b/readme-libs.txt @@ -13,7 +13,7 @@ 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 + 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: @@ -51,7 +51,7 @@ stdlib (libstd.so): io.include('stdlib') arguments, this is where the new process begins. function newProc(env,io) { - io.write('this is a new process!'); + stdio.write(io.stdout,'this is a new process!\n'); io.exit(0); } var pid = fork(env,io,newProc); @@ -92,10 +92,10 @@ stdlib (libstd.so): io.include('stdlib') Returns false on error. getuid() - Returns the numeric user id of the current user. + Returns the numeric user id of the current process. getgid() - Returns teh numeric group id of the current user. + Returns the numeric group id of the current process. getpwuid(uid) Returns a pw object, containing the passwd file data of the user @@ -103,7 +103,7 @@ stdlib (libstd.so): io.include('stdlib') getpwnam(name) Returns a pw object, containing the passwd file data of the user - who's user name = name + who's username = name getgrgid(gid) Returns a gr object, containing the group file data of the group @@ -111,7 +111,7 @@ stdlib (libstd.so): io.include('stdlib') getgrnam(name) Returns a gr object, containing the group file data of the group - who's group name = name + who's groupname = name clite (libclite.so): io.include('clite') Provides provides special functions used in CLIte. @@ -148,6 +148,23 @@ stdio (libio.so): io.include('stdio') 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 creat('path','-') creates a new file at path @@ -186,8 +203,7 @@ stdio (libio.so): io.include('stdio') 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. - \1 (start of header) followed by a special key - name (such as ArrowUp). + a special key value (such as escape). null if the tty cannot be read from. var c = stdio.read(fd); @@ -289,6 +305,20 @@ stdio (libio.so): io.include('stdio') st.size: file size, or 0 for non text files st.perms: the permissions string for the file, see chmod below. + 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: future integer mode (permission) 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 + st.perms: the permissions string for the file, see chmod below. + chmod('path','mode') fchmod(fd,'mode') Change a file's mode (permissions). @@ -334,25 +364,22 @@ stdio (libio.so): io.include('stdio') 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 terminal, equivalent to running `clear' from + Clears the current tty, equivalent to running `clear' from the shell. ttyctrl(func,v) Special function for setting and accessing CLIte-specific tty - data. Such as interacting directly with the form used for user - input. + 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. - term.ttyctrl('iset',string); // sets the current input value - var txt = term.ttyctrl('iget'); // gets the current input value - term.ttyctrl('prompt',string); // sets the current prompt text curses (libcurses.so): io.include('curses') provides an ncurses-like library, which functions for terminal management @@ -362,11 +389,10 @@ curses (libcurses.so): io.include('curses') A_BOLD 1 apply a bold face to text initscr() - Switches the terminal to an alternate framebuffer, and resets io - ready for curses library calls. + Sets up the tty in addressable mode, ready for use by curses. endwin() - Exits curses and switches the terminal back to the main frambuffer + Exits curses and switches the tty back to default mode. cbreak() Sets input to raw unbuffered mode, so that each key press is received @@ -409,13 +435,22 @@ curses (libcurses.so): io.include('curses') 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() + 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. @@ -437,5 +472,9 @@ time (libtime.so): io.include('time') 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. diff --git a/readme-programs.txt b/readme-programs.txt index 6c8b91b..597697c 100644 --- a/readme-programs.txt +++ b/readme-programs.txt @@ -31,10 +31,6 @@ The function in the second argument is roughly equivalent to main() in C. io.stdin file descriptor for standard input - Note that writing to stdout or stderr, when it is a tty, will - currently always print that output as a line, with a newline - appended. This may change in the future. - io.exit(value) exits the program, equivalent to the C exit() function. A program can also be exited by returning a non-null value from the 'main' function. @@ -57,7 +53,8 @@ Synchronous Program: Here's a "Hello World" as an example: clite.commands.load('hello',function(args,env,io) { - io.write("Hello World!"); + var stdio = io.include('stdio'); + stdio.printf("Hello World!\n"); return 0; } @@ -76,7 +73,7 @@ clite.commands.load('show',function(args,env,io) { // check there's a file to read from if (args.length != 2) { - io.error('Specify a file to read'); + stdio.write(io.stderr,'Specify a file to read\n'); return 1; // not asyncronous yet, so just return } @@ -88,7 +85,7 @@ clite.commands.load('show',function(args,env,io) { function fcb(fd) { if (!fd) { // print an error, exit the program, then end - io.error('could not open file'); + stdio.write(io.stderr,'could not open file\n'); io.exit(1); return; } @@ -101,20 +98,20 @@ clite.commands.load('show',function(args,env,io) { // check there's something there if (!data) { // print an error, exit the program, then end - io.error('could not read file'); + stdio.write(io.stderr,'could not read file\n'); io.exit(1); return; } // write to stdout - io.write(data); + stdio.write(io.stdout,data); // and exit successfully io.exit(0); } // open the file, and set the callback - var fd = stdio.open(file,fcb); + var fd = stdio.open(file,stdio.flags.O_RDONLY,fcb); // we don't want to exit the program yet, // so return null to let the system know that the