external next up previous contents index
Next: 15.2 [TECFAMOO] The file_handler Up: The File Utilities Package Previous: The File Utilities Package

15.1 FUP server builtin functions

   

This section is a slightly modified version of the README file of the FUP 1.8 distribution.

Security:

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:

List of primitives provided:

  * denotes that the function is optional at compile time

A: Modify files:
filewrite (gif), fileappend (gif), filedelete (gif), filerename (gif), *filechmod (gif), filemkdir (gif), filermdir (gif)

B: Gather information:
fileversion (gif), fileread (gif), fileexists (gif), filelength (gif), filesize (gif), filelist (gif), filegrep (gif), fileextract (gif), fileinfo (gif), fileerror (gif)

C: Execute commands:
*filerun (gif)

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
+--

fileversion
  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"

fileexists
  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

fileerror
  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"

fileinfo
  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.

filechmod
  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.)

filelist
  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") => {{},{}}

filelength
  num filelength(str PATH, str NAME)

Returns the number of lines of files/PATH/NAME.

Example: 
filelength("notes","foo.text") => 6

filesize
  num filesize(str PATH, str NAME)

Returns the number of characters of files/PATH/NAME.

Example: filesize("notes","foo.text") => 388

filedelete
  num filedelete(str PATH, str NAME)

Irretrievably deletes files/PATH/NAME.

Example: filedelete("notes","foo.text") => 1 if successful.

filemkdir
  num filemkdir(str PATH, str NAME)

Creates a new directory: files/PATH/NAME.

Example: filemkdir("notes","mydir") => 1 if  successful.

filermdir
  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.

filerename
  num filerename(str PATH, str OLDNAME, str NEWNAME)

Renames files/PATH/OLDNAME to NEWNAME.

Example:
  filerename("notes","foo.text","blah.blah") => 1 if successful.

fileread
  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) => {}

fileappend
  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.

filewrite
  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"}

filegrep
  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}}

fileextract
  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")

filerun
  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")


next up previous contents index external
Next: 15.2 [TECFAMOO] The file_handler Up: The File Utilities Package Previous: The File Utilities Package

Daniel K. Schneider
Thu Apr 17 12:43:52 MET DST 1997