<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE> S-Lang Run-Time Library Reference: Version 1.4.0: Stdio File I/O Functions</TITLE>
<LINK HREF="slangfun-11.html" REL=next>
<LINK HREF="slangfun-9.html" REL=previous>
<LINK HREF="slangfun.html#toc10" REL=contents>
</HEAD>
<BODY>
<A HREF="slangfun-11.html">Next</A>
<A HREF="slangfun-9.html">Previous</A>
<A HREF="slangfun.html#toc10">Contents</A>
<HR>
<H2><A NAME="s10">10. Stdio File I/O Functions</A></H2>
<P>
<H2><A NAME="clearerr"></A> <A NAME="ss10.1">10.1 <B>clearerr</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Clear the error of a file stream
<DT><B> Usage </B><DD><P><CODE>clearerr (File_Type fp</CODE>
<DT><B> Description </B><DD><P>The <CODE>clearerr</CODE> function clears the error and end-of-file flags
associated with the open file stream <CODE>fp</CODE>.
<DT><B> See Also </B><DD><P><CODE>ferror, feof, fopen</CODE>
</DL>
<P>
<P>
<H2><A NAME="fclose"></A> <A NAME="ss10.2">10.2 <B>fclose</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Close a file
<DT><B> Usage </B><DD><P><CODE>Integer_Type fclose (File_Type fp)</CODE>
<DT><B> Description </B><DD><P>The <CODE>fclose</CODE> function may be used to close an open file pointer
<CODE>fp</CODE>. Upon success it returns zero, and upon failure it sets
<CODE>errno</CODE> and returns <CODE>-1</CODE>. Failure usually indicates a that
the file system is full or that <CODE>fp</CODE> does not refer to an open file.
<DT><B> Notes </B><DD><P>Many C programmers call <CODE>fclose</CODE> without checking the return
value. The <B>S-lang</B> language requires the programmer to explicitly
handle any value returned by a <B>S-lang</B> function. The simplest way to
handle the return value from <CODE>fclose</CODE> is to use it as:
<BLOCKQUOTE><CODE>
<PRE>
() = fclose (fp);
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>fopen, fgets, fflush, pclose, errno</CODE>
</DL>
<P>
<P>
<H2><A NAME="fdopen"></A> <A NAME="ss10.3">10.3 <B>fdopen</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Convert a FD_Type file descriptor to a stdio File_Type object
<DT><B> Usage </B><DD><P><CODE>File_Type fdopen (FD_Type, String_Type mode)</CODE>
<DT><B> Description </B><DD><P>The <CODE>fdopen</CODE> function creates and returns a stdio
<CODE>File_Type</CODE> object from the open <CODE>FD_Type</CODE>
descriptor <CODE>fd</CODE>. The <CODE>mode</CODE> parameter corresponds to the
<CODE>mode</CODE> parameter of the <CODE>fopen</CODE> function and must be
consistent with the mode of the descriptor <CODE>fd</CODE>. The function
returns <CODE>NULL</CODE> upon failure and sets <CODE>errno</CODE>.
<DT><B> Notes </B><DD><P>The <CODE>fclose</CODE> function does not close the <CODE>File_Type</CODE> object
returned from this function. The underlying file object must be
closed by the <CODE>close</CODE> function.
<DT><B> See Also </B><DD><P><CODE>fileno, fopen, open, close, fclose</CODE>
</DL>
<P>
<P>
<H2><A NAME="feof"></A> <A NAME="ss10.4">10.4 <B>feof</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Get the end-of-file status
<DT><B> Usage </B><DD><P><CODE>Integer_Type feof (File_Type fp)</CODE>
<DT><B> Description </B><DD><P>This function may be used to determine the state of the end-of-file
indicator of the open file descriptor <CODE>fp</CODE>. It returns <CODE>0</CODE>
if the indicator is not set, or non-zero if it is. The end-of-file
indicator may be cleared by the <CODE>clearerr</CODE> function.
<DT><B> See Also </B><DD><P><CODE>ferror, clearerr, fopen</CODE>
</DL>
<P>
<P>
<H2><A NAME="ferror"></A> <A NAME="ss10.5">10.5 <B>ferror</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Determine the error status of an open file descriptor
<DT><B> Usage </B><DD><P><CODE>Integer_Type ferror (File_Type fp)</CODE>
<DT><B> Description </B><DD><P>This function may be used to determine the state of the error
indicator of the open file descriptor <CODE>fp</CODE>. It returns <CODE>0</CODE>
if the indicator is not set, or non-zero if it is. The error
indicator may be cleared by the <CODE>clearerr</CODE> function.
<DT><B> See Also </B><DD><P><CODE>feof, clearerr, fopen</CODE>
</DL>
<P>
<P>
<H2><A NAME="fflush"></A> <A NAME="ss10.6">10.6 <B>fflush</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Flush an output stream
<DT><B> Usage </B><DD><P><CODE>Integer_Type fflush (File_Type fp)</CODE>
<DT><B> Description </B><DD><P>The <CODE>fflush</CODE> function may be used to update the <EM>output</EM>
stream specified by <CODE>fp</CODE>. It returns <CODE>0</CODE> upon success, or
<CODE>-1</CODE> upon failure and sets <CODE>errno</CODE> accordingly. In
particular, this function will fail if <CODE>fp</CODE> does not represent
an output stream, or if <CODE>fp</CODE> is associated with a disk file and
there is insufficient disk space.
<DT><B> Example </B><DD><P>This example illustrates how to use the <CODE>fflush</CODE> function
without regard to the return value:
<BLOCKQUOTE><CODE>
<PRE>
() = fputs ("Enter value> ", stdout);
() = fflush (stdout);
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Notes </B><DD><P>Many C programmers disregard the return value from the <CODE>fflush</CODE>
function. The above example illustrates how to properly do this in
the <B>S-lang</B> langauge.
<DT><B> See Also </B><DD><P><CODE>fopen, fclose</CODE>
</DL>
<P>
<P>
<H2><A NAME="fgets"></A> <A NAME="ss10.7">10.7 <B>fgets</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Read a line from a file.
<DT><B> Usage </B><DD><P><CODE>Integer_Type fgets (SLang_Ref_Type ref, File_Type fp)</CODE>
<DT><B> Description </B><DD><P><CODE>fgets</CODE> reads a line from the open file specified by <CODE>fp</CODE>
and places the characters in the variable whose reference is
specified by <CODE>ref</CODE>.
It returns <CODE>-1</CODE> if <CODE>fp</CODE> 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.
<DT><B> Example </B><DD><P>The following example returns the lines of a file via a linked list:
<BLOCKQUOTE><CODE>
<PRE>
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;
}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>fopen, fclose, fputs, fread, error</CODE>
</DL>
<P>
<P>
<H2><A NAME="fgetslines"></A> <A NAME="ss10.8">10.8 <B>fgetslines</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Read all the lines from an open file
<DT><B> Usage </B><DD><P><CODE>String_Type[] fgetslines (File_Type fp)</CODE>
<DT><B> Description </B><DD><P>The <CODE>fgetslines</CODE> function returns all the remaining lines as an
array of strings in the file specified by the open file pointer
<CODE>fp</CODE>. If the file is empty, an empty string array will be
returned. The function returns <CODE>NULL</CODE> upon error.
<DT><B> Example </B><DD><P>The following function returns the number of lines in a file:
<BLOCKQUOTE><CODE>
<PRE>
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);
}
</PRE>
</CODE></BLOCKQUOTE>
Note that the file was implicitly closed by the function.
<DT><B> Notes </B><DD><P>This function should not be used if the file contains many lines
since that would require that all the lines be read into memory.
<DT><B> See Also </B><DD><P><CODE>fgets, fread, fopen</CODE>
</DL>
<P>
<P>
<H2><A NAME="fopen"></A> <A NAME="ss10.9">10.9 <B>fopen</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Open a file
<DT><B> Usage </B><DD><P><CODE>File_Type fopen (String_Type f, String_Type m)</CODE>
<DT><B> Description </B><DD><P>The <CODE>fopen</CODE> function opens a file <CODE>f</CODE> according to the mode
string <CODE>m</CODE>. Allowed values for <CODE>m</CODE> are:
<BLOCKQUOTE><CODE>
<PRE>
"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.
</PRE>
</CODE></BLOCKQUOTE>
In addition, the mode string can also include the letter <CODE>'b'</CODE>
as the last character to indicate that the file is to be opened in
binary mode.
<P>Upon success, <CODE>fopen</CODE> a <CODE>File_Type</CODE> object which is meant to
be used in other operations that require an open file. Upon
failure, the function returns <CODE>NULL</CODE>.
<DT><B> Example </B><DD><P>The following function opens a file in append mode and writes a
string to it:
<BLOCKQUOTE><CODE>
<PRE>
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);
}
</PRE>
</CODE></BLOCKQUOTE>
Note that the return values from <CODE>fputs</CODE> and <CODE>fclose</CODE> are
ignored.
<DT><B> Notes </B><DD><P>There is no need to explicitly close a file opened with <CODE>fopen</CODE>.
If the returned <CODE>File_Type</CODE> object goes out of scope, <B>S-lang</B>
will automatically close the file. However, explicitly closing a
file after use is recommended.
<DT><B> See Also </B><DD><P><CODE>fclose, fgets, fputs, popen</CODE>
</DL>
<P>
<P>
<H2><A NAME="fprintf"></A> <A NAME="ss10.10">10.10 <B>fprintf</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Create and write a formatted string to a file
<DT><B> Usage </B><DD><P><CODE>Int_Type fprintf (File_Type fp, String_Type fmt, ...)</CODE>
<DT><B> Description </B><DD><P><CODE>fprintf</CODE> formats the objects specified by the variable argument
list according to the format <CODE>fmt</CODE> and write the result to the
open file pointer <CODE>fp</CODE>.
<P>The format string obeys the same syntax and semantics as the
<CODE>sprintf</CODE> format string. See the description of the
<CODE>sprintf</CODE> function for more information.
<P><CODE>fprintf</CODE> returns the number of characters written to the file,
or <CODE>-1</CODE> upon error.
<DT><B> See Also </B><DD><P><CODE>fputs, printf, fwrite, message</CODE>
</DL>
<P>
<P>
<H2><A NAME="fputs"></A> <A NAME="ss10.11">10.11 <B>fputs</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Write a string to an open stream
<DT><B> Usage </B><DD><P><CODE>Integer_Type fputs (String_Type s, File_Type fp);</CODE>
<DT><B> Description </B><DD><P>The <CODE>fputs</CODE> function writes the string <CODE>s</CODE> to the open file
pointer <CODE>fp</CODE>. It returns -1 upon failure and sets <CODE>errno</CODE>,
otherwise it returns the length of the string.
<DT><B> Example </B><DD><P>The following function opens a file in append mode and uses the
<CODE>fputs</CODE> function to write to it.
<BLOCKQUOTE><CODE>
<PRE>
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);
}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Notes </B><DD><P>One must not disregard the return value from the <CODE>fputs</CODE>
function, as many C programmers do. Doing so may lead to a stack
overflow error.
<P>To write an object that contains embedded null characters, use the
<CODE>fwrite</CODE> function.
<DT><B> See Also </B><DD><P><CODE>fclose, fopen, fgets, fwrite</CODE>
</DL>
<P>
<P>
<H2><A NAME="fread"></A> <A NAME="ss10.12">10.12 <B>fread</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Read binary data from a file
<DT><B> Usage </B><DD><P><CODE>UInt_Type fread (Ref_Type b, DataType_Type t, UInt_Type n, File_Type fp)</CODE>
<DT><B> Description </B><DD><P>The <CODE>fread</CODE> function may be used to read <CODE>n</CODE> objects of type
<CODE>t</CODE> from an open file pointer <CODE>fp</CODE>. Upon success, it
returns the number of objects read from the file and places the
objects in the variable specified by <CODE>b</CODE>. Upon error or end of
file, it returns <CODE>-1</CODE>. 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 <CODE>Char_Type</CODE> or
<CODE>UChar_Type</CODE> objects from a file, in which case the data will be
returned as a BString_Type binary string.
<DT><B> Example </B><DD><P>The following example illustrates how to read 50 bytes from a file:
<BLOCKQUOTE><CODE>
<PRE>
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;
}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Notes </B><DD><P>Use the <CODE>pack</CODE> and <CODE>unpack</CODE> functions to read data with a
specific byte-ordering.
<DT><B> See Also </B><DD><P><CODE>fwrite, fgets, fopen, pack, unpack</CODE>
</DL>
<P>
<P>
<H2><A NAME="fseek"></A> <A NAME="ss10.13">10.13 <B>fseek</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Reposition a stream
<DT><B> Usage </B><DD><P><CODE>Integer_Type fseek (File_Type fp, Integer_Type ofs, Integer_Type whence</CODE>
<DT><B> Description </B><DD><P>The <CODE>fseek</CODE> function may be used to reposition the file position
pointer associated with the open file stream <CODE>fp</CODE>. Specifically,
it moves the pointer <CODE>ofs</CODE> bytes relative to the position
indicated by <CODE>whence</CODE>. If whence is set to one of the symbolic
constants <CODE>SEEK_SET</CODE>, <CODE>SEEK_CUR</CODE>, or <CODE>SEEK_END</CODE>, the
offset is relative to the start of the file, the current position
indicator, or end-of-file, respectively.
<P>The function return zero upon success, or <CODE>-1</CODE> upon failure and sets
<CODE>errno</CODE> accordingly.
<DT><B> Example </B><DD><P>define rewind (fp)
{
if (0 == fseek (fp, 0, SEEK_SET)) return;
vmessage ("rewind failed, reason: %s", errno_string (errno));
}
<DT><B> Notes </B><DD><P>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.
<DT><B> See Also </B><DD><P><CODE>ftell, fopen</CODE>
</DL>
<P>
<P>
<H2><A NAME="ftell"></A> <A NAME="ss10.14">10.14 <B>ftell</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Obtain the current position in an open stream
<DT><B> Usage </B><DD><P><CODE>Integer_Type ftell (File_Type fp)</CODE>
<DT><B> Description </B><DD><P>The ftell function may be used to obtain the current position in the
stream associated with the open file pointer <CODE>fp</CODE>. It returns
the position of the pointer measured in bytes from the beginning of
the file. Upon error, it returns <CODE>-1</CODE> and sets <CODE>errno</CODE>.
<DT><B> See Also </B><DD><P><CODE>fseek, fopen</CODE>
</DL>
<P>
<P>
<H2><A NAME="fwrite"></A> <A NAME="ss10.15">10.15 <B>fwrite</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Write binary data to a file
<DT><B> Usage </B><DD><P><CODE>UInt_Type fwrite (b, File_Type fp)</CODE>
<DT><B> Description </B><DD><P>The <CODE>fwrite</CODE> may be used to write the object represented by
<CODE>b</CODE> to an open file. If <CODE>b</CODE> 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 <CODE>-1</CODE> upon error and sets <CODE>errno</CODE>
accordingly.
<DT><B> Example </B><DD><P>The following example illustrates how to write an integer array to a
file. In this example, <CODE>fp</CODE> is an open file descriptor:
<BLOCKQUOTE><CODE>
<PRE>
variable a = [1:50]; % 50 element integer array
if (50 != fwrite (a, fp))
error ("fwrite failed");
</PRE>
</CODE></BLOCKQUOTE>
Here is how to write the array one element at a time:
<BLOCKQUOTE><CODE>
<PRE>
variable a = [1:50];
foreach (a)
{
variable ai = ();
if (1 != fwrite(ai, fp))
error ("fwrite failed");
}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Notes </B><DD><P>Not all data types may support the <CODE>fwrite</CODE> operation. However,
it is supported by all vector, scalar, and string objects.
<DT><B> See Also </B><DD><P><CODE>fread, fputs, fopen, pack, unpack</CODE>
</DL>
<P>
<P>
<H2><A NAME="pclose"></A> <A NAME="ss10.16">10.16 <B>pclose</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Close an object opened with popen
<DT><B> Usage </B><DD><P><CODE>Integer_Type pclose (File_Type fp)</CODE>
<DT><B> Description </B><DD><P>The <CODE>pclose</CODE> function waits for the process associated with
<CODE>fp</CODE> to exit and the returns the exit status of the command.
<DT><B> See Also </B><DD><P><CODE>pclose, fclose</CODE>
</DL>
<P>
<P>
<H2><A NAME="popen"></A> <A NAME="ss10.17">10.17 <B>popen</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Open a process
<DT><B> Usage </B><DD><P><CODE>File_Type popen (String_Type cmd, String_Type mode)</CODE>
<DT><B> Description </B><DD><P>The <CODE>popen</CODE> function executes a process specified by <CODE>cmd</CODE>
and opens a unidirectional pipe to the newly created process. The
<CODE>mode</CODE> indicates whether or not the the pipe is open for reading
or writing. Specifically, if <CODE>mode</CODE> is <CODE>"r"</CODE>, then the
pipe is opened for reading, or if <CODE>mode</CODE> is <CODE>"w"</CODE>, then the
pipe will be open for writing.
<P>Upon success, a <CODE>File_Type</CODE> pointer will be returned, otherwise
the function failed and <CODE>NULL</CODE> will be returned.
<DT><B> Notes </B><DD><P>This function is not available on all systems.
<DT><B> See Also </B><DD><P><CODE>pclose, fopen</CODE>
</DL>
<P>
<P>
<H2><A NAME="printf"></A> <A NAME="ss10.18">10.18 <B>printf</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Create and write a formatted string to stdout
<DT><B> Usage </B><DD><P><CODE>Int_Type printf (String_Type fmt, ...)</CODE>
<DT><B> Description </B><DD><P><CODE>fprintf</CODE> formats the objects specified by the variable argument
list according to the format <CODE>fmt</CODE> and write the result to
<CODE>stdout</CODE>. This function is equivalent to <CODE>fprintf</CODE> used
with the <CODE>stdout</CODE> file pointer. See <CODE>fprintf</CODE> for more
information.
<P><CODE>printf</CODE> returns the number of characters written to the file,
or <CODE>-1</CODE> upon error.
<DT><B> Notes </B><DD><P>Many C programmers do not check the return status of the
<CODE>printf</CODE> 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:
<BLOCKQUOTE><CODE>
<PRE>
() = printf ("%s laid %d eggs\n", chicken_name, num_egg);
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>fputs, printf, fwrite, message</CODE>
</DL>
<P>
<P>
<P>
<HR>
<A HREF="slangfun-11.html">Next</A>
<A HREF="slangfun-9.html">Previous</A>
<A HREF="slangfun.html#toc10">Contents</A>
</BODY>
</HTML>
