str = fish(path|fd)
str = stat(path|fd)
num = fd(path|fd [,redirect]])
The fish() ("File IS Here") function returns the absolute path to the file system object at path, or null if that doesn't exist (or any other errors are detected). If the argument is an FD it returns true on success or null if the argument is not a valid file descriptor (below). This function does not access or create any Fing (internal "File IN General" objects used by JSUS for I/O operations). Instead, it internally stores the underlying file system "status" for the object, i.e. the C/C++ structure returned by a stat() system call (hence, stat() is provided as an alias). The contents of this structure may be inspected with the fxxx() functions listed below. Because this temporary structure may be overwritten by subsequent JSUS calls, these inspector functions should be invoked immediately after the fish():
num = fmajor(); Major device number of this file;
num = fminor(); Minor device number of this file;
num = frmajor(); Major device number of device this special file represents;
num = frminor(); Minor device number of device this special file represents;
num = fnode(); iNode number of this file;
num = fhard(); Returns the number of hard links to the file system object;
num = fuid(); Returns the user id (uid) of the owner of the file object;
num = fgid(); Returns the group id (gid) of the owner of the file object;
num = fsize(); Returns the size (in bytes) of the file system object;
num = fbest(); Preferred, or optimum block size for writing to this device;
num = fblocks(); Allocated 512 byte blocks; less than fsize()/512 if any holes;
num = fatime(); System time of last access to file (often completely useless);
num = fmtime(); System time of last modification to file or directory contents;
num = fctime(); System time of last change to the inode super information;
str = ftype([max]); Returns a string with a word describing the type of the object (file, directory, pipe, socket, block, character or link). The optional max argument limits the number of characters returned. Since all responses are unique in their first character, ftype(1) returns a single character which can be easily tested to determine file type.
t/f = fmode([emode[,rmode]]); Returns true or null, depending on whether all specified modes are available to the effective or the real user. If neither argument is given, returns the full mode value from the stat(). The effective (and optional real) user modes are specified as up to 2 octal digits — the first gives SUID, SGID and STICKY bits, the second gives the required permissions (tested against the file object's combined owner, group and world permissions). All modes must be present in order to return true; to get just the rmode, specify zero for the emode.
If the preceding fish() call was for a non-existent file, all of these test functions return null. However, if the path points to a dangling symbolic link (i.e. one which cannot be resolved) these functions return status information for the link itself and ftype() returns "link". Otherwise, if a target symbolic link is successfully resolved, they return status information for the derefernced file system object.
As with all JSUS functions, a file path beginning with "./" or "../" or "~/" is expanded to replace the characters before the slash with, respectively, the current working directory, the parent directory or the user's home directory. A leading ~user/ is also expanded to the home directory of another user, but working directories are not expanded. Unlike other shells, a tilde by itself is not expanded but fish('~/') produces exactly the same result — the absolute path to the user's home directory.
The fd() function returns the system "File Descriptor" (FD) property of the internal Fing object for the file at the specified path. If no such file has yet been accessed fd() simply returns a null (which is not considered an error). In most modern operating systems "File Descriptors" are simple, positive integers which are used to identify "open" files on which low-level I/O operations may be performed. By convention, the values 0, 1 and 2 are used to refer to stdin, stdout and stderr (the three standard files usually available in all program processes). Other than this, the integer value has no useful meaning. For completeness, it should also be noted that the same value may be used in different processes to refer to different file system objects but, in any given process, a particular value refers to only one file. However, multiple different values may all refer to the same file object, both in the same and different processes, and each may represent a different state for the file itself (for example, file position).
With few exceptions, wherever a JSUS function permits a path string argument an integer FD value may be coded instead — including fish() and even fd() itself. If a Fing already exists, the file may be operated on using either the path or the FD, interchangeably. Otherwise, if any JSUS function constructs a new Fing, the file may only be referenced by its descriptor. The fd() function is rarely needed in practice, because most I/O is performed using the file path. It's primary use is for passing open files when jump()ing from one program to another (within the same process, but possibly in a different language). The first program uses fd() to obtain the FD of a file it is already using. This is then passed as an argument to the second program, which calls fish(fd) to determine the status of the file, before attempting any I/O. In the second program, all I/O functions should specify the FD (because the path cannot be easily or accurately determined).
If fd() is called with a single integer FD argument, a check is made to ensure the FD is valid and opened and, if so, the FD is returned as a number. If not, a null is returned but this is not considered an error. This is an alternative method of checking the validity of an FD by comparing the result of the call with it's argument, for example:
if (fd(100) !== 100) validFD = false;
A second integer argument may be used to redirect the first argument to a new and different FD, typically one of the standard files (0, 1 or 2). The semantics (and possible errors) are those of the underlying dup2() system call from the C run time library. If both arguments refer to the same FD, that number is returned normally without any further action. Otherwise, the second FD is closed (if already open) and the first argument's FD is duplicated to the second FD value, effectively redirecting the first argument path or FD to the second. Unlike the underlying dup2(), however, the fd() function also closes the first file argument and flushes it's buffers.