This section is a slightly modified version of the README file of the FUP 1.8 distribution.
All the built-in functions provided in the File Utilities Package used to require wizardly permissions, but since version 1.4 this is left to the database. Take a look to the file_handler file for an example of the implementation of permissions at the database level.
A simple $file_handler
wrapper is provided. A more complex version,
including a disk-quota system, is available too.
Additionally, file read/write operations are allowed only over the directory
subtree rooted at the 'base directory', called 'files' by default, and
execute operations are allowed only from the directory called 'bin' by default.
To achieve this, all paths are stripped of spaces, and then rejected if:
* denotes that the function is optional at compile time
Standard return errors:
To make the description easier, we'll assume we have the following files:
files/notes
/foo.text <-- this is a text file
/foox.test <-- this is a text file
/bar <-- this is an empty subdirectory
files/misc
We'll also assume that foo.text reads:
+--
| Copyright (c) 1994 Weizmann Institute. All rights reserved.
| This file documents the File Utilities Package developed and written by
| Jaime Prilusky and Gustavo Glusman, Weizmann Institute of Science, Israel.
| For questions, suggestions and comments, please send email to
| lsprilus@weizmann.weizmann.ac.il (Jaime Prilusky)
| Gustavo@bioinformatics.weizmann.ac.il (Gustavo Glusman)
+--
and foox.test reads:
+--
| line 1
| line 2
| end
+--
str fileversion()
Returns a string representing the version of the currently installed
FUP. The format is x.y, where x is the major release number and y is
the minor release number.
Example: fileversion() => "1.8"
num fileexists(str PATH, str NAME)
Returns 1 iff files/PATH/NAME exists, 0 otherwise.
Examples:
fileexists("notes","foo.text") => 1
fileexists("misc","foox.test") => 0
str fileerror()
Returns a string describing the UNIX error message,
which reports the last error encountered during a call to a system or
library function.
Examples:
fileerror() => "Error 0" (No error)
fileerror() => "Interrupted system call"
fileerror() => "No such file or directory"
list fileinfo(str PATH, str NAME)
Returns a list with assorted system information about the relevant file/directory.
Examples:
fileinfo("notes","") => {512, "dir", "755", "lsprilus", "staff",
788541296, 788346820, 788346820}
fileinfo("notes","foo.text")
=> {376, "reg", "644", "lsprilus", "staff", 788541674, 788541674, 788541674}
The information provided is: size, type, mode, owner, group, file last access time, file last modify time, and file last change time. Check 'man stat' for more info.
str filechmod(str PATH, str NAME, str MODE)
Sets the mode of the relevant file/directory.
Examples:
filechmod("notes","foo.text","bleh") => "644"
(This just returns the existing value.)
filechmod("notes","foo.text","640") => "640"
(It returns the new value.)
list filelist(str PATH [, str NAME])
Returns the list of files and
subdirectories in files/PATH, not recursively. If NAME is provided,
only files matching NAME as regexp will be returned. All existing
subdirectories will be returned in any case.
Examples:
filelist("") => {{},{"notes","misc"}}
filelist("notes") => {{"foo.text","foox.test"},{"bar"}}
filelist("notes/bar") => {{},{}}
filelist("notes","oo.%.") => {{"foox.test"},{"bar"}}
filelist("misc") => {{},{}}
num filelength(str PATH, str NAME)
Returns the number of lines of files/PATH/NAME.
Example:
filelength("notes","foo.text") => 6
num filesize(str PATH, str NAME)
Returns the number of characters of files/PATH/NAME.
Example: filesize("notes","foo.text") => 388
num filedelete(str PATH, str NAME)
Irretrievably deletes files/PATH/NAME.
Example: filedelete("notes","foo.text") => 1 if successful.
num filemkdir(str PATH, str NAME)
Creates a new directory: files/PATH/NAME.
Example: filemkdir("notes","mydir") => 1 if successful.
num filermdir(str PATH, str NAME)
Removes the directory: files/PATH/NAME, if it's empty.
Example:
filermdir("notes","mydir") => 1 if successful.
filermdir("notes","mydir") => E_PERM if unsuccessful.
Hint: use fileerror() to find the reason for failure.
num filerename(str PATH, str OLDNAME, str NEWNAME)
Renames files/PATH/OLDNAME to NEWNAME.
Example:
filerename("notes","foo.text","blah.blah") => 1 if successful.
list fileread(str PATH, str NAME [, num START [, num END]])
Returns a list of strings which represent lines read from files/PATH/NAME, from START to END, which default to the beginning and the end of the file respectively.
Examples:
fileread("notes","foox.test") => {"line 1","line 2","end"}
fileread("notes","foox.test",2) => {"line 2","end"}
fileread("notes","foox.test",2,2) => {"line 2"}
fileread("notes","foox.test",3,2) => {}
fileread("notes","foox.test",5,6) => {}
num fileappend(str PATH, str NAME, list TEXT)
Appends TEXT to
files/PATH/NAME. Creates the file if it didn't exist previously.
Examples:
fileappend("notes","foox.test",{"hehe","hoho"}) => 1 if successful.
num filewrite(str PATH, str NAME, list TEXT [, num START [, num END]])
Writes TEXT on files/PATH/NAME. Creates the file if it didn't exist previously. Assuming LENGTH is the number of lines in TEXT:
Examples: (the operations are not sequential. The file starts as: {"line 1","line 2","end"}) Operation File contents after filewrite("notes","foox.test",{"test"}) {"test"} filewrite("notes","foox.test",{"te","st"},2) {"line 1","te","st"} filewrite("notes","foox.test",{"te","st"},2,2) {"line 1","te","st","end"} filewrite("notes","foox.test",{"test"},2,3) {"line 1","test"} filewrite("notes","foox.test",{},2,2) {"line 1","end"}
list filegrep(str PATH, str NAME, str REGEXP [, str SWITCHES])
Returns a list of strings and line numbers, which represent lines read from files/PATH/NAME, and that match REGEXP. SWITCHES defaults to "s".
Examples:
filegrep("notes","foo.text","Weizmann")
=> {{" Copyright (c) 1994
Weizmann Institute. All rights reserved.", " Jaime Prilusky and
Gustavo Glusman, Weizmann Institute of Science, Israel.", "
lsprilus@weizmann.weizmann.ac.il (Jaime Prilusky)", "
Gustavo@bioinformatics.weizmann.ac.il (Gustavo Glusman)"},
{}}
filegrep("notes","foo.text","Weizmann","n")
=> {{}, {1, 3, 5, 6}}
filegrep("notes","foo.text","Weizmann","ns")
=> {{" Copyright (c)
1994 Weizmann Institute. All rights reserved.", " Jaime Prilusky
and Gustavo Glusman, Weizmann Institute of Science, Israel.", "
lsprilus@weizmann.weizmann.ac.il (Jaime Prilusky)", "
Gustavo@bioinformatics.weizmann.ac.il (Gustavo Glusman)"},
{1, 3, 5, 6}}
filegrep("notes","foo.text","Weizmann","vn") => {{},{2, 4, 7, 8}}
list fileextract(str PATH, str NAME, str REGEXP1, str REGEXP2 [, str REGEXP3])
Returns a list of starts and ends of sections of files/PATH/NAME, that fulfill the following requirements:
Examples: fileextract("notes","foo.text","a","x") => {{}, {}} (there isn't a line with an "x") fileextract("notes","foo.text","Copy","email") => {{1}, {4}} (the section from line 1 to line 4 fits) fileextract("notes","foo.text","a","b") => {{1, 3}, {2, 6}} (the sections from line 1 to line 2 and from line 3 to line 6 fit) fileextract("notes","foo.text","a","b","est") => {{3}, {6}} (of these, only the section from 3 to 6 has a line that matches "est")
num filerun(str EXECUTABLE [, list {str PATH1, str INFILE} [, list {str PATH2, str OUTFILE} [, str/list PARAMETER]*]])
Checks a whole
set of security issues, including the requirement that 'EXECUTABLE'
be found in the 'bin' directory. If all is ok, it issues a system
call equivalent to the Unix command:
cat PATH1/INFILE | EXECUTABLE PARAMETER(s) > PATH2/OUTFILE
Examples:
filerun("cal")
filerun("grep",{},{"temp","output"},"wizard",{"notes","*"})
filerun("lpr",{"notes","info"},{},"-Plaser")