The system tasks and functions for file-based operations are divided into the following categories:

—Functions and tasks that open and close files

—Tasks that output values into files

—Tasks that output values into variables

—Tasks and functions that read values from files and load into variables

9.5.1 Opening and closing files

The syntax for $fopen and $fclose system tasks is shown in Syntax 9-2.

file_open_function ::=

multi_channel_descriptor = $fopen ( "file_name" ) ; | fd = $fopen ( "file_name" , type ) ;

file_close_task ::=

$fclose ( multi_channel_descriptor ) ;

| $fclose ( fd ) ;

Syntax 9-2—Syntax for $fopen and $fclose system tasks

The function $fopen opens the file specified as the filename argument and returns either a 32-bit multichannel descriptor or a 32-bit file descriptor, determined by the absence or presence of the type argument.

filename is a string expression containing a character string that names the file to be opened.

type is a string expression containing a character string of one of the forms in Table 9-22 that indicates how the file should be opened. If type is omitted, the file is opened for writing, and a multichannel descriptor mcd is returned. If type is supplied, the file is opened as specified by the value of type, and a file descriptor fd is returned.

The multichannel descriptor mcd is a 32-bit integer in which a single bit is set indicating which file is opened. The least significant bit (bit 0) of an mcd always refers to the standard output. Output is directed to two or more files opened with multichannel descriptors by bitwise OR-ing together their mcds and writing to the resultant value.

The most significant bit (bit 31) of a multichannel descriptor is reserved and shall always be cleared, limiting an implementation to at most 31 files opened for output via multichannel descriptors.

The file descriptor fd is a 32-bit value. The most significant bit (bit 31) of a fd is reserved and shall always be set; this allows implementations of the file input and output functions to determine how the file was opened. The remaining bits hold a small number indicating what file is opened. Three file descriptors are pre-opened; they are STDIN, STDOUT, and STDERR, which have the values 32'h8000_0000, 32'h8000_0001, and 32'h8000_0002, respectively. STDIN is pre-opened for reading, and STDOUT and STDERR are pre-opened for append.

Unlike multichannel descriptors, file descriptors cannot be combined via bitwise OR in order to direct output to multiple files. Instead, files are opened via file descriptor for input, output, and both input and output, as well as for append operations, based on the value of type, according to Table 9-23.