/** @file ../include/stdio.h

@internalComponent

*/

/** @fn  clearerr(FILE *fp)

@param fp

Note: This description also covers the following functions -

 feof()  ferror()  fileno() 

  The function clearerr clears the end-of-file and error indicators for the stream pointed

to by fp.

 The function feof tests the end-of-file indicator for the stream pointed to by fp, returning non-zero if it is set.

The end-of-file indicator can only be cleared by the function clearerr.

 The function ferror tests the error indicator for the stream pointed to by fp, returning non-zero if it is set.

The error indicator can only be reset by the clearerr function.

 The function fileno examines the argument fp and returns its integer descriptor.

Examples:

@code

/* this program shows finding error set using ferror 

 * and clearing it using clearerr functions */

#include <stdio.h>

int main()

{

        char a;

        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughout the appln.

        	{

        	printf("Failed to set text-mode\n");

        	return -1;

        	}

        FILE* fp = fopen("c:\input.txt", "w");

        fprintf(fp, "%s", "abcdefghijklmn");

        fprintf(fp, "%c", '');

        fprintf(fp, "%s", "fdsfdsafsdabcdefghijklmn");

        fclose(fp);

        fp=fopen("c:\input.txt","r");

        if (fp == NULL)

                {

                printf("fopen failed");

                return -1;

                }

        else

                {

                fwrite(&a;, sizeof(char), 1, fp);

                if (ferror (fp))

                        printf("error set in file stream");

                else

                        {

                        fclose(fp);

                        return -1;

                        }

                clearerr(fp);

                if (!ferror(fp))

                        printf("error cleared in file stream");

                else printf("error still unexpected set in file stream");

                fclose (fp);

                }

        return 0;

}

@endcode

@code

Output

error set in file stream

error cleared in file stream

@endcode

@see open()

@see flockfile()

@see set_fmode() 

@publishedAll

@externallyDefinedApi

*/

/** @fn  fclose(FILE *fp)

@param fp

@return   Upon successful completion 0 is returned.

Otherwise, EOF is returned and the global variable errno is set to indicate the error.

In either case no further access to the stream is possible.

  The fclose function dissociates the named stream from its underlying file or set of functions. If the stream was 

being used for output any buffered data is written first using fflush .

Examples:

@code

/* this program shows opening and closing of a file using fclose api */

#include <stdio.h>

int main()

{

        FILE *fp;

        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughout the appln.

        	{

        	printf("Failed to set text-mode\n");

        	return -1;

        	}

        fp = fopen("c:\input.txt", "w+");

        if(fp == NULL)

                {               

                printf("file opening failed");

                return -1;

                }

        printf("file opened successfully: Perform file operations now");

        if(!fclose(fp))

                {

                printf("file closed successfully");

                return 0;

                }

        else

                {

                printf("file closing failed");

                return -1;

                }

}

@endcode

@code

Output

file opened successfully: Perform file operations now

file closed successfully

@endcode

Notes:

 The fclose function

does not handle NULL arguments; they will result in a segmentation

violation.

This is intentional - it makes it easier to make sure programs written

under are bug free. This behaviour is an implementation detail and programs should not 

rely upon it. 

@publishedAll

@externallyDefinedApi

*/

/** @fn  feof(FILE *fp)

@param fp

Refer to  clearerr() for the documentation

@see open()

@see flockfile()

@see set_fmode()

@publishedAll

@externallyDefinedApi

*/

/** @fn  ferror(FILE *fp)

@param fp

Refer to  clearerr() for the documentation

@see open()

@see flockfile()

@publishedAll

@externallyDefinedApi

*/

/** @fn  fseeko(FILE *stream, off_t offset, int whence)

@param stream

@param offset

@param whence

For full documentation see: http://opengroup.org/onlinepubs/007908775/xsh/fseek.html

@see fseek()

@publishedAll

@externallyDefinedApi

*/

/** @fn  fseeko64(FILE *stream, off64_t offset, int whence)

@param stream

@param offset

@param whence

For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0

@see fseeko()

@publishedAll

@externallyDefinedApi

*/

/** @fn  ftello(FILE *stream)

@param stream

For full documentation see: http://opengroup.org/onlinepubs/007908775/xsh/fseek.html

@see ftell()

@publishedAll

@externallyDefinedApi

*/

/** @fn  ftello64(FILE *stream)

@param stream

For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0

@see ftello()

@publishedAll

@externallyDefinedApi

*/

/** @fn  fflush(FILE *fp)

@param fp

@return   Upon successful completion 0 is returned.

Otherwise, EOF is returned and the global variable errno is set to indicate the error.

The function fflush forces a write of all buffered data for the given output or update fp via the stream's underlying write function.

The open status of the stream is unaffected.

 If the fp argument is NULL, fflush flushes all open output streams.

Examples:

@code

/* this program shows flushing user space buffered data using fflush */

