Module file - File library

Check access to a filesystem object.

Get the size of a filesystem object.

Open a file descriptor. This form should be used when O.CREAT is not among the modes.

Open a file descriptor. This form should be used when O.CREAT is among the modes.

Create a pipe.

Example that copies a string by sending it through a pipe:

INT fd.read, fd.write:
 INT result, result.rd, result.wr:
 VAL []BYTE string IS "hello world!":
 [(SIZE string)]BYTE buffer:
 SEQ
   file.pipe (fd.read, fd.write, result)
   ASSERT (result = 0)
   PAR
     file.blocking.read (fd.read, buffer, (SIZE string), result.rd)
     file.write (fd.write, string, (SIZE string), result.wr)
   file.close (fd.read, result)
   ASSERT (result = 0)
   file.close (fd.write, result)
   ASSERT (result = 0)

See file.npipes if you're creating several pipes.

Make a copy of a file descriptor. new.fd will be closed first if it is already open.

Read from a file descriptor into a buffer. No more than SIZE buffer bytes will be read from the descriptor.

Note: file.read assumes that data is available (e.g. reading from a file), and is not a blocking call; if the read could block, use file.blocking.read instead.

Read from a file descriptor into a buffer without blocking the occam system. No more than SIZE buffer bytes will be read from the descriptor.

Write from a buffer to a file descriptor. No more than SIZE buffer bytes will be written.

Note: file.write assumes that data can always be written (e.g. writing to a file), and is not a blocking call; if the write could block, use file.blocking.write instead.

Write from a buffer to a file descriptor without blocking the occam system. No more than SIZE buffer bytes will be written.

Move the read/write offset of a file descriptor.

Close a file descriptor.

Create a directory.

Remove a directory. The directory must be empty before it can be removed.

Unlink a filesystem object. This can be used to remove anything that isn't a directory.

Copy bytes between file descriptors. The copy is performed in the background to reduce overhead.

Copy bytes between file descriptors efficiently. This uses the sendfile(2) system call to avoid copying data between userspace and kernelspace. Either or both descriptors may refer to a socket.

Create several pipes using file.pipe.

ALTable equivalent of file.blocking.read.

ALTable equivalent of file.blocking.write.

ALTable equivalent of file.fd.fd.copy.

Wait for one of a set of file descriptors to become ready. This performs the select(2) system call.

After file.array.select returns, the file descriptors in the sets that are not ready are changed to -1. Any file descriptors passed that are already -1 are ignored.

Perform various operations on file descriptors. This allows occam-pi programs to make a fcntl(2) system call with no optional parameter. See the fcntl(2) manual page for more information.

Perform various operations on file descriptors. This allows occam-pi programs to make a fcntl(2) system call with one optional parameter. See the fcntl(2) manual page for more information.

Get number of program arguments. This is the equivalent of argc in C. Programs always have at least one argument: their own name.

Get a program argument. This is the equivalent of argv[n] in C.

For example, if the occam-pi program was invoked as ./argtest foo "bar foo", then argument 1 will be foo, argument 2 will be bar foo, and file.num.args will return 3.

If you want to parse Unix-style command-line options, use file.get.options instead.

Parse command-line options. This is intended to behave like GNU getopt_long(3), but without support for permuting options.

The options argument is an array of strings listing the possible options for the program. Options that can take an argument should be followed by an equals sign.

Example, for a program which can take -v/--verbose and -h/--host HOST arguments:

CHAN GETOPT.LONG opts:
 PAR
   INITIAL MOBILE []MOBILE []BYTE spec IS MOBILE [4]MOBILE []BYTE:
   SEQ
     spec[0] := "v"
     spec[1] := "verbose"
     spec[2] := "h="
     spec[3] := "host="
     file.get.long.options (spec, opts!)
   INITIAL BOOL running IS TRUE:
   WHILE running
     MOBILE []BYTE o, a:
     opts ? CASE
       opt; o
         IF
           same.string (o, "v") OR same.string (o, "verbose")
             ...  handle -v option
       opt.arg; o; a
         IF
           same.string (o, "h") OR same.string (o, "host")
             ...  handle -h option; argument is in a
       arg; a
         ...  handle non-option argument a
       bad; o
         ...  print usage message and exit
       done
         running := FALSE

Parse command-line options. This is intended to behave like POSIX (not GNU) getopt(3). If you want to handle long options, use file.get.long.options instead; this PROC will report all long options as bad.

The options argument is a string listing the possible (single-character) options for the program. Options that can take an argument should be followed by a colon.

Example, for a program which can take -v and -h HOST arguments:

CHAN GETOPT opts:
 PAR
   file.get.options ("vh:", opts!)
   INITIAL BOOL running IS TRUE:
   WHILE running
     BYTE o:
     MOBILE []BYTE a:
     opts ? CASE
       opt; o
         CASE o
           'v'
             ...  handle -v option
       opt.arg; o; a
         CASE o
           'h'
             ...  handle -h option; argument is in a
       arg; a
         ...  handle non-option argument a
       bad; o
         ...  print usage message and exit
       done
         running := FALSE

Get information about a filesystem object. Symbolic links will be followed.

Get information about a filesystem object or link. Symbolic links will not be followed.

Get information about an open filesystem object.

Open a directory.

Read the next directory entry from a directory.

Close a directory descriptor.

Change the permissions of a filesystem object.

Force changes to an open file to be written to disk.