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

     2 @internalComponent

     3 */

     4 

     5 /** @fn  clearerr(FILE *fp)

     6 @param fp

     7 

     8 Note: This description also covers the following functions -

     9  feof()  ferror()  fileno() 

    10 

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

    12 to by fp.

    13 

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

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

    16 

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

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

    19 

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

    21  

    22 Examples:

    23 @code

    24 /* this program shows finding error set using ferror 

    25  * and clearing it using clearerr functions */

    26 #include <stdio.h>

    27 int main()

    28 {

    29         char a;

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

    31         	{

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

    33         	return -1;

    34         	}

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

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

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

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

    39         fclose(fp);

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

    41         if (fp == NULL)

    42                 {

    43                 printf("fopen failed");

    44                 return -1;

    45                 }

    46         else

    47                 {

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

    49                 if (ferror (fp))

    50                         printf("error set in file stream");

    51                 else

    52                         {

    53                         fclose(fp);

    54                         return -1;

    55                         }

    56                 clearerr(fp);

    57                 if (!ferror(fp))

    58                         printf("error cleared in file stream");

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

    60                 fclose (fp);

    61                 }

    62         return 0;

    63 }

    64 

    65 @endcode

    66 @code

    67 Output

    68 

    69 error set in file stream

    70 error cleared in file stream

    71 

    72 @endcode

    73 @see open()

    74 @see flockfile()

    75 @see set_fmode() 

    76 

    77 @publishedAll

    78 @externallyDefinedApi

    79 */

    80 

    81 /** @fn  fclose(FILE *fp)

    82 @param fp

    83 @return   Upon successful completion 0 is returned.

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

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

    86 

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

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

    89 

    90 Examples:

    91 @code

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

    93 #include <stdio.h>

    94 int main()

    95 {

    96         FILE *fp;

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

    98         	{

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

   100         	return -1;

   101         	}

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

   103         if(fp == NULL)

   104                 {               

   105                 printf("file opening failed");

   106                 return -1;

   107                 }

   108         

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

   110         

   111         if(!fclose(fp))

   112                 {

   113                 printf("file closed successfully");

   114                 return 0;

   115                 }

   116         else

   117                 {

   118                 printf("file closing failed");

   119                 return -1;

   120                 }

   121 }

   122 

   123 @endcode

   124 @code

   125 Output

   126 

   127 file opened successfully: Perform file operations now

   128 file closed successfully

   129 

   130 @endcode

   131 

   132 Notes:

   133 

   134  The fclose function

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

   136 violation.

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

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

   139 rely upon it. 

   140  

   141 

   142 @publishedAll

   143 @externallyDefinedApi

   144 */

   145 

   146 /** @fn  feof(FILE *fp)

   147 @param fp

   148 

   149 Refer to  clearerr() for the documentation

   150 @see open()

   151 @see flockfile()

   152 @see set_fmode()

   153 

   154  

   155 

   156 @publishedAll

   157 @externallyDefinedApi

   158 */

   159 

   160 /** @fn  ferror(FILE *fp)

   161 @param fp

   162 

   163 Refer to  clearerr() for the documentation

   164 @see open()

   165 @see flockfile()

   166  

   167 

   168 @publishedAll

   169 @externallyDefinedApi

   170 */

   171 

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

   173 @param stream

   174 @param offset

   175 @param whence

   176 

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

   178 

   179 @see fseek()

   180  

   181 @publishedAll

   182 @externallyDefinedApi

   183 */

   184 

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

   186 @param stream

   187 @param offset

   188 @param whence

   189 

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

   191 

   192 @see fseeko()

   193  

   194 @publishedAll

   195 @externallyDefinedApi

   196 */

   197 

   198 /** @fn  ftello(FILE *stream)

   199 @param stream

   200 

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

   202 

   203 @see ftell()

   204  

   205 @publishedAll

   206 @externallyDefinedApi

   207 */

   208 

   209 /** @fn  ftello64(FILE *stream)

   210 @param stream

   211 

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

   213 

   214 @see ftello()

   215  

   216 @publishedAll

   217 @externallyDefinedApi

   218 */

   219 

   220 /** @fn  fflush(FILE *fp)

   221 @param fp

   222 

   223 @return   Upon successful completion 0 is returned.

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

   225 

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

   227 The open status of the stream is unaffected.

   228 

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

   230  

   231 Examples:

   232 @code

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

   234 #include <stdio.h>

   235 int main()

   236 {

   237         FILE *fp = NULL;

   238         int retval = 0;

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

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

   241         	{

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

   243         	return -1;

   244         	}

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

   246         if(fp == NULL)

   247                 {               

   248                 printf("Error : File open");

   249                 return -1;

   250                 }

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

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

   253         

   254         retval = fflush(fp);

   255         if (retval)

   256                 {               

   257                 printf("fflush failed");

   258                 fclose(fp);

   259                 unlink(name);

   260                 return -1;

   261                 }

   262         else printf("Buffer successfully flushed");

   263         fclose(fp);

   264         unlink(name);

   265         return 0;

   266 }

   267 

   268 @endcode

   269 @code

   270 Output

   271 

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

   273 Buffer successfully flushed

   274 

   275 @endcode

   276 @see write()

   277 @see fclose()

   278 @see fopen()

   279 @see setbuf()

   280 @see set_fmode()

   281  

   282 

   283 @publishedAll

   284 @externallyDefinedApi

   285 */

   286 

   287 /** @fn  fgetc(FILE *fp)

   288 @param fp

   289 

   290 Note: This description also covers the following functions -

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

   292 

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

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

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

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

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

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

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

   300 

   301   The fgetc function

   302 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.

   303 

   304  The getc function

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

   306 

   307  The getchar function

   308 is equivalent to getc (stdin.);

   309 

   310  The getw function

   311 obtains the next int

   312 (if present)

   313 from the stream pointed at by stream.

   314 

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

   316 except that the caller is responsible for locking the stream

   317 with flockfile before calling them.

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

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

   320 threads reading from the same stream.

   321 

   322 Examples:

   323 @code

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

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

   326 /* hi */

   327 #include <stdio.h>

   328 int main(void)

   329 {

   330         int retval;

   331         FILE *fp = NULL;

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

   333         	{

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

   335         	return -1;

   336         	}

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

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

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

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

   341         fclose(fp);

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

   343         if(fp == NULL)

   344         {

   345         printf("fopen failed");

   346         return -1;

   347         }

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

   349         {

   350         printf("%c", retval);

   351         }

   352         fclose(fp);

   353         return 0;

   354 }

   355 

   356 @endcode

   357 @code

   358 Output

   359 

   360 hi

   361 

   362 @endcode

   363 @see ferror()

   364 @see flockfile()

   365 @see fopen()

   366 @see fread()

   367 @see getwc()

   368 @see putc()

   369 @see ungetc()

   370 @see set_fmode()

   371  

   372 

   373 @publishedAll

   374 @externallyDefinedApi

   375 */

   376 

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

   378 @param fp

   379 @param pos

   380 Refer to  fseek() for the documentation

   381 @see lseek()

   382 @see ungetc()

   383 @see ungetwc()

   384  

   385 

   386 @publishedAll

   387 @externallyDefinedApi

   388 */

   389 

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

   391 @param fp

   392 @param pos

   393 

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

   395 

   396 

   397 @see fgetpos()

   398 

   399 @publishedAll

   400 @externallyDefinedApi

   401 */

   402 

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

   404 @param buf

   405 @param n

   406 @param fp

   407 

   408 Note: This description also covers the following functions -

   409  gets() 

   410 

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

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

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

   414 callers must use feof and ferror to determine which occurred.

   415 

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

   417 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 

   418 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.

   419 

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

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

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

   423 

   424 Examples:

   425 @code

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

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

   428 /* abcdefghijklmn */

   429 /* fdsfdsafsdabcdefghijklmn */

   430 #include <stdio.h>

   431 int main(void)

   432 {

   433         char buf[20];

   434         FILE *fp = NULL;

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

   436         	{

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

   438         	return -1;

   439         	}

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

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

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

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

   444         fclose(fp);

   445                 

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

   447         if(fp == NULL)

   448                 {

   449                 printf("fopen failed");

   450                 return -1;

   451                 }

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

   453                 printf("%s", buf);

   454         else

   455                 printf("Buffer is empty");

   456         

   457         buf[0] = '\0';

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

   459                 printf("%s", buf);

   460         else

   461                 printf("Buffer is empty");

   462         fclose(fp);     

   463         return 0;

   464 }

   465 

   466 @endcode

   467 @code

   468 Output

   469 

   470 abcdefghijklmn

   471 fdsfdsafsdabcdefghijklmn

   472 

   473 @endcode

   474 

   475 Security considerations:

   476 

   477  The gets function cannot be used securely.

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

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

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

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

   482 @see feof()

   483 @see ferror()

   484 @see fgetln()

   485 @see set_fmode()

   486  

   487 

   488 @publishedAll

   489 @externallyDefinedApi

   490 */

   491 

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

   493 @param file

   494 @param mode

   495 

   496 Note: This description also covers the following functions -

   497  fdopen()  freopen() 

   498 

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

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

   501 

   502  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. 

   503        For more details, see set_fmode(). 

   504 	          

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

   506 

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

   508 @code

   509 "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.

   510 "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.

   511 "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.

   512 "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.

   513 "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.

   514 "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.

   515 @endcode

   516 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.

   517 

   518 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.

   519 

   520 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.

   521 

   522 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.

   523 

   524 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.

   525 

   526 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:

   527 @code

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

   529     * Streams originally opened with mode "a" can be reopened with the same mode, or mode "w."

   530     * Streams originally opened with mode "w" can be reopened with the same mode, or mode "a."

   531     * Streams originally opened with mode "r+," "w+," or "a+" can be reopened with any mode. 

   532 @endcode

   533 The primary use of the freopen function is to change the file associated with a standard text stream (stderr, stdin, or stdout). 

   534 

   535 

   536 

   537 Examples:

   538 @code

   539 /* This program shows opening a file in default binary mode with write combination,write data and close */

   540 /* again open in append mode and write data */

   541 /* Check file c:\fopen.txt */

   542 #include <stdio.h>

   543 int main(void)

   544 {

   545         FILE *fp;       

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

   547         

   548         if ((fp = fopen (name, "w")) == NULL)	// Opens file in default binary mode

   549         {

   550         printf("Error creating file");

   551         return -1;

   552         }

   553         printf("Opened file");

   554         fprintf(fp, "helloworld\n");

   555         printf("Wrote to file");

   556       	fclose (fp);

   557       	printf("Closed file");

   558       	if ((fp = fopen (name, "a")) == NULL)

   559       		{

   560       		printf("Error opening file");

   561       		return -1;

   562       		}

   563       	printf("Opened file for appending");

   564 	    fprintf(fp, "fine");

   565 	    fclose (fp);

   566 	    printf("closed file, check output in c:\ fopen.txt file");

   567 	    unlink(name);

   568 	    return 0;

   569 }

   570 

   571 @endcode

   572 @code

   573 Output

   574 

   575 Opened file

   576 Wrote to file

   577 Closed file

   578 Opened file for appending

   579 closed file, check output in c:\fopen.txt file

   580 

   581 Note: fopen.txt file contains:-

   582 helloworld\nfine

   583 

   584 @endcode

   585 

   586 

   587 @code

   588 /* This program shows opening a file explicitly in text-mode using set_fmode() with write combination,write data and close */

   589 /* again open in append mode and write data */

   590 /* Check file c:\fopen.txt */

   591 #include <stdio.h>

   592 int main(void)

   593 {

   594         FILE *fp;       

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

   596         if( set_fmode('t') != 0 )

   597         	{

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

   599         	return -1;

   600         	}

   601         if(get_fmode() != 't')

   602         	{

   603         	printf(" Failed to retrieve the text-mode set using set_fmode()\n");

   604         	return -1;

   605         	}

   606         if ((fp = fopen (name, "w")) == NULL) // Opens file in text-mode

   607         {

   608         printf("Error creating file");

   609         return -1;

   610         }

   611         printf("Opened file");

   612         fprintf(fp, "helloworld\n");

   613         printf("Wrote to file");

   614       	fclose (fp);

   615       	printf("Closed file");

   616       	if ((fp = fopen (name, "a")) == NULL)

   617       		{

   618       		printf("Error opening file");

   619       		return -1;

   620       		}

   621       	printf("Opened file for appending");

   622 	    fprintf(fp, "fine");

   623 	    fclose (fp);

   624 	    printf("closed file, check output in c:\ fopen.txt file");

   625 	    unlink(name);

   626 	    return 0;

   627 }

   628 

   629 @endcode

   630 @code

   631 Output

   632 

   633 Opened file

   634 Wrote to file

   635 Closed file

   636 Opened file for appending

   637 closed file, check output in c:\fopen.txt file

   638 

   639 Note: fopen.txt file contains:-

   640 helloworld

   641 fine

   642 

   643 @endcode

   644 

   645 

   646 Notes:

   647 

   648  -# Mode values for group and others are be ignored. 

   649  -# The execute bit and setuid on exec bit are ignored. 

   650  -# The default working directory of a process is initialized to C:\\private\\UID 

   651   (UID of the calling application) and any data written into this directory persists 

   652   between phone resets. 

   653  -# If the specified file is a symbolic link and the file it is pointing to 

   654   is invalid the symbolic link file will be automatically removed.

   655 

   656 Limitations: 

   657 

   658 A file in cannot be created with write-only permission and attempting to 

   659 create one will result in a file with read-write permission. Creating a new file 

   660 with the O_CREAT flag does not alter the time stamp of its parent directory. The 

   661 newly created entry has only two time stamps: access and modification. Creation 

   662 time stamp is not supported and access time stamp is initially equal to modification 

   663 time stamp. open, fclose and fflush.

   664 

   665 KErrNotReady of symbian error code is mapped to ENOENT, which typically means drive

   666 not found or filesystem not mounted on the drive.

   667 

   668 @see open()

   669 @see fclose()

   670 @see fileno()

   671 @see fseek()

   672 @see set_fmode()

   673 @see get_fmode()

   674 

   675 

   676 

   677 @capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&)

   678 

   679 @publishedAll

   680 @externallyDefinedApi

   681 */

   682 

   683 /** @fn  fopen64(const char *file, const char *mode)

   684 @param file

   685 @param mode

   686 

   687 

   688 @return   Upon successful completion fopen64() return a FILE pointer.

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

   690 

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

   692 

   693 @see fopen()

   694 

   695 @publishedAll

   696 @externallyDefinedApi

   697 */

   698 

   699 /** @fn  fprintf(FILE *fp, const char *fmt, ...)

   700 @param fp

   701 @param fmt

   702 @param ...

   703 

   704 Refer to  printf() for the documentation

   705 @see printf()

   706 @see scanf()

   707 @see setlocale()

   708 @see wprintf()

   709  

   710 

   711 @publishedAll

   712 @externallyDefinedApi

   713 */

   714 

   715 /** @fn  fputc(int c, FILE *fp)

   716 @param c

   717 @param fp

   718 

   719 Note: This description also covers the following functions -

   720  putc()  putc_unlocked()  putchar()  putchar_unlocked()  putw() 

   721 

   722 @return   The functions, fputc, putc, putchar, putc_unlocked, and putchar_unlocked return the character written.

   723 If an error occurs, the value EOF is returned.

   724 The putw function returns 0 on success; EOF is returned if a write error occurs,

   725 or if an attempt is made to write to a read-only stream.

   726 

   727 The fputc function writes the character c (converted to an "unsigned char")

   728 to the output stream pointed to by fp.

   729 

   730 The putc macro that is identically to fputc, but is a macro that expands in-line.

   731 It may evaluate stream more than once, so arguments given to putc should not be expressions with potential side effects.

   732 

   733 The putchar function is identical to putc with an output stream of stdout.

   734 

   735 The putw function writes the specified int to the named output stream.

   736 

   737  The putc_unlocked and putchar_unlocked functions are equivalent to putc and putchar respectively,

   738 except that the caller is responsible for locking the stream with flockfile before calling them.

   739 These functions may be used to avoid the overhead of locking the stream for each character,

   740 and to avoid output being interspersed from multiple threads writing to the same stream.

   741 	

   742 	

   743 Examples:

   744 @code

   745 #include <stdio.h>

   746 int main()

   747 {

   748         FILE * fp;

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

   750         	{

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

   752         	return -1;

   753         	}

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

   755         

   756         if(fp==NULL)

   757                 {

   758                 printf("file opening failed");

   759                 return -1;

   760                 }

   761         if(putc('a',fp)!='a')

   762                 {

   763                 printf("putc failed");

   764                 fclose(fp);

   765                 return -1;

   766                 }

   767         else printf("character successfully put by putc");

   768         

   769         fclose(fp);

   770         return 0;

   771 }

   772 

   773 @endcode

   774 @code

   775 Output

   776 

   777 character successfully put by putc

   778 

   779 @endcode

   780 @see ferror()

   781 @see flockfile()

   782 @see fopen()

   783 @see getc()

   784 @see putwc()

   785 @see set_fmode() 

   786 

   787 @publishedAll

   788 @externallyDefinedApi

   789 */

   790 

   791 /** @fn  fputs(const char *s, FILE *fp)

   792 @param s

   793 @param fp

   794 

   795 Note: This description also covers the following functions -

   796  puts() 

   797 

   798 @return   The fputs function returns 0 on success and EOF on error. The puts function returns a nonnegative integer on success and EOF on error.

   799 

   800   The function fputs writes the string pointed to by s to the stream pointed to by fp.

   801 

   802  The function puts writes the string s, and a terminating newline character,

   803 to the stream stdout.

   804 

   805 

   806 Examples:

   807 @code

   808 /*this program shows writing characters from a file using fputs */

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

   810 /* hello world */

   811 #include <stdio.h>

   812 int main(void)

   813 {

   814         int wretval;    

   815         char rs1[50],rs2[50];

   816         char *rptr;

   817         int retval;

   818         FILE *fp = NULL;

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

   820         	{

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

   822         	return -1;

   823         	}

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

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

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

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

   828         fclose(fp);

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

   830         if(fp == NULL)

   831         {

   832         printf("fopen failed");

   833         return -1;

   834         }

   835         rptr = fgets(rs1,12,fp);

   836         if(rptr == NULL)

   837         {

   838         printf("fgets failed");

   839         fclose(fp);

   840         return -1;

   841         }

   842         fclose(fp);

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

   844         if(fp == NULL)

   845         {

   846         printf("fopen failed");

   847         return -1;

   848         }

   849         wretval = fputs(rs1,fp);

   850         if(wretval == EOF)

   851         {

   852         printf("fputs failed");

   853         fclose(fp);

   854         return -1;

   855         }

   856         fclose(fp);

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

   858         if(fp == NULL)

   859         {

   860         printf("fopen failed");

   861         return -1;

   862         }

   863         rptr = fgets(rs2,12,fp);

   864         if(rptr == NULL)

   865         {

   866         printf("fgets failed");

   867         fclose(fp);

   868         return -1;

   869         }

   870         printf("file reading returned \"%s\",rs2);

   871         fclose(fp);

   872         unlink("C:\puts1.txt");

   873         

   874         return 0;

   875 }

   876 

   877 @endcode

   878 @code

   879 Output

   880 

   881 file reading returned "abcdefghijk"

   882 

   883 @endcode

   884 @see ferror()

   885 @see fputws()

   886 @see putc()

   887 @see set_fmode() 

   888 

   889 @publishedAll

   890 @externallyDefinedApi

   891 */

   892 

   893 /** @fn  fread(void * buf, size_t size, size_t count, FILE * fp)

   894 @param buf

   895 @param size

   896 @param count

   897 @param fp

   898 

   899 Note: This description also covers the following functions -

   900  fwrite() 

   901 

   902 @return   The functions fread and fwrite advance the file position indicator for the stream

   903 by the number of bytes read or written.

   904 They return the number of objects read or written.

   905 If an error occurs, or the end-of-file is reached,

   906 the return value is a short object count (or zero). The function fread does not distinguish between end-of-file and error. Callers 

   907   must use feof and ferror to determine which occurred. The function fwrite returns a value less than count only if a write error has occurred.

   908 

   909   The function fread reads count objects, each size bytes long, from the stream pointed to by fp, storing them at the location given by buf.

   910 

   911  The function fwrite writes count objects, each size bytes long, to the stream pointed to by fp, obtaining them from the location given by buf.

   912  

   913 

   914 Examples:

   915 @code

   916 /* this program shows reading characters from a file using fread */

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

   918 /* hi */

   919 #include <stdio.h>

   920 int main()

   921 {

   922         char a; 

   923         FILE *fp = NULL;

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

   925         	{

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

   927         	return -1;

   928         	}

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

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

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

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

   933         fclose(fp);

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

   935         if (fp == NULL)

   936                 {

   937                 printf ("fopen failed");

   938                 return -1;

   939                 }

   940         // read single chars at a time, stopping on EOF or error:

   941         while (fread(&a;, sizeof(char), 1, fp), !feof(fp) && !ferror(fp))

   942                 {

   943                 printf("I read \"%c\",a);

   944                 }

   945         if (ferror(fp)) //Some error occurred

   946                 {

   947                 fclose(fp);

   948                 return -1;

   949                 }

   950         fclose(fp);

   951         return 0;

   952 }

   953 

   954 @endcode

   955 @code

   956 Output

   957 

   958 I read "h"

   959 I read "i"

   960 

   961 @endcode

   962 @see read()

   963 @see write()

   964 @see set_fmode() 

   965 

   966 @publishedAll

   967 @externallyDefinedApi

   968 */

   969 

   970 /** @fn  freopen(const char *file, const char *mode, FILE *fp)

   971 @param file

   972 @param mode

   973 @param fp

   974 

   975 Refer to  fopen() for the documentation

   976 @see open()

   977 @see fclose()

   978 @see fileno()

   979 @see fseek()

   980 

   981 

   982 

   983 @capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&)

   984 

   985 @publishedAll

   986 @externallyDefinedApi

   987 */

   988 

   989 /** @fn  freopen64(const char *file, const char *mode, FILE *fp)

   990 @param file

   991 @param mode

   992 @param fp

   993 

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

   995 

   996 @see freopen()

   997 

   998 @publishedAll

   999 @externallyDefinedApi

  1000 */

  1001 

  1002 /** @fn  fscanf(FILE *  fp, const char *  fmt, ...)

  1003 @param fp

  1004 @param fmt

  1005 @param ...

  1006 

  1007 Refer to  scanf() for the documentation

  1008 @see getc()

  1009 @see mbrtowc()

  1010 @see printf()

  1011 @see strtod()

  1012 @see strtol()

  1013 @see strtoul()

  1014 @see wscanf()

  1015  

  1016 

  1017 @publishedAll

  1018 @externallyDefinedApi

  1019 */

  1020 

  1021 /** @fn  fseek(FILE *fp, long offset, int whence)

  1022 @param fp

  1023 @param offset

  1024 @param whence

  1025 

  1026 Note: This description also covers the following functions -

  1027  ftell()  rewind()  fgetpos()  fsetpos() 

  1028 

  1029 @return   The rewind function returns no value. 

  1030 Upon successful completion ftell returns the current offset. Otherwise -1 is returned and the   global variable errno is set to indicate the error.

  1031 

  1032 The  fseek function sets the file position indicator for the stream pointed to by  fp. 

  1033 The new position, measured in bytes, is obtained by adding  offset bytes to the position specified by  whence. 

  1034 If  whence is set to  SEEK_SET,  SEEK_CUR, or  SEEK_END, the offset is relative to the start of the file, 

  1035 the current position indicator, or end-of-file, respectively. 

  1036 A successful call to the  fseek function clears the end-of-file indicator for the stream and 

  1037 undoes any effects of the ungetc and ungetwc functions on the same stream.

  1038 The fseek function call does not allows the file offset to be set beyond the end of the existing end-of-file of the file.

  1039 

  1040 The ftell function obtains the current value of the file position indicator for the stream pointed to by fp.

  1041 

  1042 The rewind function sets the file position indicator for the stream pointed to by fp to the beginning of the file. It is equivalent to:

  1043 

  1044 @code

  1045      (void)fseek(fp, 0L, SEEK_SET)

  1046 

  1047 @endcode

  1048 

  1049 except that the error indicator for the stream is also cleared. 

  1050 Since rewind does not return a value, an application wishing to detect errors should clear errno, 

  1051 then call rewind, and if errno is non-zero, assume an error has occurred. 

  1052 The fgetpos and fsetpos functions are alternate interfaces for retrieving and setting the current position 

  1053 in the file, similar to ftell and fseek, except that the current position is stored in an opaque object of 

  1054 type fpos_t pointed to by pos. These functions provide a portable way to seek to offsets larger than those that 

  1055 can be represented by a long int. They may also store additional state information in the fpos_t object to 

  1056 facilitate seeking within files containing multibyte characters with state-dependent encodings. 

  1057 Although fpos_t has traditionally been an integral type, applications cannot assume that it is; 

  1058 in particular, they must not perform arithmetic on objects of this type. 

  1059 If the stream is a wide character stream, the position specified by the combination of offset and whence must 

  1060 contain the first byte of a multibyte sequence.

  1061 

  1062 Notes:  Specific to text-mode Support:

  1063 	   1.	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. 

  1064             For more details, see set_fmode(). 

  1065        2.   Offset set using fseek() in text-mode will not be appropriate because every newline will be converted to symbian specific

  1066        		line-encodings( \n --> \r\n), thereby returning inappropriate offset values.

  1067        		Thus, fseek(), ftell() will not return values as expected by the User. 

  1068        3.   Offset value returned from ftell() can be used to pass to fseek() and 

  1069        		will not affect the functionality of any next read, write operations.

  1070 

  1071 

  1072 Examples:

  1073 @code

  1074 /* this program shows setting file offset using fseek */

  1075 #include <stdio.h>

  1076 int main(void)

  1077 {       

  1078         int retval;

  1079         FILE *fp = NULL;

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

  1081         	{

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

  1083         	return -1;

  1084         	}

  1085         fp = fopen("c:\input.txt", "w"); // opens file in default binary mode, hence fseek() works fine.

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

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

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

  1089         fclose(fp);

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

  1091         if (fp == NULL)

  1092         {

  1093         printf ("fopen failed");

  1094         return -1;

  1095         }

  1096         retval = fseek(fp, 3, SEEK_SET); // seek to the 20th byte of the file

  1097         if (retval)

  1098         {

  1099         printf ("fseek failed");

  1100         return -1;

  1101         }

  1102         

  1103         long pos = ftell(fp);

  1104         if (pos ==3)

  1105         {       

  1106         printf("offset setting proper");

  1107         }

  1108         fclose(fp);

  1109         return 0;

  1110 }

  1111 

  1112 @endcode

  1113 @code

  1114 Output

  1115 

  1116 offset setting proper

  1117 

  1118 @endcode

  1119 

  1120 

  1121 

  1122 

  1123 @see lseek()

  1124 @see ungetc()

  1125 @see ungetwc()

  1126 @see set_fmode()

  1127  

  1128 

  1129 @publishedAll

  1130 @externallyDefinedApi

  1131 */

  1132 

  1133 /** @fn  fsetpos(FILE *iop, const fpos_t *pos)

  1134 @param iop

  1135 @param pos