Next Previous Contents

9. fileio.ct

This section describes functions from file fileio.ct.

9.1 fclose

[] = fclose(fnum)
 fclose(fnum) closes file with given identification number.
   The fnum must have been previously obtained from fopen.
See also: fopen, fformat.
   Error codes:
   -1: Bad argument: not integer
   -2: Bad argument: outside range
   3: File was not open

9.2 feof

[result] = feof(fnum)
 feof(fnum) checks whether end of file has been reached
   on previously opened file with identification number fnum.
   Return value is 1 in case of EOF and 0 otherwise.
   Return value is -1 if the file is not open.
See also: fgetc, fgets, fopen.
   Error codes:
   -1: Bad argument: not integer
   -2: Bad argument: outside range

9.3 fformat

[] = fformat(fnum,str...)
 fformat(fnum,"format-string",arg1,arg2,...) is similar to format,
   except that it does not output to stdout but to opened file.
See also: format, sformat, fopen.
   Error codes:
   -1: First argument not integer
   -2: First argument not a valid file number
   -3: Second argument not a string or char
   4: File is not open
   

9.4 fgetc

[ch] = fgetc(fnum)
 fgetc(fnum) returns the next character from previously
   opened file with identification number fnum, or VOID
   value if end of file has been reached.
See also: fgets, fopen, feof.
   Error codes:
   -1: Bad argument: not integer
   -2: Bad argument: out of range
   -3: File was not open

9.5 fgets

[s;endletter] = fgets(fnum;endletters)
 s=fgets(fnum) reads a string from previously opened
   file with identification number fnum. The string
   is terminated with a newline, which is removed from
   the stream but not returned.
   s=fgets(fnum,t) where t is a string uses characters
   in t as terminators, the default for t is "\n".
   [s,t1]=fgets(..) also returns the terminating character
   in t1.
See also: fgetc, fopen, feof.
   Error codes:
   -1: Bad first argument: not integer
   -2: Bad first argument: outside range
   -3: File was not open
   -4: Bad second argument: not a string
   

9.6 fopen

[fnum] = fopen(name,mode)
 fopen("filename",mode) opens a file and returns
   its identifier (integer). The mode parameter can be
   "r", "w" or "a" for reading, writing and appending,
   respectively. If the open is not succesful, -1 is returned.
See also: fformat, fclose, fgetc, fgets.
   Error codes:
   -1: First arg not a string
   -2: Second arg not a string
   -3: Too many open files
   -4: Bad string for second arg

9.7 format

[] = format(str...)
 format("format-string",arg1,arg2,...) prints "format-string"
   to standard output, replacing occurrences of `format-spec`
   with consecutive args. `Format-spec` is either empty, i.e. ``,
   or of the form

       `[-]w[.d]`.

   Here w is the field width (unsigned integer) and d is the number
   of significant digits, also unsigned integer. By default the
   argument is printed left-justified, but the optional minus sign
   dictates right justification. The backquote character `  can be
   produced by writing it three times: ```.
   
   Hint: You can add any number of spaces before the closing backquote,
   for example `20.7    `.
   These spaces do not affect the output. This feature can be used
   to justify source code lines.
See also: fformat, sformat.
   Error codes:
   1: First argument not a string or char 

9.8 fparse

