   Copyright (C) 1996, 1997 John W. Eaton.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

C-Style I/O Functions
=====================

   Octave's C-style input and output functions provide most of the
functionality of the C programming language's standard I/O library.  The
argument lists for some of the input functions are slightly different,
however, because Octave has no way of passing arguments by reference.

   In the following, FILE refers to a file name and `fid' refers to an
integer file number, as returned by `fopen'.

   There are three files that are always available.  Although these
files can be accessed using their corresponding numeric file ids, you
should always use the symbolic names given in the table below, since it
will make your programs easier to understand.

 - Built-in Variable: stdin
     The standard input stream (file id 0).  When Octave is used
     interactively, this is filtered through the command line editing
     functions.

 - Built-in Variable: stdout
     The standard output stream (file id 1).  Data written to the
     standard output is normally filtered through the pager.

 - Built-in Variable: stderr
     The standard error stream (file id 2).  Even if paging is turned
     on, the standard error is not sent to the pager.  It is useful for
     error messages and prompts.

Opening and Closing Files
-------------------------

 - Built-in Function: [FID, MSG] = fopen (NAME, MODE, ARCH)
 - Built-in Function: FID_LIST = fopen ("all")
 - Built-in Function: FILE = fopen (FID)
     The first form of the `fopen' function opens the named file with
     the specified mode (read-write, read-only, etc.) and architecture
     interpretation (IEEE big endian, IEEE little endian, etc.), and
     returns an integer value that may be used to refer to the file
     later.  If an error occurs, FID is set to -1 and MSG contains the
     corresponding system error message.  The MODE is a one or two
     character string that specifies whether the file is to be opened
     for reading, writing, or both.

     The second form of the `fopen' function returns a vector of file
     ids corresponding to all the currently open files, excluding the
     `stdin', `stdout', and `stderr' streams.

     The third form of the `fopen' function returns the name of a
     currently open file given its file id.

     For example,

          myfile = fopen ("splat.dat", "r", "ieee-le");

     opens the file `splat.dat' for reading.  If necessary, binary
     numeric values will be read assuming they are stored in IEEE
     format with the least significant bit first, and then converted to
     the native representation.

     Opening a file that is already open simply opens it again and
     returns a separate file id.  It is not an error to open a file
     several times, though writing to the same file through several
     different file ids may produce unexpected results.

     The possible values `mode' may have are

    `r'
          Open a file for reading.

    `w'
          Open a file for writing.  The previous contents are discared.

    `a'
          Open or create a file for writing at the end of the file.

    `r+'
          Open an existing file for reading and writing.

    `w+'
          Open a file for reading or writing.  The previous contents are
          discarded.

    `a+'
          Open or create a file for reading or writing at the end of the
          file.

     The parameter ARCH is a string specifying the default data format
     for the file.  Valid values for ARCH are:

          `native' The format of the current machine (this is the
          default).

          `ieee-be' IEEE big endian format.

          `ieee-le' IEEE little endian format.

          `vaxd' VAX D floating format.

          `vaxg' VAX G floating format.

          `cray' Cray floating format.

     however, conversions are currently only supported for `native'
     `ieee-be', and `ieee-le' formats.

 - Built-in Function:  fclose (FID)
     Closes the specified file.  If an error is encountered while
     trying to close the file, an error message is printed and `fclose'
     returns 0.  Otherwise, it returns 1.

Simple Output
-------------

 - Built-in Function:  fputs (FID, STRING)
     Write a string to a file with no formatting.

 - Function File:  puts (STRING)
     Write a string to the standard output with no formatting.

Line-Oriented Input
-------------------

 - Built-in Function:  fgetl (FID, LEN)
     Read characters from a file, stopping after a newline, or EOF, or
     LEN characters have been read.  The characters read, excluding the
     possible trailing newline, are returned as a string.

     If LEN is omitted, `fgetl' reads until the next newline character.

     If there are no more characters to read, `fgetl' returns -1.

 - Built-in Function:  fgets (FID, LEN)
     Read characters from a file, stopping after a newline, or EOF, or
     LEN characters have been read.  The characters read, including the
     possible trailing newline, are returned as a string.

     If LEN is omitted, `fgets' reads until the next newline character.

     If there are no more characters to read, `fgets' returns -1.

Formatted Output
----------------

   This section describes how to call `printf' and related functions.

   The following functions are available for formatted output.  They are
modelled after the C language functions of the same name, but they
interpret the format template differently in order to improve the
performance of printing vector and matrix values.

 - Function File:  printf (TEMPLATE, ...)
     The `printf' function prints the optional arguments under the
     control of the template string TEMPLATE to the stream `stdout'.

 - Built-in Function:  fprintf (FID, TEMPLATE, ...)
     This function is just like `printf', except that the output is
     written to the stream FID instead of `stdout'.

 - Built-in Function:  sprintf (TEMPLATE, ...)
     This is like `printf', except that the output is returned as a
     string.  Unlike the C library function, which requires you to
     provide a suitably sized string as an argument, Octave's `sprintf'
     function returns the string, automatically sized to hold all of
     the items converted.

   The `printf' function can be used to print any number of arguments.
The template string argument you supply in a call provides information
not only about the number of additional arguments, but also about their
types and what style should be used for printing them.

   Ordinary characters in the template string are simply written to the
output stream as-is, while "conversion specifications" introduced by a
`%' character in the template cause subsequent arguments to be
formatted and written to the output stream.  For example,

     pct = 37;
     filename = "foo.txt";
     printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
             filename, pct);

