Description: Documentation

## function clearerr

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

ferror , feof , fopen

## function fclose

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

fopen , fgets , fflush , pclose , errno

## function fdopen

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

fileno , fopen , open , close , fclose

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

ferror , clearerr , fopen

## function ferror

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

feof , clearerr , fopen

## function fflush

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

fopen , fclose

## function fgets

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

fopen , fclose , fputs , fread , error

## function fgetslines

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

fgets , fread , fopen

## function fopen

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

fclose , fgets , fputs , popen

## function fprintf

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

fputs , printf , fwrite , message

## function fputs

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

fclose , fopen , fgets , fwrite

## function fread

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

fwrite , fgets , fopen , pack , unpack

## function fseek

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

ftell , fopen

## function ftell

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

fseek , fopen

## function fwrite

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

fread , fputs , fopen , pack , unpack

## function pclose

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

pclose, fclose

## function popen

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

pclose , fopen

## function printf

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

fputs , printf, fwrite , message