#include <stdio.h>

int main()

{

        FILE *fp = NULL;

        int retval = 0;

        char name[20] = "c:\flush1.txt";

        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughout the appln.

        	{

        	printf("Failed to set text-mode\n");

        	return -1;

        	}

        fp = fopen(name, "w+"); 

        if(fp == NULL)

                {               

                printf("Error : File open");

                return -1;

                }

        setvbuf(fp, NULL, _IOFBF, 100);  // set to full buffering with NULL buffer      

        fprintf(fp, "we are trying to buffer 100 characters at once with NULL buffer.");

        retval = fflush(fp);

        if (retval)

                {               

                printf("fflush failed");

                fclose(fp);

                unlink(name);

                return -1;

                }

        else printf("Buffer successfully flushed");

        fclose(fp);

        unlink(name);

        return 0;

}

@endcode

@code

Output

we are trying to buffer 100 characters at once with NULL buffer.

Buffer successfully flushed

@endcode

@see write()

@see fclose()

@see fopen()

@see setbuf()

@see set_fmode()

@publishedAll

@externallyDefinedApi

*/

/** @fn  fgetc(FILE *fp)

@param fp

Note: This description also covers the following functions -

 getc()  getc_unlocked()  getchar()  getchar_unlocked()  getw() 

@return   If successful, these routines return the next requested object

from the stream. Character values are returned as an unsigned char converted to an int. 

If the stream is at end-of-file or a read error occurs,

the routines return EOF. The routines and ferror must be used to distinguish between end-of-file and error.

If an error occurs, the global variable errno is set to indicate the error.

The end-of-file condition is remembered, even on a terminal, and all

subsequent attempts to read will return EOF until the condition is cleared with

  The fgetc function

obtains the next input character (if present) from the stream pointed at by stream, or the next character pushed back on the stream via ungetc.

 The getc function

acts essentially identically to fgetc, but is a macro that expands in-line.

 The getchar function

is equivalent to getc (stdin.);

 The getw function

obtains the next int

(if present)

from the stream pointed at by stream.

 The getc_unlocked and getchar_unlocked functions are equivalent to getc and getchar respectively,

except that the caller is responsible for locking the stream

with flockfile before calling them.

These functions may be used to avoid the overhead of locking the stream

for each character, and to avoid input being dispersed among multiple

threads reading from the same stream.

Examples:

@code

/* this program shows reading from file using getc */

/* consider input.txt has the following content: */

/* hi */

#include <stdio.h>

int main(void)

{

        int retval;

        FILE *fp = NULL;

        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughout the appln.

        	{

        	printf("Failed to set text-mode\n");

        	return -1;

        	}

        fp = fopen("c:\input.txt", "w");

        fprintf(fp, "%s", "abcdefghijklmn");

        fprintf(fp, "%c", '\n');

        fprintf(fp, "%s", "fdsfdsafsdabcdefghijklmn");

        fclose(fp);

        fp = fopen("C:\input.txt","r");

        if(fp == NULL)

        {

        printf("fopen failed");

        return -1;

        }

        while((int)(retval = getc(fp) )!= EOF)

        {

        printf("%c", retval);

        }

        fclose(fp);

        return 0;

}

@endcode

@code

Output

hi

@endcode

@see ferror()

@see flockfile()

@see fopen()

@see fread()

@see getwc()

@see putc()

@see ungetc()

@see set_fmode()

@publishedAll

@externallyDefinedApi

*/

/** @fn  fgetpos(FILE * fp, fpos_t * pos)

@param fp

@param pos

Refer to  fseek() for the documentation

@see lseek()

@see ungetc()

@see ungetwc()

@publishedAll

@externallyDefinedApi

*/

/** @fn  fgetpos64(FILE * fp, fpos64_t * pos)

@param fp

@param pos

For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0

@see fgetpos()

@publishedAll

@externallyDefinedApi

*/

/** @fn  fgets(char *buf, int n, FILE *fp)

@param buf

@param n

@param fp

Note: This description also covers the following functions -

 gets() 

@return   Upon successful completion fgets and gets return a pointer to the string. If end-of-file occurs before any 

characters are read they return NULL and the buffer contents remain unchanged. If an error occurs they 

return NULL and the buffer contents are indeterminate. The fgets and gets functions do not distinguish between end-of-file and error and 

callers must use feof and ferror to determine which occurred.

  The fgets function reads at most one less than the number of characters 

specified by n from the given stream and stores them in the string buf. Reading stops when a newline character is found, at end-of-file or 

error. The newline, if any, is retained. If any characters are read, and there is no error, a \\0 character is appended to end the string.

The gets function is equivalent to fgets with an infinite size and a stream of stdin,

except that the newline character (if any) is not stored in the string.

It is the caller's responsibility to ensure that the input line,if any, is sufficiently short to fit in the string.

Examples:

@code

/* this program shows reading characters from a file using fgets */