produces output like

     Processing of `foo.txt' is 37% finished.
     Please be patient.

   This example shows the use of the `%d' conversion to specify that a
scalar argument should be printed in decimal notation, the `%s'
conversion to specify printing of a string argument, and the `%%'
conversion to print a literal `%' character.

   There are also conversions for printing an integer argument as an
unsigned value in octal, decimal, or hexadecimal radix (`%o', `%u', or
`%x', respectively); or as a character value (`%c').

   Floating-point numbers can be printed in normal, fixed-point notation
using the `%f' conversion or in exponential notation using the `%e'
conversion.  The `%g' conversion uses either `%e' or `%f' format,
depending on what is more appropriate for the magnitude of the
particular number.

   You can control formatting more precisely by writing "modifiers"
between the `%' and the character that indicates which conversion to
apply.  These slightly alter the ordinary behavior of the conversion.
For example, most conversion specifications permit you to specify a
minimum field width and a flag indicating whether you want the result
left- or right-justified within the field.

   The specific flags and modifiers that are permitted and their
interpretation vary depending on the particular conversion.  They're all
described in more detail in the following sections.

Output Conversion for Matrices
------------------------------

   When given a matrix value, Octave's formatted output functions cycle
through the format template until all the values in the matrix have been
printed.  For example,

     printf ("%4.2f %10.2e %8.4g\n", hilb (3));

          -| 1.00   5.00e-01   0.3333
          -| 0.50   3.33e-01     0.25
          -| 0.33   2.50e-01      0.2

   If more than one value is to be printed in a single call, the output
functions do not return to the beginning of the format template when
moving on from one value to the next.  This can lead to confusing output
if the number of elements in the matrices are not exact multiples of the
number of conversions in the format template.  For example,

     printf ("%4.2f %10.2e %8.4g\n", [1, 2], [3, 4]);

          -| 1.00   2.00e+00        3
          -| 4.00

   If this is not what you want, use a series of calls instead of just
one.

Output Conversion Syntax
------------------------

   This section provides details about the precise syntax of conversion
specifications that can appear in a `printf' template string.

   Characters in the template string that are not part of a conversion
specification are printed as-is to the output stream.

   The conversion specifications in a `printf' template string have the
general form:

     % FLAGS WIDTH [ . PRECISION ] TYPE CONVERSION

   For example, in the conversion specifier `%-10.8ld', the `-' is a
flag, `10' specifies the field width, the precision is `8', the letter
`l' is a type modifier, and `d' specifies the conversion style.  (This
particular type specifier says to print a numeric argument in decimal
notation, with a minimum of 8 digits left-justified in a field at least
10 characters wide.)

   In more detail, output conversion specifications consist of an
initial `%' character followed in sequence by:

   * Zero or more "flag characters" that modify the normal behavior of
     the conversion specification.

   * An optional decimal integer specifying the "minimum field width".
     If the normal conversion produces fewer characters than this, the
     field is padded with spaces to the specified width.  This is a
     _minimum_ value; if the normal conversion produces more characters
     than this, the field is _not_ truncated.  Normally, the output is
     right-justified within the field.

     You can also specify a field width of `*'.  This means that the
     next argument in the argument list (before the actual value to be
     printed) is used as the field width.  The value is rounded to the
     nearest integer.  If the value is negative, this means to set the
     `-' flag (see below) and to use the absolute value as the field
     width.

   * An optional "precision" to specify the number of digits to be
     written for the numeric conversions.  If the precision is
     specified, it consists of a period (`.') followed optionally by a
     decimal integer (which defaults to zero if omitted).

     You can also specify a precision of `*'.  This means that the next
     argument in the argument list (before the actual value to be
     printed) is used as the precision.  The value must be an integer,
     and is ignored if it is negative.

   * An optional "type modifier character".  This character is ignored
     by Octave's `printf' function, but is recognized to provide
     compatibility with the C language `printf'.

   * A character that specifies the conversion to be applied.

   The exact options that are permitted and how they are interpreted
vary between the different conversion specifiers.  See the descriptions
of the individual conversions for information about the particular
options that they use.

Table of Output Conversions
---------------------------

   Here is a table summarizing what all the different conversions do:

`%d', `%i'
     Print an integer as a signed decimal number.  See Integer Conversions,
     for details.  `%d' and `%i' are synonymous for
     output, but are different when used with `scanf' for input (see
     Table of Input Conversions).

`%o'
     Print an integer as an unsigned octal number.  See Integer Conversions,
     for details.

`%u'
     Print an integer as an unsigned decimal number.  See Integer Conversions,
     for details.

`%x', `%X'
     Print an integer as an unsigned hexadecimal number.  `%x' uses
     lower-case letters and `%X' uses upper-case.  See Integer Conversions,
     for details.

`%f'
     Print a floating-point number in normal (fixed-point) notation.
     See Floating-Point Conversions, for details.

`%e', `%E'
     Print a floating-point number in exponential notation.  `%e' uses
     lower-case letters and `%E' uses upper-case.  See Floating-Point Conversions,
     for details.

`%g', `%G'
     Print a floating-point number in either normal (fixed-point) or
     exponential notation, whichever is more appropriate for its
     magnitude.  `%g' uses lower-case letters and `%G' uses upper-case.
     See Floating-Point Conversions, for details.

