<!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>