If an invalid conversion character follows the %, the results of the operation are implementation dependent.

If EOF is encountered during input, conversion is terminated. If EOF occurs before any characters matching the current directive have been read (other than leading white space, where permitted), execution of the current directive terminates with an input failure. Otherwise, unless execution of the current directive is terminated with a matching failure, execution of the following directive (if any) is terminated with an input failure.

If conversion terminates on a conflicting input character, the offending input character is left unread in the input stream. Trailing white space (including newline characters) is left unread unless matched by a directive. The success of literal matches and suppressed assignments is not directly determinable.

The number of successfully matched and assigned input items is returned in code; this number can be 0 in the event of an early matching failure between an input character and the control string. If the input ends before the first matching failure or conversion, EOF is returned. Applications can call $ferror to determine the cause of the most recent error (see 9.5.7).

9.5.5 File positioning

Example 1

integer pos ;

pos = $ftell ( fd );

returns in pos the offset from the beginning of the file of the current byte of the file fd, which shall be read or written by a subsequent operation on that file descriptor.

This value can be used by subsequent $fseek calls to reposition the file to this point. Any repositioning shall cancel any $ungetc operations. If an error occurs, EOF is returned. Applications can call $ferror to determine the cause of the most recent error (see 17.2.7 of IEEE std 1364-2005 Verilog HDL).

Example 2

code = $fseek ( fd, offset, operation ); code = $rewind ( fd );

sets the position of the next input or output operation on the file specified by fd. The new position is at the signed distance offset bytes from the beginning, from the current position, or from the end of the file, according to an operation value of 0, 1, and 2 as follows:

—0 sets position equal to offset bytes

—1 sets position to current location plus offset

—2 sets position to EOF plus offset

$rewind is equivalent to $fseek (fd,0,0);

Repositioning the current file position with $fseek or $rewind shall cancel any $ungetc operations.

$fseek() allows the file position indicator to be set beyond the end of the existing data in the file. If data are later written at this point, subsequent reads of data in the gap shall return zero until data are actually written into the gap. $fseek, by itself, does not extend the size of the file.

When a file is opened for append (that is, when type is "a" or "a+"), it is impossible to overwrite information already in the file. $fseek can be used to reposition the file pointer to any position in the file, but when output is written to the file, the current file pointer is disregarded. All output is written at the end of the file and causes the file pointer to be repositioned at the end of the output.

If an error occurs repositioning the file, then code is set to -1. Otherwise, code is set to 0.

Applications can call $ferror to determine the cause of the most recent error (see 9.5.7).

9.5.6 Flushing output

For example:

$fflush ( mcd ); $fflush ( fd ); $fflush ( );

writes any buffered output to the file(s) specified by mcd, to the file specified by fd, or if $fflush is invoked with no arguments, to all open files.

9.5.7 I/O error status

Should any error be detected by one of the file I/O routines, an error code is returned. Often this is sufficient for normal operation (i.e., if the opening of an optional configuration file fails, the application typically would simply continue using default values). However, sometimes it is useful to obtain more information about the error for correct application operation. In this case, the $ferror function can be used:

integer errno ;

errno = $ferror ( fd, str );

A string description of type of error encountered by the most recent file I/O operation is written into str, which should be at least 640 bits wide. The integral value of the error code is returned in errno. If the most recent operation did not result in an error, then the value returned shall be zero, and the string variable str shall be empty.