`%c'
     Print a single character.  See Other Output Conversions.

`%s'
     Print a string.  See Other Output Conversions.

`%%'
     Print a literal `%' character.  See Other Output Conversions.

   If the syntax of a conversion specification is invalid, unpredictable
things will happen, so don't do this.  If there aren't enough function
arguments provided to supply values for all the conversion
specifications in the template string, or if the arguments are not of
the correct types, the results are unpredictable.  If you supply more
arguments than conversion specifications, the extra argument values are
simply ignored; this is sometimes useful.

Integer Conversions
-------------------

   This section describes the options for the `%d', `%i', `%o', `%u',
`%x', and `%X' conversion specifications.  These conversions print
integers in various formats.

   The `%d' and `%i' conversion specifications both print an numeric
argument as a signed decimal number; while `%o', `%u', and `%x' print
the argument as an unsigned octal, decimal, or hexadecimal number
(respectively).  The `%X' conversion specification is just like `%x'
except that it uses the characters `ABCDEF' as digits instead of
`abcdef'.

   The following flags are meaningful:

`-'
     Left-justify the result in the field (instead of the normal
     right-justification).

`+'
     For the signed `%d' and `%i' conversions, print a plus sign if the
     value is positive.

` '
     For the signed `%d' and `%i' conversions, if the result doesn't
     start with a plus or minus sign, prefix it with a space character
     instead.  Since the `+' flag ensures that the result includes a
     sign, this flag is ignored if you supply both of them.

`#'
     For the `%o' conversion, this forces the leading digit to be `0',
     as if by increasing the precision.  For `%x' or `%X', this
     prefixes a leading `0x' or `0X' (respectively) to the result.
     This doesn't do anything useful for the `%d', `%i', or `%u'
     conversions.

`0'
     Pad the field with zeros instead of spaces.  The zeros are placed
     after any indication of sign or base.  This flag is ignored if the
     `-' flag is also specified, or if a precision is specified.

   If a precision is supplied, it specifies the minimum number of
digits to appear; leading zeros are produced if necessary.  If you
don't specify a precision, the number is printed with as many digits as
it needs.  If you convert a value of zero with an explicit precision of
zero, then no characters at all are produced.

Floating-Point Conversions
--------------------------

   This section discusses the conversion specifications for
floating-point numbers: the `%f', `%e', `%E', `%g', and `%G'
conversions.

   The `%f' conversion prints its argument in fixed-point notation,
producing output of the form [`-']DDD`.'DDD, where the number of digits
following the decimal point is controlled by the precision you specify.

   The `%e' conversion prints its argument in exponential notation,
producing output of the form [`-']D`.'DDD`e'[`+'|`-']DD.  Again, the
number of digits following the decimal point is controlled by the
precision.  The exponent always contains at least two digits.  The `%E'
conversion is similar but the exponent is marked with the letter `E'
instead of `e'.

   The `%g' and `%G' conversions print the argument in the style of
`%e' or `%E' (respectively) if the exponent would be less than -4 or
greater than or equal to the precision; otherwise they use the `%f'
style.  Trailing zeros are removed from the fractional portion of the
result and a decimal-point character appears only if it is followed by
a digit.

   The following flags can be used to modify the behavior:

`-'
     Left-justify the result in the field.  Normally the result is
     right-justified.

`+'
     Always include a plus or minus sign in the result.

` '
     If the result doesn't start with a plus or minus sign, prefix it
     with a space instead.  Since the `+' flag ensures that the result
     includes a sign, this flag is ignored if you supply both of them.

`#'
     Specifies that the result should always include a decimal point,
     even if no digits follow it.  For the `%g' and `%G' conversions,
     this also forces trailing zeros after the decimal point to be left
     in place where they would otherwise be removed.

`0'
     Pad the field with zeros instead of spaces; the zeros are placed
     after any sign.  This flag is ignored if the `-' flag is also
     specified.

   The precision specifies how many digits follow the decimal-point
character for the `%f', `%e', and `%E' conversions.  For these
conversions, the default precision is `6'.  If the precision is
explicitly `0', this suppresses the decimal point character entirely.
For the `%g' and `%G' conversions, the precision specifies how many
significant digits to print.  Significant digits are the first digit
before the decimal point, and all the digits after it.  If the
precision is `0' or not specified for `%g' or `%G', it is treated like
a value of `1'.  If the value being printed cannot be expressed
precisely in the specified number of digits, the value is rounded to
the nearest number that fits.

Other Output Conversions
------------------------

   This section describes miscellaneous conversions for `printf'.

   The `%c' conversion prints a single character.  The `-' flag can be
used to specify left-justification in the field, but no other flags are
defined, and no precision or type modifier can be given.  For example:

     printf ("%c%c%c%c%c", "h", "e", "l", "l", "o");

prints `hello'.

   The `%s' conversion prints a string.  The corresponding argument
must be a string.  A precision can be specified to indicate the maximum
number of characters to write; otherwise characters in the string up to
but not including the terminating null character are written to the
output stream.  The `-' flag can be used to specify left-justification
in the field, but no other flags or type modifiers are defined for this
conversion.  For example:

     printf ("%3s%-6s", "no", "where");

prints ` nowhere ' (note the leading and trailing spaces).

