Opening Files

 

    Each procedure in this subsection creates a new open-file object and returns a new file handle referring to it.

                   

TYPE
  OpenFlags = (fCreate, fExclusive, fTruncate,
               fRead, fWrite, fAppend,
               fNoDelay, fAsync);
  OpenMode = BITS 16 FOR SET OF [fCreate .. fAppend];

A value of type OpenMode is maintained within each open-file object. Most, but not all, of the individual flags can be specified when the open-file object is created; the others must be specified using the SetFlags procedure (see page ).

 

PROCEDURE Open(
    dir: Dir;
    path: PathName;
    flags: OpenMode;
    mode: FileMode;
    getLock: BOOLEAN := FALSE;
    euser: User := NIL)
    : File
  RAISES {Error};
  (* NotSuperUserEC, PathES, FileExistsEC, FileBusyEC,
     NotEnoughRoomEC, RanOutOfResourcesEC, CannotWriteADirectoryEC,
     NoDriverForDeviceEC, MinorDeviceDoesNotExistEC, FailureES,
     NotImplementedEC *)

Open returns a file handle referring to a new open-file object for the file (or directory) with the specified path name. The details depend on the flags parameter:

fCreate:

If the specified path name doesn't exist (but all the directories it names do exist) and fCreate is specified, create a new file. In this case, the new file is given the specified file mode adjusted using the value of the umask (see the GetUMask procedure on page ). NotEnoughRoomEC is raised if the volume is too full to create a new file. (The mode parameter is ignored if no new file is created. LookUpEC is raised if a directory specified by the path name doesn't exist, or if fCreate isn't specified and the file itself doesn't exist.)        

fExclusive:

When specified along with fCreate, raise FileExistsEC if the specified path name already exists. This can be used to implement a mutex that is accessible by several processes on the same or different machines.  

fTruncate:

Truncate the length of the file to zero.  

fRead:

Request that the open-file object allow reading.  

fWrite:

Request that the open-file object allow writing.  

fAppend:

Open for appending. When this flag is used with fWrite, all writes using this open-file object are performed at the end of the file, ignoring the file pointer.      

  If the path name specifies a regular file and getLock is TRUE, an advisory lock is simultaneously acquired (see the SetLock procedure on page ). This lock is an ExclusiveLock if fWrite was specified, or a SharedLock otherwise; it is automatically released when the file is closed.

Opening a directory for reading as if it were a regular file is permitted; attempting to open a directory for writing raises CannotWriteADirectoryEC.

Opening a file for writing has the side-effect of clearing the file's SetUIDonExec flag.

  Local access checking is based on the effective user name of the caller unless the caller is the super-user and supplies a non-NIL euser parameter, in which case the checking is based on that user. NotSuperUserEC is raised if a process other than the super-user supplies a non-NIL euser parameter.

Open raises RanOutOfResourcesEC if the path name specifies a file residing on an Ultrix machine and the Ultrix limitation on the maximum number of file descriptors per process is encountered. (This can occur two ways: either a Topaz application is running on Ultrix and trying to open a local file, or a Topaz application is running on Taos and trying to open a remote file residing on an Ultrix machine.)

Ultrix note: When getLock equals TRUE, Open does not atomically open the file and acquire the lock; it is possible that Open will create a new file and then block trying to lock it.

 

PROCEDURE OpenRead(
    dir: Dir;
    path: PathName;
    getLock: BOOLEAN := FALSE)
    : File
  RAISES {Error};
  (* PathES, FileBusyEC, RanOutOfResourcesEC,
     NoDriverForDeviceEC, MinorDeviceDoesNotExistEC, FailureES *)

OpenRead is equivalent to:

 

Note that mode is irrelevant because no new file is ever created.

 

PROCEDURE OpenWrite(
    dir: Dir;
    path: PathName;
    getLock: BOOLEAN := FALSE)
    : File
  RAISES {Error};
  (* PathES, FileBusyEC, NotEnoughRoomEC, RanOutOfResourcesEC,
     CannotWriteADirectoryEC,
     NoDriverForDeviceEC, MinorDeviceDoesNotExistEC, FailureES *)

OpenWrite is equivalent to:

       

It creates a new file if none existed, or truncates an existing file to length zero. Note that the file is also open for reading. The file mode ReadWriteAll is used since the setting of the umask will typically subtract wOK from Group and from Others.

    

TYPE
  SearchPath = ARRAY OF Dir;

PROCEDURE OpenSearch(
    VAR IN searchPath: SearchPath;
    path: PathName;
    VAR (* OUT *) pathIndex: CARDINAL;
    spStart: CARDINAL := 0;
    spCount: CARDINAL := LAST(CARDINAL);
    getLock: BOOLEAN := FALSE;
    euser: User := NIL)
    : File
  RAISES {Error};
  (* NotSuperUserEC, PathES, FileBusyEC, RanOutOfResourcesEC,
     NoDriverForDeviceEC, MinorDeviceDoesNotExistEC, FailureES *)

OpenSearch looks up a path name in the sequence of directories specified by path[spStart FOR spCount]. If the file is found, it is opened as in OpenRead and pathIndex is set to the index within searchPath where the file was found. This procedure is equivalent to:

 

OpenSearch interprets the euser parameter the same way Open does.

 

PROCEDURE OpenPipe(
    VAR (* OUT *) rdPipe: File;
    VAR (* OUT *) wrPipe: File;
    bufferSize: CARDINAL := 0)
  RAISES {Error}; (* RanOutOfResourcesEC *)

  OpenPipe creates two new open-file objects. The first is open only for reading and the second is open only for writing. They are linked together so that anything written on wrPipe is read by rdPipe. There are bufferSize bytes of first-in-first-out storage between the two ends; if bufferSize is zero, an implementation-dependent size is chosen. The open-file objects created by this procedure cannot be passed to the Seek procedure.

Once the reading end of a pipe is closed, a pipe is said to be broken. Writing to a broken pipe causes an error; see the Write procedure on page for details on how that error is reported.

Taos note: The current default for bufferSize is 4096. RanOutOfResourcesEC is never raised.

Ultrix note: The bufferSize parameter is ignored; 4096 is always used.

  

PROCEDURE OpenControlTerminal(): File
  RAISES {Error}; (* InvalidObjectEC *)

  OpenControlTerminal opens the control terminal for the calling process. OpenControlTerminal raises InvalidObjectEC if the calling process has no control terminal.

Taos note: OpenControlTerminal does not have to look up the path name /dev/tty, so it never needs to read from the disk.