6.1.6 Special I/O

fmt_read(+Fmt,-Term,-Ret)

fmt_read(+Stream,+Fmt,-Term,-Ret)

These predicates provides a routine for reading data from the current input file (which must have been already opened by using see/1) according to a C format, as used in the C function scanf. Fmt must be a string of characters (enclosed in ") representing the format that will be passed to the C call to scanf. See the C documentation for scanf for the meaning of this string. The usual alphabetical C escape characters (e.g., $\backslash n$) are recognized, but not the octal or the hexadecimal ones. Another difference with C is that, unlike most C compilers, XSB insists that a single % in the format string signifies format conversion specification. (Some C compilers might output % if it is not followed by a valid type conversion spec.) So, to output % you must type %%. Format can also be an atom enclosed in single quotes. However, in that case, escape sequences are not recognized and are printed as is.

Term is a term (e.g., args(X,Y,Z)) whose arguments will be unified with the field values read in. (The functor symbol of Term is ignored.) Special syntactic sugar is provided for the case when the format string contains only one format specifier: If Term is a variable, X, then the predicate behaves as if Term were arg(X).

If the number of arguments exceeds the number of format specifiers, a warning is produced and the extra arguments remain uninstantiated. If the number of format specifiers exceeds the number of arguments, then the remainder of the format string (after the last matching specifier) is ignored.

Note that floats do not unify with anything. Ret must be a variable and it will be assigned a return value by the predicate: a negative integer if end-of-file is encountered; otherwise the number of fields read (as returned by scanf.)

fmt_read cannot read strings (that correspond to the %s format specifier) that are longer than 16K. Attempting to read longer strings will cause buffer overflow. It is therefore recommended that one should use size modifiers in format strings (e.g., %2000s), if such long strings might occur in the input.

fmt_write(+Fmt,+Term)

fmt_write(+Stream,+Fmt,+Term)

This predicate provides a routine for writing data to the current output file (which must have been already opened by using tell/1) according to a C format, as used in the C function printf. Fmt must be a string of characters (enclosed in ") representing the format that will be passed to the C call to printf. See the C documentation for printf for the meaning of this string. The usual alphabetical C escape characters ( e.g., $\backslash n$) are recognized, but not the octal or the hexadecimal ones.

In addition to the usual C conversion specifiers, %S is also allowed. The corresponding argument can be any Prolog term. This provides an easy way to print the values of Prolog variables, etc. Also %! is supported and indicates that the corresponding argument is to be ignored and will generate nothing in the output.

Another difference with C is that, unlike most C compilers, XSB insists that a single % in the format string signifies format conversion specification. (Some C compilers might output % if it is not followed by a valid type conversion spec.) So, to output % you must type %%.

Format can also be an atom, but then escape sequences are not recognized.

Term is a term (e.g., args(X,Y,Z)) whose arguments will be output. The functor symbol of Term is ignored.

Special syntactic sugar is provided for the following cases: If Term is a variable, X, then it is ignored and only the format string is printed. If Term is a string, integer or a float, then it is assumed that this is the only argument to be printed, i.e., it is equivalent to specifying arg(Term).

If the number of format specifiers is greater than the number of arguments to be printed, an error is issued. If the number of arguments is greater, then a warning is issued.

fmt_write_string(-String,+Fmt,+Term)

This predicate works like the C function sprintf. It takes the format string and substitutes the values from the arguments of Term (e.g., args(X,Y,Z)) for the formatting instructions %s, %d, etc. Additional syntactic sugar, as in fmt_write, is recognized. The result is available in String. Fmt is a string or an atom that represents the format, as in fmt_write.

If the number of format specifiers is greater than the number of arguments to be printed, an error is issued. If the number of arguments is greater, then a warning is issued.

fmt_write_string requires that the printed size of each argument (e.g., X,Y,and Z above) must be less than 16K. Longer arguments are cut to that size, so some loss of information is possible. However, there is no limit on the total size of the output (apart from the maximum atom size imposed by XSB).

file_read_line_list(-String)

A line read from the current input stream is converted into a list of character codes. This predicate avoids interning an atom as does file_read_line_atom/3, and so is recommended when speed is important. This predicate fails on reaching the end of file.

file_read_line_list(Stream_or_alias,-CharList)

Acts as does file_read_line_list, but uses Stream_or_atom.

Error Cases

• Stream_or_alias is not instantiated to a stream term or alias.
  • domain_error(stream_or_alias,Stream_or_alias)
• Stream_or_alias is not associated with an open input stream
  • existence_error(stream,Stream_or_alias)

file_read_line_atom(-Atom)

Reads a line from the current (textual) input stream, returning it as Atom. This predicate fails on reaching the end of file.

file_read_line_atom(+Stream_or_alias,-Atom)

Like file_read_line_atom/1 but reads from Stream_or_alias. Error Cases

• Stream_or_alias is not instantiated to a stream term or alias.
  • domain_error(stream_or_alias,Stream_or_alias)
• Stream_or_alias is not associated with an open input stream
  • existence_error(stream,Stream_or_alias)

file_write_line(+String, +Offset)

file_io
Write String beginning with character Offset to the current output stream. String can be an atom or a list of ASCII character codes. This does not put the newline character at the end of the string (unless String already had this character). Note that escape sequences, like \n, are recognized if String is a character list, but are output as is if String is an atom.

file_write_line(+Stream_or_alias, +String, +Offset)

file_io
Like file_write_line/2, but output goes to Stream_or_alias.

Error Cases

• Stream_or_alias is not instantiated to a stream term or alias.
  • domain_error(stream_or_alias,Stream_or_alias)
• Stream_or_alias is not associated with an open input stream
  • existence_error(stream,Stream_or_alias)

file_getbuf_list(+Stream_or_alias, +BytesRequested, -CharList, -BytesRead)

file_io
Read BytesRequested bytes from file represented by Stream_or_alias (which must already be open for reading) into variable String as a list of character codes. This is analogous to fread in C. This predicate always succeeds. It does not distinguish between a file error and end of file. You can determine if either of these conditions has happened by verifying that $\tt BytesRead < BytesRequested$.

file_getbuf_list(+BytesRequested, -String, -BytesRead)

file_io

Like file_getbuf_list/3, but reads from the currently open input stream (i.e., with see/1).

file_getbuf_atom(+Stream_or_alias, +BytesRequested, -String, -BytesRead)

file_io
Read BytesRequested bytes from file represented by Stream_or_alias (which must already be open for reading) into variable String. This is analogous to fread in C. This predicate always succeeds. It does not distinguish between a file error and end of file. You can determine if either of these conditions has happened by verifying that $\tt BytesRead < BytesRequested$.

Note: because XSB does not have an atom table garbage collector yet, this predicate should not be used to read large files. Use read_getbuf_list or another predicate in this case.

Error Cases

• Stream_or_alias is not instantiated to a stream term or alias.
  • domain_error(stream_or_alias,Stream_or_alias)
• Stream_or_alias is not associated with an open input stream
  • existence_error(stream,Stream_or_alias)

file_getbuf_atom(+BytesRequested, -String, -BytesRead)

file_io
Like file_getbuf_atom/4, but reads from the currently open input stream.

file_putbuf(+Stream_or_alias, +BytesRequested, +String, +Offset, -BytesWritten)

file_io
Write BytesRequested bytes into file represented by I/O port Stream_or_alias (which must already be open for writing) from variable String at position Offset. This is analogous to C fwrite. The value of String can be an atom or a list of ASCII characters.

Error Cases

• Stream_or_alias is not instantiated to a stream term or alias.
  • domain_error(stream_or_alias,Stream_or_alias)
• Stream_or_alias is not associated with an open input stream
  • existence_error(stream,Stream_or_alias)

file_putbuf(+BytesRequested, +String, +Offset, -BytesWritten)

file_io
Like file_putbuf/3, but output goes to the currently open output stream.