/* consider input.txt has the following content: */

/* abcdefghijklmn */

/* fdsfdsafsdabcdefghijklmn */

#include <stdio.h>

int main(void)

{

        char buf[20];

        FILE *fp = NULL;

        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughout the appln.

        	{

        	printf("Failed to set text-mode\n");

        	return -1;

        	}

       	fp = fopen("c:\input.txt", "w");

        fprintf(fp, "%s", "abcdefghijklmn");

        fprintf(fp, "%c", "");

        fprintf(fp, "%s", "fdsfdsafsdabcdefghijklmn");

        fclose(fp);

        fp = fopen("C:\input.txt","r");

        if(fp == NULL)

                {

                printf("fopen failed");

                return -1;

                }

        if(fgets(buf,18,fp) != NULL)

                printf("%s", buf);

        else

                printf("Buffer is empty");

        buf[0] = '\0';

        if(fgets(buf,2,fp) != NULL)

                printf("%s", buf);

        else

                printf("Buffer is empty");

        fclose(fp);     

        return 0;

}

@endcode

@code

Output

abcdefghijklmn

fdsfdsafsdabcdefghijklmn

@endcode

Security considerations:

 The gets function cannot be used securely.

Because of its lack of bounds checking,and the inability for the calling program

to reliably determine the length of the next incoming line,the use of this function enables malicious users

to arbitrarily change a running program's functionality through a buffer overflow attack.

It is strongly suggested that the fgets function be used in all cases.

@see feof()

@see ferror()

@see fgetln()

@see set_fmode()

@publishedAll

@externallyDefinedApi

*/

/** @fn  fopen(const char *file, const char *mode)

@param file

@param mode

Note: This description also covers the following functions -

 fdopen()  freopen() 

@return   Upon successful completion fopen, fdopen and freopen return a FILE pointer.

Otherwise, NULL is returned and the global variable errno is set to indicate the error.

 Note: To open file in text-mode use set_fmode() prior to fopen() or at the start of appln. Default file opening mode in symbian is binary. 

       For more details, see set_fmode(). 

The  fopen function opens the file whose name is the string pointed to by  file and associates a stream with it.

The argument mode points to a string beginning with one of the following sequences (Additional characters may follow these sequences.):

@code

"r" 	Open file in text mode if text-mode is set using set_fmode(), otherwise opens in default binary mode for reading. The stream is positioned at the beginning of the file.

"r+" 	Open file in text mode if text-mode is set using set_fmode(), otherwise opens in default binary mode for reading and writing. The stream is positioned at the beginning of the file.

"w" 	Truncate to zero length or create file in text mode if text-mode is set using set_fmode(), otherwise opens in default binary mode for writing. The stream is positioned at the beginning of the file.

"w+" 	Open file in text mode if text-mode is set using set_fmode(), otherwise opens in default binary mode for reading and writing. The file is created if it does not exist, otherwise it is truncated. The stream is positioned at the beginning of the file.

"a" 	Open file in text mode if text-mode is set using set_fmode(), otherwise opens in default binary mode for writing. The file is created if it does not exist. The stream is positioned at the end of the file. Subsequent writes to the file will always end up at the then current end of file, irrespective of any intervening fseek or similar.

"a+" 	Open file in text mode if text-mode is set using set_fmode(), otherwise opens in default binary mode for reading and writing. The file is created if it does not exist. The stream is positioned at the end of the file. Subsequent writes to the file will always end up at the then current end of file, irrespective of any intervening fseek or similar.

@endcode

The mode string can also include the letter "b" either as a third character or as a character between the characters in any of the two-character strings described above while explicitly specifying binary mode.

The mode string can also include the letter "t" either as a third character or as a character between the characters in any of the two-character strings described above while explicitly specifying text mode.

Reads and writes may be intermixed on read/write streams in any order, and do not require an intermediate seek as in previous versions of stdio. This is not portable to other systems, however; ANSI C requires that a file positioning function intervene between output and input, unless an input operation encounters end-of-file.

The fdopen function associates a stream with the existing file descriptor, fildes. The mode of the stream must be compatible with the mode of the file descriptor. When the stream is closed via fclose, fildes is closed also.

The freopen function opens the file whose name is the string pointed to by path and associates the stream pointed to by stream with it. The original stream (if it exists) is closed. The mode argument is used just as in the fopen function.

If the file argument is NULL, freopen attempts to re-open the file associated with stream with a new mode. The new mode must be compatible with the mode that the stream was originally opened with:

@code

    * Streams originally opened with mode "r" can only be reopened with that same mode.