[n...] = fparse(fnum,controlstr)
 [n,a,b,c,...] = fparse(fnum,"contolstring") scans input file
   with identification number fnum (obtained with fopen).
   Occurrences of `` in "controlstring" denote objects to be
   read and placed to output variables a,b,c,... in order.
   The number of objects succesfully read added by one is
   placed in n in the normal case.
   The notation `i`, `r`, `z` and `c` can be used to read
   integer, real or complex numbers, or single characters.

   For example,

   fnum = fopen("inputfile","r");
   [n,c,i,z] = fparse(fnum,"N`c` = `i`, a = `z`;");
   if (n != 4) error("...");

   would accept the input

   N3=  35,a   =3.4;

   after which c would be '3', i would be 35 and z would
   be 3.4. White space characters in controlstring are special,
   they match any number (including zero) of whitespace characters
   in input. Other characters in controlstring must appear
   literally in input. The variable n would be assigned the value
   4 in this case. Every time an object is succesfully read,
   the return value is incremented. If the end of the control string
   after the last `` item matches the input, the return value is
   incremented once more. Thus, in the above example, n==1 would
   mean that error occurred between `c` and `i``, n==1 would
   indicate error between `i` and `z` and n==3 would indicate a
   missing semicolon after `z`. Perfectly correct input always
   produced n equal to the total number of output arguments,
   four in the above example.

   Currently there is no way to quote the ` character
   in control string. To read `, read it as `c` and later
   check that it really was a backquote.
   
See also: fopen, feof, fgets, fgetc.
   Error codes:
   -1: First input arg not an integer
   -2: Second input arg not a string
   -3: Bad first argument: outside range
   -4: File is not open
   -5: Unended `` item in control string
   -6: Too few output arguments as compared to control string
   -7: Bad `` item: must be `c`, `i`, `r` or `z`
   -8: `x` item does not end with backquote character

9.9 fprintf

[] = fprintf(fnum,formatstr...)
 fprintf(fnum,"format-string",arg1,arg2,...) is an interface to the C
   fprintf function. The format string should have a percent slot
   for every arg. The args may be integer or real scalars or strings.
   The file identifier fnum must have been obtained from fopen.

   Notice: The stream is not flushed after every fprintf operation,
   but a flush occurs whenever you switch from using fprintf to
   fformat on the same file. Therefore avoid mixing fprintf and fformat
   on the same file if performance is an issue for you!
   
See also: fopen, printf, sprintf, format.
   Error codes:
   1: Bad argument type
   2: Second arg not a string
   3: First argument not an integer
   4: Bad file identifier: out of range
   5: File is not open
   6: Internal error: fdopen failed
   

9.10 fread

[s] = fread(fnum,n)
 fread(fnum,n) reads next n characters (bytes) from
   previously opened file with identification number fnum,
   and returns the result as a string.
   If EOF is reached during read, the read is terminated earlier,
   resulting in length(s) being less than n (possibly zero).
See also: fgets, fopen, feof, fgetc.
   Error codes:
   -1: Bad first arg, not integer
   -2: Bad first arg, out of range
   -3: Bad second arg, not integer
   -4: File was not open
   -5: Number of bytes to be read is negative

9.11 printf

[] = printf(formatstr...)
 printf("format-string",arg1,arg2,...) is an interface to the C
   printf function. The format string should have a percent slot
   for every arg. The args may be integer or real scalars or strings.
See also: fprintf, sprintf, format.
   Error codes:
   1: Bad argument type
   2: First arg not a string
   

9.12 remove

[] = remove(fn)
 remove("file") removes the named file.
   If the file does not exist or some other error occurs,
   no warning or error message is given.
   Error codes:
   1: Argument not a string
   

9.13 sformat

[s] = sformat(formatstr...)
 sformat("format-string",arg1,arg2,...) is similar to format,
   except that it does not output to stdout but returns a string
   variable.
See also: format, fformat, sprintf.
   Error codes:
   -1: First argument not a string or char 

9.14 sprintf

[s] = sprintf(formatstr,arg)
 sprintf("format-string",arg1,arg2,...) is an interface to the C
   sprintf function. The format string should have a percent
   slot for every arg. The args may be integer or real scalars
   or strings.
See also: sformat.

   LIMITATIONS:
       This implementation allows only one arg (arg1).
       The resulting string may not become larger than
           500 chars or Tela may crash.
   Error codes:
   -1: First arg not a string
   -2: Args may only be scalar ints or reals, or strings
   

9.15 ungetc

[] = ungetc(ch,fnum)
 ungetc(ch,fnum) puts the character ch back to the file defined
   by identification number fnum. The success of the operation
   depends on the implementation underlying C library ungetc call;
   ANSI C guarantees only one character of pushback but many libraries
   allow more.
   Ungetc does not return a value. If the operation is unsuccessful,
   a warning message is generated.
   Error codes:
   -1: Bad first argument: not integer
   -2: Bad first argument: outside range
   -3: File was not open
   -4: First argument not an integer
   1: Cannot push back character


Next Previous Contents