Synopsis
Clear the error of a file stream
Usage
clearerr (File_Type fp
Description
The clearerr function clears the error and end-of-file flags
associated with the open file stream fp .
See also
Synopsis
Close a file
Usage
Integer_Type fclose (File_Type fp)
Description
The
fclose function may be used to close an open file pointer
fp . Upon success it returns zero, and upon failure it sets
errno and returns
-1 . Failure usually indicates a that
the file system is full or that
fp does not refer to an open file.
Notes
Many C programmers call
fclose without checking the return
value. The
SLang language requires the programmer to explicitly
handle any value returned by a
SLang function. The simplest way to
handle the return value from
fclose is to use it as:
() = fclose (fp);
See also
Synopsis
Convert a FD_Type file descriptor to a stdio File_Type object
Usage
File_Type fdopen (FD_Type, String_Type mode)
Description
The
fdopen function creates and returns a stdio
File_Type object from the open
FD_Type
descriptor
fd . The
mode parameter corresponds to the
mode parameter of the
fopen function and must be
consistent with the mode of the descriptor
fd . The function
returns \NULL upon failure and sets
errno .
Notes
The
fclose function does not close the
File_Type object
returned from this function. The underlying file object must be
closed by the
close function.
See also
function feof
Synopsis
Get the end-of-file status
Usage
Integer_Type feof (File_Type fp)
Description
This function may be used to determine the state of the end-of-file
indicator of the open file descriptor
fp . It returns
0
if the indicator is not set, or non-zero if it is. The end-of-file
indicator may be cleared by the
clearerr function.
See also
Synopsis
Determine the error status of an open file descriptor
Usage
Integer_Type ferror (File_Type fp)
Description
This function may be used to determine the state of the error
indicator of the open file descriptor
fp . It returns
0
if the indicator is not set, or non-zero if it is. The error
indicator may be cleared by the
clearerr function.
See also
Synopsis
Flush an output stream
Usage
Integer_Type fflush (File_Type fp)
Description
The
fflush function may be used to update the
output
stream specified by
fp . It returns
0 upon success, or
-1 upon failure and sets
errno accordingly. In
particular, this function will fail if
fp does not represent
an output stream, or if
fp is associated with a disk file and
there is insufficient disk space.
Example
This example illustrates how to use the
fflush function
without regard to the return value:
() = fputs ("Enter value> ", stdout);
() = fflush (stdout);
Notes
Many C programmers disregard the return value from the fflush
function. The above example illustrates how to properly do this in
the SLang langauge.
See also
Synopsis
Read a line from a file.
Usage
Integer_Type fgets (SLang_Ref_Type ref, File_Type fp)
Description
fgets reads a line from the open file specified by fp
and places the characters in the variable whose reference is
specified by ref .
It returns -1 if fp is not associated with an open file
or an attempt was made to read at the end the file; otherwise, it
returns the number of characters read.
Example
The following example returns the lines of a file via a linked list:
define read_file (file)
{
variable buf, fp, root, tail;
variable list_type = struct { text, next };
root = NULL;
fp = fopen(file, "r");
if (fp == NULL)
error("fopen %s failed." file);
while (-1 != fgets (&buf, fp))
{
if (root == NULL)
{
root = @list_type;
tail = root;
}
else
{
tail.next = @list_type;
tail = tail.next;
}
tail.text = buf;
tail.next = NULL;
}
() = fclose (fp);
return root;
}
See also
Synopsis
Read all the lines from an open file
Usage
String_Type[] fgetslines (File_Type fp)
Description
The fgetslines function returns all the remaining lines as an
array of strings in the file specified by the open file pointer
fp . If the file is empty, an empty string array will be
returned. The function returns NULL upon error.
Example
The following function returns the number of lines in a file:
define count_lines_in_file (file)
{
variable fp, lines;
fp = fopen (file, "r");
if (fp == NULL)
return -1;
lines = fgetslines (fp);
if (lines == NULL)
return -1;
return length (lines);
}
Note that the file was implicitly closed by the function.
Notes
This function should not be used if the file contains many lines
since that would require that all the lines be read into memory.
See also
Synopsis
Open a file
Usage
File_Type fopen (String_Type f, String_Type m)
Description
The
fopen function opens a file
f according to the mode
string
m . Allowed values for
m are:
"r" Read only
"w" Write only
"a" Append
"r+" Reading and writing at the beginning of the file.
"w+" Reading and writing. The file is created if it does not
exist; otherwise, it is truncated.
"a+" Reading and writing at the end of the file. The file is created
if it does not already exist.
In addition, the mode string can also include the letter
'b'
as the last character to indicate that the file is to be opened in
binary mode.
Upon success,
fopen a
File_Type object which is meant to
be used in other operations that require an open file. Upon
failure, the function returns
NULL .
Example
The following function opens a file in append mode and writes a
string to it:
define append_string_to_file (file, str)
{
variable fp = fopen (file, "a");
if (fp == NULL) verror ("%s could not be opened", file);
() = fputs (string, fp);
() = fclose (fp);
}
Note that the return values from
fputs and
fclose are
ignored.
Notes
There is no need to explicitly close a file opened with fopen .
If the returned File_Type object goes out of scope, SLang
will automatically close the file. However, explicitly closing a
file after use is recommended.
See also
Synopsis
Create and write a formatted string to a file
Usage
Int_Type fprintf (File_Type fp, String_Type fmt, ...)
Description
fprintf formats the objects specified by the variable argument
list according to the format
fmt and write the result to the
open file pointer
fp .
The format string obeys the same syntax and semantics as the
sprintf format string. See the description of the
sprintf function for more information.
fprintf returns the number of characters written to the file,
or \-1 upon error.
See also
Synopsis
Write a string to an open stream
Usage
Integer_Type fputs (String_Type s, File_Type fp);
Description
The
fputs function writes the string
s to the open file
pointer
fp . It returns -1 upon failure and sets
errno ,
otherwise it returns the length of the string.
Example
The following function opens a file in append mode and uses the
fputs function to write to it.
define append_string_to_file (str, file)
{
variable fp;
fp = fopen (file, "a");
if (fp == NULL) verror ("Unable to open %s", file);
if ((-1 == fputs (s, fp))
or (-1 == fclose (fp)))
verror ("Error writing to %s", file);
}
Notes
One must not disregard the return value from the
fputs
function, as many C programmers do. Doing so may lead to a stack
overflow error.
To write an object that contains embedded null characters, use the
fwrite function.
See also
Synopsis
Read binary data from a file
Usage
UInt_Type fread (Ref_Type b, DataType_Type t, UInt_Type n, File_Type fp)
Description
The fread function may be used to read n objects of type
t from an open file pointer fp . Upon success, it
returns the number of objects read from the file and places the
objects in the variable specified by b . Upon error or end of
file, it returns -1 . If more than one object is read from the
file, those objects will be placed in an array of the appropriate
size. The exception to this is when reading Char_Type or
UChar_Type objects from a file, in which case the data will be
returned as a BString_Type binary string.
Example
The following example illustrates how to read 50 bytes from a file:
define read_50_bytes_from_file (file)
{
variable fp, n, buf;
fp = fopen (file, "rb");
if (fp == NULL) error ("Open failed");
n = fread (&buf, Char_Type, 50, fp);
if (n == -1)
error ("fread failed");
() = fclose (fp);
return buf;
}
Notes
Use the
pack and
unpack functions to read data with a
specific byte-ordering.
See also
Synopsis
Reposition a stream
Usage
Integer_Type fseek (File_Type fp, Integer_Type ofs, Integer_Type whence
Description
The
fseek function may be used to reposition the file position
pointer associated with the open file stream
fp . Specifically,
it moves the pointer
ofs bytes relative to the position
indicated by
whence . If whence is set to one of the symbolic
constants
SEEK_SET ,
SEEK_CUR , or
SEEK_END , the
offset is relative to the start of the file, the current position
indicator, or end-of-file, respectively.
The function return zero upon success, or \-1 upon failure and sets
errno accordingly.
Example
define rewind (fp)
{
if (0 == fseek (fp, 0, SEEK_SET)) return;
vmessage ("rewind failed, reason: %s", errno_string (errno));
}
Notes
The current implementation uses an integer to specify the offset.
One some systems, a long integer may be required making this
function fail for very large files, i.e., files that are longer than
the maximum value of an integer.
See also
Synopsis
Obtain the current position in an open stream
Usage
Integer_Type ftell (File_Type fp)
Description
The ftell function may be used to obtain the current position in the
stream associated with the open file pointer
fp . It returns
the position of the pointer measured in bytes from the beginning of
the file. Upon error, it returns
-1 and sets
errno .
See also
Synopsis
Write binary data to a file
Usage
UInt_Type fwrite (b, File_Type fp)
Description
The
fwrite may be used to write the object represented by
b to an open file. If
b is a string or an array, the
function will attempt to write all elements of the object to the
file. It returns the number of objects successfully written,
otherwise it returns \-1 upon error and sets
errno
accordingly.
Example
The following example illustrates how to write an integer array to a
file. In this example,
fp is an open file descriptor:
variable a = [1:50]; % 50 element integer array
if (50 != fwrite (a, fp))
error ("fwrite failed");
Here is how to write the array one element at a time:
variable a = [1:50];
foreach (a)
{
variable ai = ();
if (1 != fwrite(ai, fp))
error ("fwrite failed");
}
Notes
Not all data types may support the fwrite operation. However,
it is supported by all vector, scalar, and string objects.
See also
Synopsis
Close an object opened with popen
Usage
Integer_Type pclose (File_Type fp)
Description
The pclose function waits for the process associated with
fp to exit and the returns the exit status of the command.
See also
Synopsis
Open a process
Usage
File_Type popen (String_Type cmd, String_Type mode)
Description
The popen function executes a process specified by cmd
and opens a unidirectional pipe to the newly created process. The
mode indicates whether or not the the pipe is open for reading
or writing. Specifically, if mode is "r" , then the
pipe is opened for reading, or if mode is "w" , then the
pipe will be open for writing.
Upon success, a File_Type pointer will be returned, otherwise
the function failed and NULL will be returned.
Notes
This function is not available on all systems.
See also
Synopsis
Create and write a formatted string to stdout
Usage
Int_Type printf (String_Type fmt, ...)
Description
fprintf formats the objects specified by the variable argument
list according to the format
fmt and write the result to
stdout . This function is equivalent to
fprintf used
with the
stdout file pointer. See
fprintf for more
information.
printf returns the number of characters written to the file,
or \-1 upon error.
Notes
Many C programmers do not check the return status of the
printf C library function. Make sure that if you do not care
about whether or not the function succeeds, then code it as in the
following example:
() = printf ("%s laid %d eggs\n", chicken_name, num_egg);
See also