Formatted Input
---------------

   Octave provides the `scanf', `fscanf', and `sscanf' functions to
read formatted input.  There are two forms of each of these functions.
One can be used to extract vectors of data from a file, and the other
is more `C-like'.

 - Built-in Function: [VAL, COUNT] = fscanf (FID, TEMPLATE, SIZE)
 - Built-in Function: [V1, V2, ..., COUNT] =  fscanf (FID, TEMPLATE,
          "C")
     In the first form, read from FID according to TEMPLATE, returning
     the result in the matrix VAL.

     The optional argument SIZE specifies the amount of data to read
     and may be one of

    `Inf'
          Read as much as possible, returning a column vector.

    `NR'
          Read up to NR elements, returning a column vector.

    `[NR, Inf]'
          Read as much as possible, returning a matrix with NR rows.
          If the number of elements read is not an exact multiple of
          NR, the last column is padded with zeros.

    `[NR, NC]'
          Read up to `NR * NC' elements, returning a matrix with NR
          rows.  If the number of elements read is not an exact multiple
          of NR, the last column is padded with zeros.

     If SIZE is omitted, a value of `Inf' is assumed.

     A string is returned if TEMPLATE specifies only character
     conversions.

     The number of items successfully read is returned in COUNT.

     In the second form, read from FID according to TEMPLATE, with each
     conversion specifier in TEMPLATE corresponding to a single scalar
     return value.  This form is more `C-like', and also compatible
     with previous versions of Octave.  The number of successful
     conversions is returned in COUNT

 - Built-in Function: [VAL, COUNT] = sscanf (STRING, TEMPLATE, SIZE)
 - Built-in Function: [V1, V2, ..., COUNT] =  sscanf (STRING, TEMPLATE,
          "C")
     This is like `fscanf', except that the characters are taken from
     the string STRING instead of from a stream.  Reaching the end of
     the string is treated as an end-of-file condition.

   Calls to `scanf' are superficially similar to calls to `printf' in
that arbitrary arguments are read under the control of a template
string.  While the syntax of the conversion specifications in the
template is very similar to that for `printf', the interpretation of
the template is oriented more towards free-format input and simple
pattern matching, rather than fixed-field formatting.  For example,
most `scanf' conversions skip over any amount of "white space"
(including spaces, tabs, and newlines) in the input file, and there is
no concept of precision for the numeric input conversions as there is
for the corresponding output conversions.  Ordinarily, non-whitespace
characters in the template are expected to match characters in the
input stream exactly.

   When a "matching failure" occurs, `scanf' returns immediately,
leaving the first non-matching character as the next character to be
read from the stream, and `scanf' returns all the items that were
successfully converted.

   The formatted input functions are not used as frequently as the
formatted output functions.  Partly, this is because it takes some care
to use them properly.  Another reason is that it is difficult to recover
from a matching error.

Input Conversion Syntax
-----------------------

   A `scanf' template string is a string that contains ordinary
multibyte characters interspersed with conversion specifications that
start with `%'.

   Any whitespace character in the template causes any number of
whitespace characters in the input stream to be read and discarded.
The whitespace characters that are matched need not be exactly the same
whitespace characters that appear in the template string.  For example,
write ` , ' in the template to recognize a comma with optional
whitespace before and after.

   Other characters in the template string that are not part of
conversion specifications must match characters in the input stream
exactly; if this is not the case, a matching failure occurs.

   The conversion specifications in a `scanf' template string have the
general form:

     % FLAGS WIDTH TYPE CONVERSION

   In more detail, an input conversion specification consists of an
initial `%' character followed in sequence by:

   * An optional "flag character" `*', which says to ignore the text
     read for this specification.  When `scanf' finds a conversion
     specification that uses this flag, it reads input as directed by
     the rest of the conversion specification, but it discards this
     input, does not return any value, and does not increment the count
     of successful assignments.

   * An optional decimal integer that specifies the "maximum field
     width".  Reading of characters from the input stream stops either
     when this maximum is reached or when a non-matching character is
     found, whichever happens first.  Most conversions discard initial
     whitespace characters, and these discarded characters don't count
     towards the maximum field width.  Conversions that do not discard
     initial whitespace are explicitly documented.

   * An optional type modifier character.  This character is ignored by
     Octave's `scanf' function, but is recognized to provide
     compatibility with the C language `scanf'.

   * A character that specifies the conversion to be applied.

   The exact options that are permitted and how they are interpreted
vary between the different conversion specifiers.  See the descriptions
of the individual conversions for information about the particular
options that they allow.

Table of Input Conversions
--------------------------

   Here is a table that summarizes the various conversion
specifications:

`%d'
     Matches an optionally signed integer written in decimal.  See
     Numeric Input Conversions.

`%i'
     Matches an optionally signed integer in any of the formats that
     the C language defines for specifying an integer constant.  See
     Numeric Input Conversions.

`%o'
     Matches an unsigned integer written in octal radix.  See Numeric Input Conversions.

`%u'
     Matches an unsigned integer written in decimal radix.  See
     Numeric Input Conversions.

`%x', `%X'
     Matches an unsigned integer written in hexadecimal radix.  See
     Numeric Input Conversions.

`%e', `%f', `%g', `%E', `%G'
     Matches an optionally signed floating-point number.  See Numeric Input Conversions.

