This section describes functions from file fileio.ct.
[] = fclose(fnum)
fclose(fnum) closes file with given identification number.
The fnum must have been previously obtained from fopen.
See also:
fopen,
fformat,
fread,
fwrite,
fgetc,
fgetc.
Error codes:
-1: Bad argument: not integer
-2: Bad argument: outside range
3: File was not open
[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,
fread,
fwrite.
Error codes:
-1: Bad argument: not integer
-2: Bad argument: outside range
[] = 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
[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,
fread,
fwrite.
Error codes:
-1: Bad argument: not integer
-2: Bad argument: out of range
-3: File was not open
[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,
fread,
fwrite.
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
[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,
fread,
fwrite.
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
[] = 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
[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,
fread,
fwrite.
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
[] = 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
[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:
fwrite,
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
[] = fwrite(fnum,arr)
fwrite(fnum,arr) writes the elements of integer array arr
as unsigned bytes in a previously opened file with
identification number fnum. The elements of arr are clamped
to the range 0..255 before writing them in the file.
See also:
fread,
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 array
-4: File was not open
[] = 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
[] = 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
[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
[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
[] = 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