Syntax 9-3—Syntax for file output system tasks

Each of the formatted display tasks — $display, $write, $monitor, and $strobe — has a counterpart that writes to specific files as opposed to the standard output. These counterpart tasks — $fdisplay, $fwrite, $fmonitor, $fstrobe, and $fdebug — accept the same type of arguments as the tasks upon which they are based, with one exception: The first argument shall be either a multichannel descriptor or a file descriptor, which indicates where to direct the file output. Multichannel descriptors are described in detail in 9.5.1. A multichannel descriptor is either a variable or the result of an expression that takes the form of a 32-bit unsigned integer value.

The $fstrobe and $fmonitor system tasks work just like their counterparts, $strobe and $monitor, except that they write to files using the file descriptor.

9.5.3 Formatting data to a string

The syntax for the $swrite family of tasks and for $sformat system task is shown in Syntax 9-4.

string_output_task ::=

$swrite ( string_variable , list_of_arguments ) ;

variable-format_string_output_task ::=

$sformat ( string_variable , format_string , list_of_arguments ) ;

Syntax 9-4—Syntax for formatting data tasks

The $swrite family of tasks is based on the $fwrite family of tasks and accepts the same type of arguments as the tasks upon which it is based, with one exception: The first argument to $swrite shall be a string variable to which the resulting string shall be written, instead of a variable specifying the file to which to write the resulting string.

The system task $sformat is similar to the system task $swrite, with one major difference.

Unlike the display and write family of output system tasks, $sformat always interprets its second argument, and only its second argument, as a format string. This format argument can be a static string, such as "data is %d" or can be a string variable whose content is interpreted as the format string. No other arguments are interpreted as format strings. $sformat supports all the format specifiers supported by $display, as documented in Table 9-21.

The remaining arguments to $sformat are processed using any format specifiers in the format_string, until all such format specifiers are used up. If not enough arguments are supplied for the format specifiers or too many are supplied, then the application shall issue a warning and continue execution. The application, if possible, can statically determine a mismatch in format specifiers and number of arguments and issue a compile time error message.

If the format_string is a string variable, it might not be possible to determine its value at compile time.

9.5.4 Reading data from a file

Files opened using file descriptors can be read from only if they were opened with either the r or r+ type values. See 9.5.2 for more information about opening files.

9.5.4.1 Reading a line at a time

For example:

integer code ;

code = $fgets ( str, fd );

reads characters from the file specified by fd into the string variable, str until a newline character is read and transferred to str, or an EOF condition is encountered.

If an error occurs reading from the file, then code is set to zero. Otherwise, the number of characters read is returned in code. Applications can call $ferror to determine the cause of the most recent error (see 9.5.7).

9.5.4.2 Reading formatted data

For example:

integer code ;

code = $fscanf ( fd, format, args ); code = $sscanf ( str, format, args );

$fscanf reads from the files specified by the file descriptor fd.

$sscanf reads from the string variable, str.

Both functions read characters, interpret them according to a format, and store the results. Both expect as arguments a control string, format, and a set of arguments specifying where to place the results. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are ignored.

If an argument is too small to hold the converted input, then, in general, the least significant bits are transferred. Arguments of any length that is supported by Verilog AMS HDL in the analog context can be used. However, if the destination is a real, then the value +Inf (or -Inf) is transferred. The format is a string expression. The string contains conversion specifications, which direct the conversion of input into the arguments. The control string can contain the following:

a)White space characters (blanks, tabs, newlines, or formfeeds) that, except in one case described below, cause input to be read up to the next nonwhite space character. For $sscanf, null characters shall also be considered white space.

b)An ordinary character (not %) that must match the next character of the input stream.

c)Conversion specifications consisting of the character %, an optional assignment suppression character *, a decimal digit string that specifies an optional numerical maximum field width, and a conversion code.

A conversion specification directs the conversion of the next input field; the result is placed in the variable specified in the corresponding argument unless assignment suppression was indicated by the character *. In this case, no argument shall be supplied.

The suppression of assignment provides a way of describing an input field that is to be skipped. An input field is defined as a string of nonspace characters; it extends to the next inappropriate character or until the maximum field width, if one is specified, is exhausted. For all descriptors except the character c, white space leading an input field is ignored.