`%s'
     Matches a string containing only non-whitespace characters.  See
     String Input Conversions.

`%c'
     Matches a string of one or more characters; the number of
     characters read is controlled by the maximum field width given for
     the conversion.  See String Input Conversions.

`%%'
     This matches a literal `%' character in the input stream.  No
     corresponding argument is used.

   If the syntax of a conversion specification is invalid, the behavior
is undefined.  If there aren't enough function arguments provided to
supply addresses for all the conversion specifications in the template
strings that perform assignments, or if the arguments are not of the
correct types, the behavior is also undefined.  On the other hand, extra
arguments are simply ignored.

Numeric Input Conversions
-------------------------

   This section describes the `scanf' conversions for reading numeric
values.

   The `%d' conversion matches an optionally signed integer in decimal
radix.

   The `%i' conversion matches an optionally signed integer in any of
the formats that the C language defines for specifying an integer
constant.

   For example, any of the strings `10', `0xa', or `012' could be read
in as integers under the `%i' conversion.  Each of these specifies a
number with decimal value `10'.

   The `%o', `%u', and `%x' conversions match unsigned integers in
octal, decimal, and hexadecimal radices, respectively.

   The `%X' conversion is identical to the `%x' conversion.  They both
permit either uppercase or lowercase letters to be used as digits.

   Unlike the C language `scanf', Octave ignores the `h', `l', and `L'
modifiers.

String Input Conversions
------------------------

   This section describes the `scanf' input conversions for reading
string and character values: `%s' and `%c'.

   The `%c' conversion is the simplest: it matches a fixed number of
characters, always.  The maximum field with says how many characters to
read; if you don't specify the maximum, the default is 1.  This
conversion does not skip over initial whitespace characters.  It reads
precisely the next N characters, and fails if it cannot get that many.

   The `%s' conversion matches a string of non-whitespace characters.
It skips and discards initial whitespace, but stops when it encounters
more whitespace after having read something.

   For example, reading the input:

      hello, world

with the conversion `%10c' produces `" hello, wo"', but reading the
same input with the conversion `%10s' produces `"hello,"'.

Binary I/O
----------

   Octave can read and write binary data using the functions `fread'
and `fwrite', which are patterned after the standard C functions with
the same names.  The are able to automatically swap the byte order of
integer data and convert among ths supported floating point formats as
the data are read.

 - Built-in Function: [VAL, COUNT] = fread (FID, SIZE, PRECISION, SKIP,
          ARCH)
     Read binary data of type PRECISION from the specified file ID FID.

     The optional argument SIZE specifies the amount of data to read
     and may be one of

    `Inf'
          Read as much as possible, returning a column vector.

    `NR'
          Read up to NR elements, returning a column vector.

    `[NR, Inf]'
          Read as much as possible, returning a matrix with NR rows.
          If the number of elements read is not an exact multiple of
          NR, the last column is padded with zeros.

    `[NR, NC]'
          Read up to `NR * NC' elements, returning a matrix with NR
          rows.  If the number of elements read is not an exact multiple
          of NR, the last column is padded with zeros.

     If SIZE is omitted, a value of `Inf' is assumed.

     The optional argument PRECISION is a string specifying the type of
     data to read and may be one of

    `"char"'
    `"char*1"'
    `"integer*1"'
    `"int8"'
          Single character.

    `"signed char"'
    `"schar"'
          Signed character.

    `"unsigned char"'
    `"uchar"'
          Unsigned character.

    `"short"'
          Short integer.

    `"unsigned short"'
    `"ushort"'
          Unsigned short integer.

    `"int"'
          Integer.

    `"unsigned int"'
    `"uint"'
          Unsigned integer.

    `"long"'
          Long integer.

    `"unsigned long"'
    `"ulong"'
          Unsigned long integer.

    `"float"'
    `"float32"'
    `"real*4"'
          Single precision float.

    `"double"'
    `"float64"'
    `"real*8"'
          Double precision float.

    `"integer*2"'
    `"int16"'
          Two byte integer.

    `"integer*4"'
    `"int32"'
          Four byte integer.

     The default precision is `"uchar"'.

     The optional argument SKIP specifies the number of bytes to skip
     after each element is read.  If it is not specified, a value of 0
     is assumed.

     The optional argument ARCH is a string specifying the data format
     for the file.  Valid values are

    `"native"'
          The format of the current machine.

    `"ieee-le"'
          IEEE big endian.

    `"ieee-be"'
          IEEE little endian.

    `"vaxd"'
          VAX D floating format.

    `"vaxg"'
          VAX G floating format.

    `"cray"'
          Cray floating format.

     Conversions are currently only supported for `"ieee-be"' and
     `"ieee-le"' formats.

     The data read from the file is returned in VAL, and the number of
     values read is returned in `count'

 - Built-in Function: COUNT = fwrite (FID, DATA, PRECISION, SKIP, ARCH)
     Write data in binary form of type PRECISION to the specified file
     ID FID, returning the number of values successfully written to the
     file.

     The argument DATA is a matrix of values that are to be written to
     the file.  The values are extracted in column-major order.

     The remaining arguments PRECISION, SKIP, and ARCH are optional,
     and are interpreted as described for `fread'.

     The behavior of `fwrite' is undefined if the values in DATA are
     too large to fit in the specified precision.

Temporary Files
---------------

 - Built-in Function: [FID, NAME, MSG] = tmpfile (TEMPLATE, DELETE)
     Return the file ID corresponding to a new temporary file with a
     unique name created from TEMPLATE.  The last six characters of
     TEMPLATE must be `XXXXXX' and tehse are replaced with a string
     that makes the filename unique.  The file is then created with
     mode read/write and permissions that are system dependent (on
     GNU/Linux systems, the permissions will be 0600 for versions of
     glibc 2.0.7 and later).  The file is opened with the `O_EXCL' flag.

     If the optional argument DELETE is supplied and is true, the file
     will be deleted automatically when Octave exits, or when the
     function `purge_tmp_files' is called.

     If successful, FID is a valid file ID, NAME is the name of the
     file, and and MSG is an empty string.  Otherwise, FID is -1, NAME
     is empty, and MSG contains a system-dependent error message.

 - Built-in Function: [FID, MSG] = tmpfile ()
     Return the file ID corresponding to a new temporary file with a
     unique name.  The file is opened in binary read/write (`"w+b"')
     mode.  The file will be deleted automatically when it is closed or
     when Octave exits.

     If successful, FID is a valid file ID and MSG is an empty string.
     Otherwise, FID is -1 and MSG contains a system-dependent error
     message.

 - Built-in Function:  tmpnam (DIR, PREFIX)
     Return a unique temporary file name as a string.

     If PREFIX is omitted, a value of `"oct-"' is used.  If DIR is also
     omitted, the default directory for temporary files is used.  If
     DIR is provided, it must exist, otherwise the default directory
     for temporary files is used.  Since the named file is not opened,
     by `tmpnam', it is possible (though relatively unlikely) that it
     will not be available by the time your program attempts to open it.

End of File and Errors
----------------------

 - Built-in Function:  feof (FID)
     Return 1 if an end-of-file condition has been encountered for a
     given file and 0 otherwise.  Note that it will only return 1 if
     the end of the file has already been encountered, not if the next
     read operation will result in an end-of-file condition.

 - Built-in Function:  ferror (FID)
     Return 1 if an error condition has been encountered for a given
     file and 0 otherwise.  Note that it will only return 1 if an error
     has already been encountered, not if the next operation will
     result in an error condition.

 - Built-in Function:  freport ()
     Print a list of which files have been opened, and whether they are
     open for reading, writing, or both.  For example,

          freport ()

               -|  number  mode  name
               -|
               -|       0     r  stdin
               -|       1     w  stdout
               -|       2     w  stderr
               -|       3     r  myfile

File Positioning
----------------

   Three functions are available for setting and determining the
position of the file pointer for a given file.

 - Built-in Function:  ftell (FID)
     Return the position of the file pointer as the number of characters
     from the beginning of the file FID.

 - Built-in Function:  fseek (FID, OFFSET, ORIGIN)
     Set the file pointer to any location within the file FID.  The
     pointer is positioned OFFSET characters from the ORIGIN, which may
     be one of the predefined variables `SEEK_CUR' (current position),
     `SEEK_SET' (beginning), or `SEEK_END' (end of file). If ORIGIN is
     omitted, `SEEK_SET' is assumed.  The offset must be zero, or a
     value returned by `ftell' (in which case ORIGIN must be `SEEK_SET'.

 - Built-in Variable: SEEK_SET
 - Built-in Variable: SEEK_CUR
 - Built-in Variable: SEEK_END
     These variables may be used as the optional third argument for the
     function `fseek'.

    `SEEK_SET'
          Position file relative to the beginning.

    `SEEK_CUR'
          Position file relative to the current position.

    `SEEK_END'
          used with fseek to position file relative to the end.

 - Built-in Function:  frewind (FID)
     Move the file pointer to the beginning of the file FID, returning
     1 for success, and 0 if an error was encountered.  It is
     equivalent to `fseek (FID, 0, SEEK_SET)'.

   The following example stores the current file position in the
variable `marker', moves the pointer to the beginning of the file, reads
four characters, and then returns to the original position.

     marker = ftell (myfile);
     frewind (myfile);
     fourch = fgets (myfile, 4);
     fseek (myfile, marker, SEEK_SET);

Plotting
********

   All of Octave's plotting functions use `gnuplot' to handle the
actual graphics.  There are two low-level functions, `gplot' and
`gsplot', that behave almost exactly like the corresponding `gnuplot'
functions `plot' and `splot'.  A number of other higher level plotting
functions, patterned after the graphics functions found in MATLAB
version 3.5, are also available.  These higher level functions are all
implemented in terms of the two low-level plotting functions.

Two-Dimensional Plotting
========================

 - Command: gplot RANGES EXPRESSION USING TITLE STYLE
     Generate a 2-dimensional plot.

     The RANGES, USING, TITLE, and STYLE arguments are optional, and
     the USING, TITLE and STYLE qualifiers may appear in any order
     after the expression.  You may plot multiple expressions with a
     single command by separating them with commas.  Each expression
     may have its own set of qualifiers.

     The optional item RANGES has the syntax

          [ x_lo : x_up ] [ y_lo : y_up ]

     and may be used to specify the ranges for the axes of the plot,
     independent of the actual range of the data.  The range for the y
     axes and any of the individual limits may be omitted.  A range
     `[:]' indicates that the default limits should be used.  This
     normally means that a range just large enough to include all the
     data points will be used.

     The expression to be plotted must not contain any literal matrices
     (e.g. `[ 1, 2; 3, 4 ]') since it is nearly impossible to
     distinguish a plot range from a matrix of data.

     See the help for `gnuplot' for a description of the syntax for the
     optional items.

     By default, the `gplot' command plots the second column of a matrix
     versus the first.  If the matrix only has one column, it is taken
     as a vector of y-coordinates and the x-coordinate is taken as the
     element index, starting with zero.  For example,

          gplot rand (100,1) with linespoints

     will plot 100 random values and connect them with lines.  When
     `gplot' is used to plot a column vector, the indices of the
     elements are taken as x values.

     If there are more than two columns, you can choose which columns
     to plot with the USING qualifier. For example, given the data

          x = (-10:0.1:10)';
          data = [x, sin(x), cos(x)];

     the command

          gplot [-11:11] [-1.1:1.1] \
            data with lines, data using 1:3 with impulses

     will plot two lines.  The first line is generated by the command
     `data with lines', and is a graph of the sine function over the
     range -10 to 10.  The data is taken from the first two columns of
     the matrix because columns to plot were not specified with the
     USING qualifier.

     The clause `using 1:3' in the second part of this plot command
     specifies that the first and third columns of the matrix `data'
     should be taken as the values to plot.

     In this example, the ranges have been explicitly specified to be a
     bit larger than the actual range of the data so that the curves do
     not touch the border of the plot.

 - Command: gset options
 - Command: gshow options
 - Command: replot options
     In addition to the basic plotting commands, the whole range of
     `gset' and `gshow' commands from `gnuplot' are available, as is
     `replot'.

     Note that in Octave 2.0, the `set' and `show' commands were
     renamed to `gset' and `gshow' in order to allow for compatibility
     with the MATLAB graphics and GUI commands in a future version of
     Octave.  (For now, the old `set' and `show' commands do work, but
     they print an annoying warning message to try to get people to
     switch to using `gset' and `gshow'.)

     The `gset' and `gshow' commands allow you to set and show
     `gnuplot' parameters.  For more information about the `gset' and
     `gshow' commands, see the documentation for `set' and `show' in
     the `gnuplot' user's guide (also available on line if you run
     `gnuplot' directly, instead of running it from Octave).

     The `replot' command allows you to force the plot to be
     redisplayed.  This is useful if you have changed something about
     the plot, such as the title or axis labels.  The `replot' command
     also accepts the same arguments as `gplot' or `gsplot' (except for
     data ranges) so you can add additional lines to existing plots.

     For example,

          gset term tek40
          gset output "/dev/plotter"
          gset title "sine with lines and cosine with impulses"
          replot "sin (x) w l"

     will change the terminal type for plotting, add a title to the
     current plot, add a graph of sin (x) to the plot, and force the
     new plot to be sent to the plot device.  This last step is
     normally required in order to update the plot.  This default is
     reasonable for slow terminals or hardcopy output devices because
     even when you are adding additional lines with a replot command,
     gnuplot always redraws the entire plot, and you probably don't
     want to have a completely new plot generated every time something
     as minor as an axis label changes.

     The command `shg' is equivalent to executing `replot' without any
     arguments.

 - Built-in Variable: automatic_replot
     You can tell Octave to redisplay the plot each time anything about
     it changes by setting the value of the builtin variable
     `automatic_replot' to a nonzero value.  Since this is fairly
     inefficient, the default value is 0.

   Note that NaN values in the plot data are automatically omitted, and
Inf values are converted to a very large value before calling gnuplot.

   The MATLAB-style two-dimensional plotting commands are:

 - Function File:  plot (ARGS)
     This function produces two-dimensional plots.  Many different
     combinations of arguments are possible.  The simplest form is

          plot (Y)

     where the argument is taken as the set of Y coordinates and the X
     coordinates are taken to be the indices of the elements, starting
     with 1.

     If more than one argument is given, they are interpreted as

          plot (X, Y, FMT ...)

     where Y and FMT are optional, and any number of argument sets may
     appear.  The X and Y values are interpreted as follows:

        * If a single data argument is supplied, it is taken as the set
          of Y coordinates and the X coordinates are taken to be the
          indices of the elements, starting with 1.

        * If the first argument is a vector and the second is a matrix,
          the the vector is plotted versus the columns (or rows) of the
          matrix.  (using whichever combination matches, with columns
          tried first.)

        * If the first argument is a matrix and the second is a vector,
          the the columns (or rows) of the matrix are plotted versus
          the vector.  (using whichever combination matches, with
          columns tried first.)

        * If both arguments are vectors, the elements of Y are plotted
          versus the elements of X.

        * If both arguments are matrices, the columns of Y are plotted
          versus the columns of X.  In this case, both matrices must
          have the same number of rows and columns and no attempt is
          made to transpose the arguments to make the number of rows
          match.

          If both arguments are scalars, a single point is plotted.

     If the FMT argument is supplied, it is interpreted as follows.  If
     FMT is missing, the default gnuplot line style is assumed.

    `-'
          Set lines plot style (default).

    `.'
          Set dots plot style.

    `@'
          Set points plot style.

    `-@'
          Set linespoints plot style.

    `^'
          Set impulses plot style.

    `L'
          Set steps plot style.

    `N'
          Interpreted as the plot color if N is an integer in the range
          1 to 6.

    `NM'
          If NM is a two digit integer and M is an integer in the range
          1 to 6, M is interpreted as the point style.  This is only
          valid in combination with the `@' or `-@' specifiers.

    `C'
          If C is one of `"r"', `"g"', `"b"', `"m"', `"c"', or `"w"',
          it is interpreted as the plot color (red, green, blue,
          magenta, cyan, or white).

    `";title;"'
          Here `"title"' is the label for the key.

    `+'
    `*'
    `o'
    `x'
          Used in combination with the points or linespoints styles,
          set the point style.

     The color line styles have the following meanings on terminals that
     support color.

          Number  Gnuplot colors  (lines)points style
            1       red                   *
            2       green                 +
            3       blue                  o
            4       magenta               x
            5       cyan                house
            6       brown            there exists

     The FMT argument can also be used to assign key titles.  To do so,
     include the desired title between semi-colons after the formatting
     sequence described above, e.g. "+3;Key Title;" Note that the last
     semi-colon is required and will generate an error if it is left
     out.

     Here are some plot examples:

          plot (x, y, "@12", x, y2, x, y3, "4", x, y4, "+")

     This command will plot `y' with points of type 2 (displayed as
     `+') and color 1 (red), `y2' with lines, `y3' with lines of color
     4 (magenta) and `y4' with points displayed as `+'.

          plot (b, "*")

     This command will plot the data in the variable `b' will be plotted
     with points displayed as `*'.

          t = 0:0.1:6.3;
          plot (t, cos(t), "-;cos(t);", t, sin(t), "+3;sin(t);");

     This will plot the cosine and sine functions and label them
     accordingly in the key.

 - Built-in Function:  hold ARGS
     Tell Octave to `hold' the current data on the plot when executing
     subsequent plotting commands.  This allows you to execute a series
     of plot commands and have all the lines end up on the same figure.
     The default is for each new plot command to clear the plot device
     first.  For example, the command

          hold on

     turns the hold state on.  An argument of `off' turns the hold state
     off, and `hold' with no arguments toggles the current hold state.

 - Built-in Function:  ishold
     Return 1 if the next line will be added to the current plot, or 0
     if the plot device will be cleared before drawing the next line.

 - Built-in Function:  clearplot
 - Built-in Function:  clg
     Clear the plot window and any titles or axis labels.  The name
     `clg' is aliased to `clearplot' for compatibility with MATLAB.

     The commands `gplot clear', `gsplot clear', and `replot clear' are
     equivalent to `clearplot'.  (Previously, commands like `gplot
     clear' would evaluate `clear' as an ordinary expression and clear
     all the visible variables.)

 - Function File:  shg
     Show the graph window.  Currently, this is the same as executing
     replot without any arguments.

 - Built-in Function:  closeplot
     Close stream to the `gnuplot' subprocess.  If you are using X11,
     this will close the plot window.

 - Built-in Function:  purge_tmp_files
     Delete the temporary files created by the plotting commands.

     Octave creates temporary data files for `gnuplot' and then sends
     commands to `gnuplot' through a pipe.  Octave will delete the
     temporary files on exit, but if you are doing a lot of plotting
     you may want to clean up in the middle of a session.

     A future version of Octave will eliminate the need to use temporary
     files to hold the plot data.

 - Function File:  axis (LIMITS)
     Set axis limits for plots.

     The argument LIMITS should be a 2, 4, or 6 element vector.  The
     first and second elements specify the lower and upper limits for
     the x axis.  The third and fourth specify the limits for the y
     axis, and the fifth and sixth specify the limits for the z axis.

     If your plot is already drawn, then you need to use `replot' before
     the new axis limits will take effect.  You can get this to happen
     automatically by setting the built-in variable `automatic_replot'
     to a nonzero value.

     Without any arguments, `axis' turns autoscaling on.

     The vector argument specifying limits is optional, and additional
     string arguments may be used to specify various axis properties.
     For example,

          axis ([1, 2, 3, 4], "square");

     forces a square aspect ratio, and

          axis ("labely", "tic");

     turns tic marks on for all axes and tic mark labels on for the
     y-axis only.

     The following options control the aspect ratio of the axes.

    `"square"'
          Force a square aspect ratio.

    `"equal"'
          Force x distance to equal y-distance.

    `"normal"'
          Restore the balance.

     The following options control the way axis limits are interpreted.

    `"auto"'
          Set the specified axes to have nice limits around the data or
          all if no axes are specified.

    `"manual"'
          Fix the current axes limits.

    `"tight"'
          Fix axes to the limits of the data (not implemented).

     The option `"image"' is equivalent to `"tight"' and `"equal"'.

     The following options affect the appearance of tic marks.

    `"on"'
          Turn tic marks and labels on for all axes.

    `"off"'
          Turn tic marks off for all axes.

    `"tic[xyz]"'
          Turn tic marks on for all axes, or turn them on for the
          specified axes and off for the remainder.

    `"label[xyz]"'
          Turn tic labels on for all axes, or turn them on for the
          specified axes and off for the remainder.

    `"nolabel"'
          Turn tic labels off for all axes.  Note, if there are no tic
     marks for an axis, there can be no labels.

     The following options affect the direction of increasing values on
     the axes.

    `"ij"'
          Reverse y-axis, so lower values are nearer the top.

    `"xy"'
          Restore y-axis, so higher values are nearer the top.