os/ossrv/genericopenlibs/openenvcore/include/stdio.dosc
author sl
Tue, 10 Jun 2014 14:32:02 +0200
changeset 1 260cb5ec6c19
permissions -rw-r--r--
Update contrib.
sl@0
     1
/** @file ../include/stdio.h
sl@0
     2
@internalComponent
sl@0
     3
*/
sl@0
     4
sl@0
     5
/** @fn  clearerr(FILE *fp)
sl@0
     6
@param fp
sl@0
     7
sl@0
     8
Note: This description also covers the following functions -
sl@0
     9
 feof()  ferror()  fileno() 
sl@0
    10
sl@0
    11
  The function clearerr clears the end-of-file and error indicators for the stream pointed
sl@0
    12
to by fp.
sl@0
    13
sl@0
    14
 The function feof tests the end-of-file indicator for the stream pointed to by fp, returning non-zero if it is set.
sl@0
    15
The end-of-file indicator can only be cleared by the function clearerr.
sl@0
    16
sl@0
    17
 The function ferror tests the error indicator for the stream pointed to by fp, returning non-zero if it is set.
sl@0
    18
The error indicator can only be reset by the clearerr function.
sl@0
    19
sl@0
    20
 The function fileno examines the argument fp and returns its integer descriptor.
sl@0
    21
 
sl@0
    22
Examples:
sl@0
    23
@code
sl@0
    24
/* this program shows finding error set using ferror 
sl@0
    25
 * and clearing it using clearerr functions */
sl@0
    26
#include <stdio.h>
sl@0
    27
int main()
sl@0
    28
{
sl@0
    29
        char a;
sl@0
    30
        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughout the appln.
sl@0
    31
        	{
sl@0
    32
        	printf("Failed to set text-mode\n");
sl@0
    33
        	return -1;
sl@0
    34
        	}
sl@0
    35
        FILE* fp = fopen("c:\input.txt", "w");
sl@0
    36
        fprintf(fp, "%s", "abcdefghijklmn");
sl@0
    37
        fprintf(fp, "%c", '');
sl@0
    38
        fprintf(fp, "%s", "fdsfdsafsdabcdefghijklmn");
sl@0
    39
        fclose(fp);
sl@0
    40
        fp=fopen("c:\input.txt","r");
sl@0
    41
        if (fp == NULL)
sl@0
    42
                {
sl@0
    43
                printf("fopen failed");
sl@0
    44
                return -1;
sl@0
    45
                }
sl@0
    46
        else
sl@0
    47
                {
sl@0
    48
                fwrite(&a;, sizeof(char), 1, fp);
sl@0
    49
                if (ferror (fp))
sl@0
    50
                        printf("error set in file stream");
sl@0
    51
                else
sl@0
    52
                        {
sl@0
    53
                        fclose(fp);
sl@0
    54
                        return -1;
sl@0
    55
                        }
sl@0
    56
                clearerr(fp);
sl@0
    57
                if (!ferror(fp))
sl@0
    58
                        printf("error cleared in file stream");
sl@0
    59
                else printf("error still unexpected set in file stream");
sl@0
    60
                fclose (fp);
sl@0
    61
                }
sl@0
    62
        return 0;
sl@0
    63
}
sl@0
    64
sl@0
    65
@endcode
sl@0
    66
@code
sl@0
    67
Output
sl@0
    68
sl@0
    69
error set in file stream
sl@0
    70
error cleared in file stream
sl@0
    71
sl@0
    72
@endcode
sl@0
    73
@see open()
sl@0
    74
@see flockfile()
sl@0
    75
@see set_fmode() 
sl@0
    76
sl@0
    77
@publishedAll
sl@0
    78
@externallyDefinedApi
sl@0
    79
*/
sl@0
    80
sl@0
    81
/** @fn  fclose(FILE *fp)
sl@0
    82
@param fp
sl@0
    83
@return   Upon successful completion 0 is returned.
sl@0
    84
Otherwise, EOF is returned and the global variable errno is set to indicate the error.
sl@0
    85
In either case no further access to the stream is possible.
sl@0
    86
sl@0
    87
  The fclose function dissociates the named stream from its underlying file or set of functions. If the stream was 
sl@0
    88
being used for output any buffered data is written first using fflush .
sl@0
    89
sl@0
    90
Examples:
sl@0
    91
@code
sl@0
    92
/* this program shows opening and closing of a file using fclose api */
sl@0
    93
#include <stdio.h>
sl@0
    94
int main()
sl@0
    95
{
sl@0
    96
        FILE *fp;
sl@0
    97
        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughout the appln.
sl@0
    98
        	{
sl@0
    99
        	printf("Failed to set text-mode\n");
sl@0
   100
        	return -1;
sl@0
   101
        	}
sl@0
   102
        fp = fopen("c:\input.txt", "w+");
sl@0
   103
        if(fp == NULL)
sl@0
   104
                {               
sl@0
   105
                printf("file opening failed");
sl@0
   106
                return -1;
sl@0
   107
                }
sl@0
   108
        
sl@0
   109
        printf("file opened successfully: Perform file operations now");
sl@0
   110
        
sl@0
   111
        if(!fclose(fp))
sl@0
   112
                {
sl@0
   113
                printf("file closed successfully");
sl@0
   114
                return 0;
sl@0
   115
                }
sl@0
   116
        else
sl@0
   117
                {
sl@0
   118
                printf("file closing failed");
sl@0
   119
                return -1;
sl@0
   120
                }
sl@0
   121
}
sl@0
   122
sl@0
   123
@endcode
sl@0
   124
@code
sl@0
   125
Output
sl@0
   126
sl@0
   127
file opened successfully: Perform file operations now
sl@0
   128
file closed successfully
sl@0
   129
sl@0
   130
@endcode
sl@0
   131
sl@0
   132
Notes:
sl@0
   133
sl@0
   134
 The fclose function
sl@0
   135
does not handle NULL arguments; they will result in a segmentation
sl@0
   136
violation.
sl@0
   137
This is intentional - it makes it easier to make sure programs written
sl@0
   138
under are bug free. This behaviour is an implementation detail and programs should not 
sl@0
   139
rely upon it. 
sl@0
   140
 
sl@0
   141
sl@0
   142
@publishedAll
sl@0
   143
@externallyDefinedApi
sl@0
   144
*/
sl@0
   145
sl@0
   146
/** @fn  feof(FILE *fp)
sl@0
   147
@param fp
sl@0
   148
sl@0
   149
Refer to  clearerr() for the documentation
sl@0
   150
@see open()
sl@0
   151
@see flockfile()
sl@0
   152
@see set_fmode()
sl@0
   153
sl@0
   154
 
sl@0
   155
sl@0
   156
@publishedAll
sl@0
   157
@externallyDefinedApi
sl@0
   158
*/
sl@0
   159
sl@0
   160
/** @fn  ferror(FILE *fp)
sl@0
   161
@param fp
sl@0
   162
sl@0
   163
Refer to  clearerr() for the documentation
sl@0
   164
@see open()
sl@0
   165
@see flockfile()
sl@0
   166
 
sl@0
   167
sl@0
   168
@publishedAll
sl@0
   169
@externallyDefinedApi
sl@0
   170
*/
sl@0
   171
sl@0
   172
/** @fn  fseeko(FILE *stream, off_t offset, int whence)
sl@0
   173
@param stream
sl@0
   174
@param offset
sl@0
   175
@param whence
sl@0
   176
sl@0
   177
For full documentation see: http://opengroup.org/onlinepubs/007908775/xsh/fseek.html
sl@0
   178
sl@0
   179
@see fseek()
sl@0
   180
 
sl@0
   181
@publishedAll
sl@0
   182
@externallyDefinedApi
sl@0
   183
*/
sl@0
   184
sl@0
   185
/** @fn  fseeko64(FILE *stream, off64_t offset, int whence)
sl@0
   186
@param stream
sl@0
   187
@param offset
sl@0
   188
@param whence
sl@0
   189
sl@0
   190
For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0
sl@0
   191
sl@0
   192
@see fseeko()
sl@0
   193
 
sl@0
   194
@publishedAll
sl@0
   195
@externallyDefinedApi
sl@0
   196
*/
sl@0
   197
sl@0
   198
/** @fn  ftello(FILE *stream)
sl@0
   199
@param stream
sl@0
   200
sl@0
   201
For full documentation see: http://opengroup.org/onlinepubs/007908775/xsh/fseek.html
sl@0
   202
sl@0
   203
@see ftell()
sl@0
   204
 
sl@0
   205
@publishedAll
sl@0
   206
@externallyDefinedApi
sl@0
   207
*/
sl@0
   208
sl@0
   209
/** @fn  ftello64(FILE *stream)
sl@0
   210
@param stream
sl@0
   211
sl@0
   212
For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0
sl@0
   213
sl@0
   214
@see ftello()
sl@0
   215
 
sl@0
   216
@publishedAll
sl@0
   217
@externallyDefinedApi
sl@0
   218
*/
sl@0
   219
sl@0
   220
/** @fn  fflush(FILE *fp)
sl@0
   221
@param fp
sl@0
   222
sl@0
   223
@return   Upon successful completion 0 is returned.
sl@0
   224
Otherwise, EOF is returned and the global variable errno is set to indicate the error.
sl@0
   225
sl@0
   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.
sl@0
   227
The open status of the stream is unaffected.
sl@0
   228
sl@0
   229
 If the fp argument is NULL, fflush flushes all open output streams.
sl@0
   230
 
sl@0
   231
Examples:
sl@0
   232
@code
sl@0
   233
/* this program shows flushing user space buffered data using fflush */
sl@0
   234
#include <stdio.h>
sl@0
   235
int main()
sl@0
   236
{
sl@0
   237
        FILE *fp = NULL;
sl@0
   238
        int retval = 0;
sl@0
   239
        char name[20] = "c:\flush1.txt";
sl@0
   240
        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughout the appln.
sl@0
   241
        	{
sl@0
   242
        	printf("Failed to set text-mode\n");
sl@0
   243
        	return -1;
sl@0
   244
        	}
sl@0
   245
        fp = fopen(name, "w+"); 
sl@0
   246
        if(fp == NULL)
sl@0
   247
                {               
sl@0
   248
                printf("Error : File open");
sl@0
   249
                return -1;
sl@0
   250
                }
sl@0
   251
        setvbuf(fp, NULL, _IOFBF, 100);  // set to full buffering with NULL buffer      
sl@0
   252
        fprintf(fp, "we are trying to buffer 100 characters at once with NULL buffer.");
sl@0
   253
        
sl@0
   254
        retval = fflush(fp);
sl@0
   255
        if (retval)
sl@0
   256
                {               
sl@0
   257
                printf("fflush failed");
sl@0
   258
                fclose(fp);
sl@0
   259
                unlink(name);
sl@0
   260
                return -1;
sl@0
   261
                }
sl@0
   262
        else printf("Buffer successfully flushed");
sl@0
   263
        fclose(fp);
sl@0
   264
        unlink(name);
sl@0
   265
        return 0;
sl@0
   266
}
sl@0
   267
sl@0
   268
@endcode
sl@0
   269
@code
sl@0
   270
Output
sl@0
   271
sl@0
   272
we are trying to buffer 100 characters at once with NULL buffer.
sl@0
   273
Buffer successfully flushed
sl@0
   274
sl@0
   275
@endcode
sl@0
   276
@see write()
sl@0
   277
@see fclose()
sl@0
   278
@see fopen()
sl@0
   279
@see setbuf()
sl@0
   280
@see set_fmode()
sl@0
   281
 
sl@0
   282
sl@0
   283
@publishedAll
sl@0
   284
@externallyDefinedApi
sl@0
   285
*/
sl@0
   286
sl@0
   287
/** @fn  fgetc(FILE *fp)
sl@0
   288
@param fp
sl@0
   289
sl@0
   290
Note: This description also covers the following functions -
sl@0
   291
 getc()  getc_unlocked()  getchar()  getchar_unlocked()  getw() 
sl@0
   292
sl@0
   293
@return   If successful, these routines return the next requested object
sl@0
   294
from the stream. Character values are returned as an unsigned char converted to an int. 
sl@0
   295
If the stream is at end-of-file or a read error occurs,
sl@0
   296
the routines return EOF. The routines and ferror must be used to distinguish between end-of-file and error.
sl@0
   297
If an error occurs, the global variable errno is set to indicate the error.
sl@0
   298
The end-of-file condition is remembered, even on a terminal, and all
sl@0
   299
subsequent attempts to read will return EOF until the condition is cleared with
sl@0
   300
sl@0
   301
  The fgetc function
sl@0
   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.
sl@0
   303
sl@0
   304
 The getc function
sl@0
   305
acts essentially identically to fgetc, but is a macro that expands in-line.
sl@0
   306
sl@0
   307
 The getchar function
sl@0
   308
is equivalent to getc (stdin.);
sl@0
   309
sl@0
   310
 The getw function
sl@0
   311
obtains the next int
sl@0
   312
(if present)
sl@0
   313
from the stream pointed at by stream.
sl@0
   314
sl@0
   315
 The getc_unlocked and getchar_unlocked functions are equivalent to getc and getchar respectively,
sl@0
   316
except that the caller is responsible for locking the stream
sl@0
   317
with flockfile before calling them.
sl@0
   318
These functions may be used to avoid the overhead of locking the stream
sl@0
   319
for each character, and to avoid input being dispersed among multiple
sl@0
   320
threads reading from the same stream.
sl@0
   321
sl@0
   322
Examples:
sl@0
   323
@code
sl@0
   324
/* this program shows reading from file using getc */
sl@0
   325
/* consider input.txt has the following content: */
sl@0
   326
/* hi */
sl@0
   327
#include <stdio.h>
sl@0
   328
int main(void)
sl@0
   329
{
sl@0
   330
        int retval;
sl@0
   331
        FILE *fp = NULL;
sl@0
   332
        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughout the appln.
sl@0
   333
        	{
sl@0
   334
        	printf("Failed to set text-mode\n");
sl@0
   335
        	return -1;
sl@0
   336
        	}
sl@0
   337
        fp = fopen("c:\input.txt", "w");
sl@0
   338
        fprintf(fp, "%s", "abcdefghijklmn");
sl@0
   339
        fprintf(fp, "%c", '\n');
sl@0
   340
        fprintf(fp, "%s", "fdsfdsafsdabcdefghijklmn");
sl@0
   341
        fclose(fp);
sl@0
   342
        fp = fopen("C:\input.txt","r");
sl@0
   343
        if(fp == NULL)
sl@0
   344
        {
sl@0
   345
        printf("fopen failed");
sl@0
   346
        return -1;
sl@0
   347
        }
sl@0
   348
        while((int)(retval = getc(fp) )!= EOF)
sl@0
   349
        {
sl@0
   350
        printf("%c", retval);
sl@0
   351
        }
sl@0
   352
        fclose(fp);
sl@0
   353
        return 0;
sl@0
   354
}
sl@0
   355
sl@0
   356
@endcode
sl@0
   357
@code
sl@0
   358
Output
sl@0
   359
sl@0
   360
hi
sl@0
   361
sl@0
   362
@endcode
sl@0
   363
@see ferror()
sl@0
   364
@see flockfile()
sl@0
   365
@see fopen()
sl@0
   366
@see fread()
sl@0
   367
@see getwc()
sl@0
   368
@see putc()
sl@0
   369
@see ungetc()
sl@0
   370
@see set_fmode()
sl@0
   371
 
sl@0
   372
sl@0
   373
@publishedAll
sl@0
   374
@externallyDefinedApi
sl@0
   375
*/
sl@0
   376
sl@0
   377
/** @fn  fgetpos(FILE * fp, fpos_t * pos)
sl@0
   378
@param fp
sl@0
   379
@param pos
sl@0
   380
Refer to  fseek() for the documentation
sl@0
   381
@see lseek()
sl@0
   382
@see ungetc()
sl@0
   383
@see ungetwc()
sl@0
   384
 
sl@0
   385
sl@0
   386
@publishedAll
sl@0
   387
@externallyDefinedApi
sl@0
   388
*/
sl@0
   389
sl@0
   390
/** @fn  fgetpos64(FILE * fp, fpos64_t * pos)
sl@0
   391
@param fp
sl@0
   392
@param pos
sl@0
   393
sl@0
   394
For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0
sl@0
   395
sl@0
   396
sl@0
   397
@see fgetpos()
sl@0
   398
sl@0
   399
@publishedAll
sl@0
   400
@externallyDefinedApi
sl@0
   401
*/
sl@0
   402
sl@0
   403
/** @fn  fgets(char *buf, int n, FILE *fp)
sl@0
   404
@param buf
sl@0
   405
@param n
sl@0
   406
@param fp
sl@0
   407
sl@0
   408
Note: This description also covers the following functions -
sl@0
   409
 gets() 
sl@0
   410
sl@0
   411
@return   Upon successful completion fgets and gets return a pointer to the string. If end-of-file occurs before any 
sl@0
   412
characters are read they return NULL and the buffer contents remain unchanged. If an error occurs they 
sl@0
   413
return NULL and the buffer contents are indeterminate. The fgets and gets functions do not distinguish between end-of-file and error and 
sl@0
   414
callers must use feof and ferror to determine which occurred.
sl@0
   415
sl@0
   416
  The fgets function reads at most one less than the number of characters 
sl@0
   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 
sl@0
   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.
sl@0
   419
sl@0
   420
The gets function is equivalent to fgets with an infinite size and a stream of stdin,
sl@0
   421
except that the newline character (if any) is not stored in the string.
sl@0
   422
It is the caller's responsibility to ensure that the input line,if any, is sufficiently short to fit in the string.
sl@0
   423
sl@0
   424
Examples:
sl@0
   425
@code
sl@0
   426
/* this program shows reading characters from a file using fgets */
sl@0
   427
/* consider input.txt has the following content: */
sl@0
   428
/* abcdefghijklmn */
sl@0
   429
/* fdsfdsafsdabcdefghijklmn */
sl@0
   430
#include <stdio.h>
sl@0
   431
int main(void)
sl@0
   432
{
sl@0
   433
        char buf[20];
sl@0
   434
        FILE *fp = NULL;
sl@0
   435
        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughout the appln.
sl@0
   436
        	{
sl@0
   437
        	printf("Failed to set text-mode\n");
sl@0
   438
        	return -1;
sl@0
   439
        	}
sl@0
   440
       	fp = fopen("c:\input.txt", "w");
sl@0
   441
        fprintf(fp, "%s", "abcdefghijklmn");
sl@0
   442
        fprintf(fp, "%c", "");
sl@0
   443
        fprintf(fp, "%s", "fdsfdsafsdabcdefghijklmn");
sl@0
   444
        fclose(fp);
sl@0
   445
                
sl@0
   446
        fp = fopen("C:\input.txt","r");
sl@0
   447
        if(fp == NULL)
sl@0
   448
                {
sl@0
   449
                printf("fopen failed");
sl@0
   450
                return -1;
sl@0
   451
                }
sl@0
   452
        if(fgets(buf,18,fp) != NULL)
sl@0
   453
                printf("%s", buf);
sl@0
   454
        else
sl@0
   455
                printf("Buffer is empty");
sl@0
   456
        
sl@0
   457
        buf[0] = '\0';
sl@0
   458
        if(fgets(buf,2,fp) != NULL)
sl@0
   459
                printf("%s", buf);
sl@0
   460
        else
sl@0
   461
                printf("Buffer is empty");
sl@0
   462
        fclose(fp);     
sl@0
   463
        return 0;
sl@0
   464
}
sl@0
   465
sl@0
   466
@endcode
sl@0
   467
@code
sl@0
   468
Output
sl@0
   469
sl@0
   470
abcdefghijklmn
sl@0
   471
fdsfdsafsdabcdefghijklmn
sl@0
   472
sl@0
   473
@endcode
sl@0
   474
sl@0
   475
Security considerations:
sl@0
   476
sl@0
   477
 The gets function cannot be used securely.
sl@0
   478
Because of its lack of bounds checking,and the inability for the calling program
sl@0
   479
to reliably determine the length of the next incoming line,the use of this function enables malicious users
sl@0
   480
to arbitrarily change a running program's functionality through a buffer overflow attack.
sl@0
   481
It is strongly suggested that the fgets function be used in all cases.
sl@0
   482
@see feof()
sl@0
   483
@see ferror()
sl@0
   484
@see fgetln()
sl@0
   485
@see set_fmode()
sl@0
   486
 
sl@0
   487
sl@0
   488
@publishedAll
sl@0
   489
@externallyDefinedApi
sl@0
   490
*/
sl@0
   491
sl@0
   492
/** @fn  fopen(const char *file, const char *mode)
sl@0
   493
@param file
sl@0
   494
@param mode
sl@0
   495
sl@0
   496
Note: This description also covers the following functions -
sl@0
   497
 fdopen()  freopen() 
sl@0
   498
sl@0
   499
@return   Upon successful completion fopen, fdopen and freopen return a FILE pointer.
sl@0
   500
Otherwise, NULL is returned and the global variable errno is set to indicate the error.
sl@0
   501
sl@0
   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. 
sl@0
   503
       For more details, see set_fmode(). 
sl@0
   504
	          
sl@0
   505
The  fopen function opens the file whose name is the string pointed to by  file and associates a stream with it.
sl@0
   506
sl@0
   507
The argument mode points to a string beginning with one of the following sequences (Additional characters may follow these sequences.):
sl@0
   508
@code
sl@0
   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.
sl@0
   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.
sl@0
   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.
sl@0
   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.
sl@0
   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.
sl@0
   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.
sl@0
   515
@endcode
sl@0
   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.
sl@0
   517
sl@0
   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.
sl@0
   519
sl@0
   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.
sl@0
   521
sl@0
   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.
sl@0
   523
sl@0
   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.
sl@0
   525
sl@0
   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:
sl@0
   527
@code
sl@0
   528
    * Streams originally opened with mode "r" can only be reopened with that same mode.
sl@0
   529
    * Streams originally opened with mode "a" can be reopened with the same mode, or mode "w."
sl@0
   530
    * Streams originally opened with mode "w" can be reopened with the same mode, or mode "a."
sl@0
   531
    * Streams originally opened with mode "r+," "w+," or "a+" can be reopened with any mode. 
sl@0
   532
@endcode
sl@0
   533
The primary use of the freopen function is to change the file associated with a standard text stream (stderr, stdin, or stdout). 
sl@0
   534
sl@0
   535
sl@0
   536
sl@0
   537
Examples:
sl@0
   538
@code
sl@0
   539
/* This program shows opening a file in default binary mode with write combination,write data and close */
sl@0
   540
/* again open in append mode and write data */
sl@0
   541
/* Check file c:\fopen.txt */
sl@0
   542
#include <stdio.h>
sl@0
   543
int main(void)
sl@0
   544
{
sl@0
   545
        FILE *fp;       
sl@0
   546
        char name[20] = "c:\fopen1.txt";
sl@0
   547
        
sl@0
   548
        if ((fp = fopen (name, "w")) == NULL)	// Opens file in default binary mode
sl@0
   549
        {
sl@0
   550
        printf("Error creating file");
sl@0
   551
        return -1;
sl@0
   552
        }
sl@0
   553
        printf("Opened file");
sl@0
   554
        fprintf(fp, "helloworld\n");
sl@0
   555
        printf("Wrote to file");
sl@0
   556
      	fclose (fp);
sl@0
   557
      	printf("Closed file");
sl@0
   558
      	if ((fp = fopen (name, "a")) == NULL)
sl@0
   559
      		{
sl@0
   560
      		printf("Error opening file");
sl@0
   561
      		return -1;
sl@0
   562
      		}
sl@0
   563
      	printf("Opened file for appending");
sl@0
   564
	    fprintf(fp, "fine");
sl@0
   565
	    fclose (fp);
sl@0
   566
	    printf("closed file, check output in c:\ fopen.txt file");
sl@0
   567
	    unlink(name);
sl@0
   568
	    return 0;
sl@0
   569
}
sl@0
   570
sl@0
   571
@endcode
sl@0
   572
@code
sl@0
   573
Output
sl@0
   574
sl@0
   575
Opened file
sl@0
   576
Wrote to file
sl@0
   577
Closed file
sl@0
   578
Opened file for appending
sl@0
   579
closed file, check output in c:\fopen.txt file
sl@0
   580
sl@0
   581
Note: fopen.txt file contains:-
sl@0
   582
helloworld\nfine
sl@0
   583
sl@0
   584
@endcode
sl@0
   585
sl@0
   586
sl@0
   587
@code
sl@0
   588
/* This program shows opening a file explicitly in text-mode using set_fmode() with write combination,write data and close */
sl@0
   589
/* again open in append mode and write data */
sl@0
   590
/* Check file c:\fopen.txt */
sl@0
   591
#include <stdio.h>
sl@0
   592
int main(void)
sl@0
   593
{
sl@0
   594
        FILE *fp;       
sl@0
   595
        char name[20] = "c:\fopen1.txt";
sl@0
   596
        if( set_fmode('t') != 0 )
sl@0
   597
        	{
sl@0
   598
        	printf("Failed to set text-mode\n");
sl@0
   599
        	return -1;
sl@0
   600
        	}
sl@0
   601
        if(get_fmode() != 't')
sl@0
   602
        	{
sl@0
   603
        	printf(" Failed to retrieve the text-mode set using set_fmode()\n");
sl@0
   604
        	return -1;
sl@0
   605
        	}
sl@0
   606
        if ((fp = fopen (name, "w")) == NULL) // Opens file in text-mode
sl@0
   607
        {
sl@0
   608
        printf("Error creating file");
sl@0
   609
        return -1;
sl@0
   610
        }
sl@0
   611
        printf("Opened file");
sl@0
   612
        fprintf(fp, "helloworld\n");
sl@0
   613
        printf("Wrote to file");
sl@0
   614
      	fclose (fp);
sl@0
   615
      	printf("Closed file");
sl@0
   616
      	if ((fp = fopen (name, "a")) == NULL)
sl@0
   617
      		{
sl@0
   618
      		printf("Error opening file");
sl@0
   619
      		return -1;
sl@0
   620
      		}
sl@0
   621
      	printf("Opened file for appending");
sl@0
   622
	    fprintf(fp, "fine");
sl@0
   623
	    fclose (fp);
sl@0
   624
	    printf("closed file, check output in c:\ fopen.txt file");
sl@0
   625
	    unlink(name);
sl@0
   626
	    return 0;
sl@0
   627
}
sl@0
   628
sl@0
   629
@endcode
sl@0
   630
@code
sl@0
   631
Output
sl@0
   632
sl@0
   633
Opened file
sl@0
   634
Wrote to file
sl@0
   635
Closed file
sl@0
   636
Opened file for appending
sl@0
   637
closed file, check output in c:\fopen.txt file
sl@0
   638
sl@0
   639
Note: fopen.txt file contains:-
sl@0
   640
helloworld
sl@0
   641
fine
sl@0
   642
sl@0
   643
@endcode
sl@0
   644
sl@0
   645
sl@0
   646
Notes:
sl@0
   647
sl@0
   648
 -# Mode values for group and others are be ignored. 
sl@0
   649
 -# The execute bit and setuid on exec bit are ignored. 
sl@0
   650
 -# The default working directory of a process is initialized to C:\\private\\UID 
sl@0
   651
  (UID of the calling application) and any data written into this directory persists 
sl@0
   652
  between phone resets. 
sl@0
   653
 -# If the specified file is a symbolic link and the file it is pointing to 
sl@0
   654
  is invalid the symbolic link file will be automatically removed.
sl@0
   655
sl@0
   656
Limitations: 
sl@0
   657
sl@0
   658
A file in cannot be created with write-only permission and attempting to 
sl@0
   659
create one will result in a file with read-write permission. Creating a new file 
sl@0
   660
with the O_CREAT flag does not alter the time stamp of its parent directory. The 
sl@0
   661
newly created entry has only two time stamps: access and modification. Creation 
sl@0
   662
time stamp is not supported and access time stamp is initially equal to modification 
sl@0
   663
time stamp. open, fclose and fflush.
sl@0
   664
sl@0
   665
KErrNotReady of symbian error code is mapped to ENOENT, which typically means drive
sl@0
   666
not found or filesystem not mounted on the drive.
sl@0
   667
sl@0
   668
@see open()
sl@0
   669
@see fclose()
sl@0
   670
@see fileno()
sl@0
   671
@see fseek()
sl@0
   672
@see set_fmode()
sl@0
   673
@see get_fmode()
sl@0
   674
sl@0
   675
sl@0
   676
sl@0
   677
@capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&)
sl@0
   678
sl@0
   679
@publishedAll
sl@0
   680
@externallyDefinedApi
sl@0
   681
*/
sl@0
   682
sl@0
   683
/** @fn  fopen64(const char *file, const char *mode)
sl@0
   684
@param file
sl@0
   685
@param mode
sl@0
   686
sl@0
   687
sl@0
   688
@return   Upon successful completion fopen64() return a FILE pointer.
sl@0
   689
Otherwise, NULL is returned and the global variable errno is set to indicate the error.
sl@0
   690
sl@0
   691
For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0
sl@0
   692
sl@0
   693
@see fopen()
sl@0
   694
sl@0
   695
@publishedAll
sl@0
   696
@externallyDefinedApi
sl@0
   697
*/
sl@0
   698
sl@0
   699
/** @fn  fprintf(FILE *fp, const char *fmt, ...)
sl@0
   700
@param fp
sl@0
   701
@param fmt
sl@0
   702
@param ...
sl@0
   703
sl@0
   704
Refer to  printf() for the documentation
sl@0
   705
@see printf()
sl@0
   706
@see scanf()
sl@0
   707
@see setlocale()
sl@0
   708
@see wprintf()
sl@0
   709
 
sl@0
   710
sl@0
   711
@publishedAll
sl@0
   712
@externallyDefinedApi
sl@0
   713
*/
sl@0
   714
sl@0
   715
/** @fn  fputc(int c, FILE *fp)
sl@0
   716
@param c
sl@0
   717
@param fp
sl@0
   718
sl@0
   719
Note: This description also covers the following functions -
sl@0
   720
 putc()  putc_unlocked()  putchar()  putchar_unlocked()  putw() 
sl@0
   721
sl@0
   722
@return   The functions, fputc, putc, putchar, putc_unlocked, and putchar_unlocked return the character written.
sl@0
   723
If an error occurs, the value EOF is returned.
sl@0
   724
The putw function returns 0 on success; EOF is returned if a write error occurs,
sl@0
   725
or if an attempt is made to write to a read-only stream.
sl@0
   726
sl@0
   727
The fputc function writes the character c (converted to an "unsigned char")
sl@0
   728
to the output stream pointed to by fp.
sl@0
   729
sl@0
   730
The putc macro that is identically to fputc, but is a macro that expands in-line.
sl@0
   731
It may evaluate stream more than once, so arguments given to putc should not be expressions with potential side effects.
sl@0
   732
sl@0
   733
The putchar function is identical to putc with an output stream of stdout.
sl@0
   734
sl@0
   735
The putw function writes the specified int to the named output stream.
sl@0
   736
sl@0
   737
 The putc_unlocked and putchar_unlocked functions are equivalent to putc and putchar respectively,
sl@0
   738
except that the caller is responsible for locking the stream with flockfile before calling them.
sl@0
   739
These functions may be used to avoid the overhead of locking the stream for each character,
sl@0
   740
and to avoid output being interspersed from multiple threads writing to the same stream.
sl@0
   741
	
sl@0
   742
	
sl@0
   743
Examples:
sl@0
   744
@code
sl@0
   745
#include <stdio.h>
sl@0
   746
int main()
sl@0
   747
{
sl@0
   748
        FILE * fp;
sl@0
   749
        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughout the appln.
sl@0
   750
        	{
sl@0
   751
        	printf("Failed to set text-mode\n");
sl@0
   752
        	return -1;
sl@0
   753
        	}
sl@0
   754
        fp=fopen("C:\input.txt","w+");
sl@0
   755
        
sl@0
   756
        if(fp==NULL)
sl@0
   757
                {
sl@0
   758
                printf("file opening failed");
sl@0
   759
                return -1;
sl@0
   760
                }
sl@0
   761
        if(putc('a',fp)!='a')
sl@0
   762
                {
sl@0
   763
                printf("putc failed");
sl@0
   764
                fclose(fp);
sl@0
   765
                return -1;
sl@0
   766
                }
sl@0
   767
        else printf("character successfully put by putc");
sl@0
   768
        
sl@0
   769
        fclose(fp);
sl@0
   770
        return 0;
sl@0
   771
}
sl@0
   772
sl@0
   773
@endcode
sl@0
   774
@code
sl@0
   775
Output
sl@0
   776
sl@0
   777
character successfully put by putc
sl@0
   778
sl@0
   779
@endcode
sl@0
   780
@see ferror()
sl@0
   781
@see flockfile()
sl@0
   782
@see fopen()
sl@0
   783
@see getc()
sl@0
   784
@see putwc()
sl@0
   785
@see set_fmode() 
sl@0
   786
sl@0
   787
@publishedAll
sl@0
   788
@externallyDefinedApi
sl@0
   789
*/
sl@0
   790
sl@0
   791
/** @fn  fputs(const char *s, FILE *fp)
sl@0
   792
@param s
sl@0
   793
@param fp
sl@0
   794
sl@0
   795
Note: This description also covers the following functions -
sl@0
   796
 puts() 
sl@0
   797
sl@0
   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.
sl@0
   799
sl@0
   800
  The function fputs writes the string pointed to by s to the stream pointed to by fp.
sl@0
   801
sl@0
   802
 The function puts writes the string s, and a terminating newline character,
sl@0
   803
to the stream stdout.
sl@0
   804
sl@0
   805
sl@0
   806
Examples:
sl@0
   807
@code
sl@0
   808
/*this program shows writing characters from a file using fputs */
sl@0
   809
/* consider input.txt has the following content: */
sl@0
   810
/* hello world */
sl@0
   811
#include <stdio.h>
sl@0
   812
int main(void)
sl@0
   813
{
sl@0
   814
        int wretval;    
sl@0
   815
        char rs1[50],rs2[50];
sl@0
   816
        char *rptr;
sl@0
   817
        int retval;
sl@0
   818
        FILE *fp = NULL;
sl@0
   819
        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughout the appln.
sl@0
   820
        	{
sl@0
   821
        	printf("Failed to set text-mode\n");
sl@0
   822
        	return -1;
sl@0
   823
        	}
sl@0
   824
        fp = fopen("c:\input.txt", "w");
sl@0
   825
        fprintf(fp, "%s", "abcdefghijklmn");
sl@0
   826
        fprintf(fp, "%c", "");
sl@0
   827
        fprintf(fp, "%s", "fdsfdsafsdabcdefghijklmn");
sl@0
   828
        fclose(fp);
sl@0
   829
        fp = fopen("c:\input.txt","r");
sl@0
   830
        if(fp == NULL)
sl@0
   831
        {
sl@0
   832
        printf("fopen failed");
sl@0
   833
        return -1;
sl@0
   834
        }
sl@0
   835
        rptr = fgets(rs1,12,fp);
sl@0
   836
        if(rptr == NULL)
sl@0
   837
        {
sl@0
   838
        printf("fgets failed");
sl@0
   839
        fclose(fp);
sl@0
   840
        return -1;
sl@0
   841
        }
sl@0
   842
        fclose(fp);
sl@0
   843
        fp = fopen("c:\puts1.txt","w+");
sl@0
   844
        if(fp == NULL)
sl@0
   845
        {
sl@0
   846
        printf("fopen failed");
sl@0
   847
        return -1;
sl@0
   848
        }
sl@0
   849
        wretval = fputs(rs1,fp);
sl@0
   850
        if(wretval == EOF)
sl@0
   851
        {
sl@0
   852
        printf("fputs failed");
sl@0
   853
        fclose(fp);
sl@0
   854
        return -1;
sl@0
   855
        }
sl@0
   856
        fclose(fp);
sl@0
   857
        fp = fopen("C:\puts1.txt","r");
sl@0
   858
        if(fp == NULL)
sl@0
   859
        {
sl@0
   860
        printf("fopen failed");
sl@0
   861
        return -1;
sl@0
   862
        }
sl@0
   863
        rptr = fgets(rs2,12,fp);
sl@0
   864
        if(rptr == NULL)
sl@0
   865
        {
sl@0
   866
        printf("fgets failed");
sl@0
   867
        fclose(fp);
sl@0
   868
        return -1;
sl@0
   869
        }
sl@0
   870
        printf("file reading returned \"%s\",rs2);
sl@0
   871
        fclose(fp);
sl@0
   872
        unlink("C:\puts1.txt");
sl@0
   873
        
sl@0
   874
        return 0;
sl@0
   875
}
sl@0
   876
sl@0
   877
@endcode
sl@0
   878
@code
sl@0
   879
Output
sl@0
   880
sl@0
   881
file reading returned "abcdefghijk"
sl@0
   882
sl@0
   883
@endcode
sl@0
   884
@see ferror()
sl@0
   885
@see fputws()
sl@0
   886
@see putc()
sl@0
   887
@see set_fmode() 
sl@0
   888
sl@0
   889
@publishedAll
sl@0
   890
@externallyDefinedApi
sl@0
   891
*/
sl@0
   892
sl@0
   893
/** @fn  fread(void * buf, size_t size, size_t count, FILE * fp)
sl@0
   894
@param buf
sl@0
   895
@param size
sl@0
   896
@param count
sl@0
   897
@param fp
sl@0
   898
sl@0
   899
Note: This description also covers the following functions -
sl@0
   900
 fwrite() 
sl@0
   901
sl@0
   902
@return   The functions fread and fwrite advance the file position indicator for the stream
sl@0
   903
by the number of bytes read or written.
sl@0
   904
They return the number of objects read or written.
sl@0
   905
If an error occurs, or the end-of-file is reached,
sl@0
   906
the return value is a short object count (or zero). The function fread does not distinguish between end-of-file and error. Callers 
sl@0
   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.
sl@0
   908
sl@0
   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.
sl@0
   910
sl@0
   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.
sl@0
   912
 
sl@0
   913
sl@0
   914
Examples:
sl@0
   915
@code
sl@0
   916
/* this program shows reading characters from a file using fread */
sl@0
   917
/* consider input.txt has the following content: */
sl@0
   918
/* hi */
sl@0
   919
#include <stdio.h>
sl@0
   920
int main()
sl@0
   921
{
sl@0
   922
        char a; 
sl@0
   923
        FILE *fp = NULL;
sl@0
   924
        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughtout the appln.
sl@0
   925
        	{
sl@0
   926
        	printf("Failed to set text-mode\n");
sl@0
   927
        	return -1;
sl@0
   928
        	}
sl@0
   929
        fp = fopen("c:\input.txt", "w");
sl@0
   930
        fprintf(fp, "%s", "abcdefghijklmn");
sl@0
   931
        fprintf(fp, "%c", '\n');
sl@0
   932
        fprintf(fp, "%s", "fdsfdsafsdabcdefghijklmn");
sl@0
   933
        fclose(fp);
sl@0
   934
        fp = fopen("c:\input.txt", "r");
sl@0
   935
        if (fp == NULL)
sl@0
   936
                {
sl@0
   937
                printf ("fopen failed");
sl@0
   938
                return -1;
sl@0
   939
                }
sl@0
   940
        // read single chars at a time, stopping on EOF or error:
sl@0
   941
        while (fread(&a;, sizeof(char), 1, fp), !feof(fp) && !ferror(fp))
sl@0
   942
                {
sl@0
   943
                printf("I read \"%c\",a);
sl@0
   944
                }
sl@0
   945
        if (ferror(fp)) //Some error occurred
sl@0
   946
                {
sl@0
   947
                fclose(fp);
sl@0
   948
                return -1;
sl@0
   949
                }
sl@0
   950
        fclose(fp);
sl@0
   951
        return 0;
sl@0
   952
}
sl@0
   953
sl@0
   954
@endcode
sl@0
   955
@code
sl@0
   956
Output
sl@0
   957
sl@0
   958
I read "h"
sl@0
   959
I read "i"
sl@0
   960
sl@0
   961
@endcode
sl@0
   962
@see read()
sl@0
   963
@see write()
sl@0
   964
@see set_fmode() 
sl@0
   965
sl@0
   966
@publishedAll
sl@0
   967
@externallyDefinedApi
sl@0
   968
*/
sl@0
   969
sl@0
   970
/** @fn  freopen(const char *file, const char *mode, FILE *fp)
sl@0
   971
@param file
sl@0
   972
@param mode
sl@0
   973
@param fp
sl@0
   974
sl@0
   975
Refer to  fopen() for the documentation
sl@0
   976
@see open()
sl@0
   977
@see fclose()
sl@0
   978
@see fileno()
sl@0
   979
@see fseek()
sl@0
   980
sl@0
   981
sl@0
   982
sl@0
   983
@capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&)
sl@0
   984
sl@0
   985
@publishedAll
sl@0
   986
@externallyDefinedApi
sl@0
   987
*/
sl@0
   988
sl@0
   989
/** @fn  freopen64(const char *file, const char *mode, FILE *fp)
sl@0
   990
@param file
sl@0
   991
@param mode
sl@0
   992
@param fp
sl@0
   993
sl@0
   994
For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0
sl@0
   995
sl@0
   996
@see freopen()
sl@0
   997
sl@0
   998
@publishedAll
sl@0
   999
@externallyDefinedApi
sl@0
  1000
*/
sl@0
  1001
sl@0
  1002
/** @fn  fscanf(FILE *  fp, const char *  fmt, ...)
sl@0
  1003
@param fp
sl@0
  1004
@param fmt
sl@0
  1005
@param ...
sl@0
  1006
sl@0
  1007
Refer to  scanf() for the documentation
sl@0
  1008
@see getc()
sl@0
  1009
@see mbrtowc()
sl@0
  1010
@see printf()
sl@0
  1011
@see strtod()
sl@0
  1012
@see strtol()
sl@0
  1013
@see strtoul()
sl@0
  1014
@see wscanf()
sl@0
  1015
 
sl@0
  1016
sl@0
  1017
@publishedAll
sl@0
  1018
@externallyDefinedApi
sl@0
  1019
*/
sl@0
  1020
sl@0
  1021
/** @fn  fseek(FILE *fp, long offset, int whence)
sl@0
  1022
@param fp
sl@0
  1023
@param offset
sl@0
  1024
@param whence
sl@0
  1025
sl@0
  1026
Note: This description also covers the following functions -
sl@0
  1027
 ftell()  rewind()  fgetpos()  fsetpos() 
sl@0
  1028
sl@0
  1029
@return   The rewind function returns no value. 
sl@0
  1030
Upon successful completion ftell returns the current offset. Otherwise -1 is returned and the   global variable errno is set to indicate the error.
sl@0
  1031
sl@0
  1032
The  fseek function sets the file position indicator for the stream pointed to by  fp. 
sl@0
  1033
The new position, measured in bytes, is obtained by adding  offset bytes to the position specified by  whence. 
sl@0
  1034
If  whence is set to  SEEK_SET,  SEEK_CUR, or  SEEK_END, the offset is relative to the start of the file, 
sl@0
  1035
the current position indicator, or end-of-file, respectively. 
sl@0
  1036
A successful call to the  fseek function clears the end-of-file indicator for the stream and 
sl@0
  1037
undoes any effects of the ungetc and ungetwc functions on the same stream.
sl@0
  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.
sl@0
  1039
sl@0
  1040
The ftell function obtains the current value of the file position indicator for the stream pointed to by fp.
sl@0
  1041
sl@0
  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:
sl@0
  1043
sl@0
  1044
@code
sl@0
  1045
     (void)fseek(fp, 0L, SEEK_SET)
sl@0
  1046
sl@0
  1047
@endcode
sl@0
  1048
sl@0
  1049
except that the error indicator for the stream is also cleared. 
sl@0
  1050
Since rewind does not return a value, an application wishing to detect errors should clear errno, 
sl@0
  1051
then call rewind, and if errno is non-zero, assume an error has occurred. 
sl@0
  1052
The fgetpos and fsetpos functions are alternate interfaces for retrieving and setting the current position 
sl@0
  1053
in the file, similar to ftell and fseek, except that the current position is stored in an opaque object of 
sl@0
  1054
type fpos_t pointed to by pos. These functions provide a portable way to seek to offsets larger than those that 
sl@0
  1055
can be represented by a long int. They may also store additional state information in the fpos_t object to 
sl@0
  1056
facilitate seeking within files containing multibyte characters with state-dependent encodings. 
sl@0
  1057
Although fpos_t has traditionally been an integral type, applications cannot assume that it is; 
sl@0
  1058
in particular, they must not perform arithmetic on objects of this type. 
sl@0
  1059
If the stream is a wide character stream, the position specified by the combination of offset and whence must 
sl@0
  1060
contain the first byte of a multibyte sequence.
sl@0
  1061
sl@0
  1062
Notes:  Specific to text-mode Support:
sl@0
  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. 
sl@0
  1064
            For more details, see set_fmode(). 
sl@0
  1065
       2.   Offset set using fseek() in text-mode will not be appropriate because every newline will be converted to symbian specific
sl@0
  1066
       		line-encodings( \n --> \r\n), thereby returning inappropriate offset values.
sl@0
  1067
       		Thus, fseek(), ftell() will not return values as expected by the User. 
sl@0
  1068
       3.   Offset value returned from ftell() can be used to pass to fseek() and 
sl@0
  1069
       		will not affect the functionality of any next read, write operations.
sl@0
  1070
sl@0
  1071
sl@0
  1072
Examples:
sl@0
  1073
@code
sl@0
  1074
/* this program shows setting file offset using fseek */
sl@0
  1075
#include <stdio.h>
sl@0
  1076
int main(void)
sl@0
  1077
{       
sl@0
  1078
        int retval;
sl@0
  1079
        FILE *fp = NULL;
sl@0
  1080
        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughtout the appln.
sl@0
  1081
        	{
sl@0
  1082
        	printf("Failed to set text-mode\n");
sl@0
  1083
        	return -1;
sl@0
  1084
        	}
sl@0
  1085
        fp = fopen("c:\input.txt", "w"); // opens file in default binary mode, hence fseek() works fine.
sl@0
  1086
        fprintf(fp, "%s", "abcdefghijklmn");
sl@0
  1087
        fprintf(fp, "%c", '');
sl@0
  1088
        fprintf(fp, "%s", "fdsfdsafsdabcdefghijklmn");
sl@0
  1089
        fclose(fp);
sl@0
  1090
        fp = fopen("c:\input.txt", "r");
sl@0
  1091
        if (fp == NULL)
sl@0
  1092
        {
sl@0
  1093
        printf ("fopen failed");
sl@0
  1094
        return -1;
sl@0
  1095
        }
sl@0
  1096
        retval = fseek(fp, 3, SEEK_SET); // seek to the 20th byte of the file
sl@0
  1097
        if (retval)
sl@0
  1098
        {
sl@0
  1099
        printf ("fseek failed");
sl@0
  1100
        return -1;
sl@0
  1101
        }
sl@0
  1102
        
sl@0
  1103
        long pos = ftell(fp);
sl@0
  1104
        if (pos ==3)
sl@0
  1105
        {       
sl@0
  1106
        printf("offset setting proper");
sl@0
  1107
        }
sl@0
  1108
        fclose(fp);
sl@0
  1109
        return 0;
sl@0
  1110
}
sl@0
  1111
sl@0
  1112
@endcode
sl@0
  1113
@code
sl@0
  1114
Output
sl@0
  1115
sl@0
  1116
offset setting proper
sl@0
  1117
sl@0
  1118
@endcode
sl@0
  1119
sl@0
  1120
sl@0
  1121
sl@0
  1122
sl@0
  1123
@see lseek()
sl@0
  1124
@see ungetc()
sl@0
  1125
@see ungetwc()
sl@0
  1126
@see set_fmode()
sl@0
  1127
 
sl@0
  1128
sl@0
  1129
@publishedAll
sl@0
  1130
@externallyDefinedApi
sl@0
  1131
*/
sl@0
  1132
sl@0
  1133
/** @fn  fsetpos(FILE *iop, const fpos_t *pos)
sl@0
  1134
@param iop
sl@0
  1135
@param pos
sl@0
  1136
sl@0
  1137
Refer to  fseek() for the documentation
sl@0
  1138
@see lseek()
sl@0
  1139
@see ungetc()
sl@0
  1140
@see ungetwc()
sl@0
  1141
 
sl@0
  1142
sl@0
  1143
@publishedAll
sl@0
  1144
@externallyDefinedApi
sl@0
  1145
*/
sl@0
  1146
sl@0
  1147
/** @fn  fsetpos64(FILE *iop, const fpos64_t *pos)
sl@0
  1148
@param iop
sl@0
  1149
@param pos
sl@0
  1150
sl@0
  1151
For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0
sl@0
  1152
sl@0
  1153
@see fsetpos()
sl@0
  1154
 
sl@0
  1155
sl@0
  1156
@publishedAll
sl@0
  1157
@externallyDefinedApi
sl@0
  1158
*/
sl@0
  1159
sl@0
  1160
/** @fn  ftell(FILE *fp)
sl@0
  1161
@param fp
sl@0
  1162
sl@0
  1163
Refer to  fseek(), set_fmode() for the documentation
sl@0
  1164
@see lseek()
sl@0
  1165
@see ungetc()
sl@0
  1166
@see ungetwc()
sl@0
  1167
@see set_fmode()
sl@0
  1168
 
sl@0
  1169
sl@0
  1170
@publishedAll
sl@0
  1171
@externallyDefinedApi
sl@0
  1172
*/
sl@0
  1173
sl@0
  1174
/** @fn  fwrite(const void *  buf, size_t size, size_t count, FILE *  fp)
sl@0
  1175
@param buf
sl@0
  1176
@param size
sl@0
  1177
@param count
sl@0
  1178
@param fp
sl@0
  1179
sl@0
  1180
Refer to  fread() for the documentation
sl@0
  1181
@see read()
sl@0
  1182
@see write()
sl@0
  1183
 
sl@0
  1184
sl@0
  1185
@publishedAll
sl@0
  1186
@externallyDefinedApi
sl@0
  1187
*/
sl@0
  1188
sl@0
  1189
/** @fn  getc(FILE *fp)
sl@0
  1190
@param fp
sl@0
  1191
sl@0
  1192
Refer to  fgetc() for the documentation
sl@0
  1193
@see ferror()
sl@0
  1194
@see flockfile()
sl@0
  1195
@see fopen()
sl@0
  1196
@see fread()
sl@0
  1197
@see getwc()
sl@0
  1198
@see putc()
sl@0
  1199
@see ungetc()
sl@0
  1200
 
sl@0
  1201
sl@0
  1202
@publishedAll
sl@0
  1203
@externallyDefinedApi
sl@0
  1204
*/
sl@0
  1205
sl@0
  1206
/** @fn  getchar()
sl@0
  1207
@param 
sl@0
  1208
sl@0
  1209
Refer to  fgetc() for the documentation
sl@0
  1210
@see ferror()
sl@0
  1211
@see flockfile()
sl@0
  1212
@see fopen()
sl@0
  1213
@see fread()
sl@0
  1214
@see getwc()
sl@0
  1215
@see putc()
sl@0
  1216
@see ungetc()
sl@0
  1217
 
sl@0
  1218
sl@0
  1219
@publishedAll
sl@0
  1220
@externallyDefinedApi
sl@0
  1221
*/
sl@0
  1222
sl@0
  1223
/** @fn  gets(char *str)
sl@0
  1224
@param str
sl@0
  1225
sl@0
  1226
Refer to  fgets() for the documentation
sl@0
  1227
@see feof()
sl@0
  1228
@see ferror()
sl@0
  1229
@see fgetln()
sl@0
  1230
 
sl@0
  1231
sl@0
  1232
@publishedAll
sl@0
  1233
@externallyDefinedApi
sl@0
  1234
*/
sl@0
  1235
sl@0
  1236
/** @fn  perror(const char *string)
sl@0
  1237
@param string
sl@0
  1238
sl@0
  1239
Note: This description also covers the following functions -
sl@0
  1240
 strerror()  strerror_r() 
sl@0
  1241
sl@0
  1242
@return   strerror function returns the appropriate error description string, 
sl@0
  1243
  or an unknown error message if the error code is unknown. The value of errno 
sl@0
  1244
  is not changed for a successful call and is set to a nonzero value upon error. 
sl@0
  1245
  The strerror_r function returns 0 on success and -1 on failure, setting 
sl@0
  1246
  errno.
sl@0
  1247
sl@0
  1248
  The strerror , strerror_r and perror functions look up the error message string corresponding to an
sl@0
  1249
error number.
sl@0
  1250
sl@0
  1251
 The strerror function accepts an error number argument errnum and returns a pointer to the corresponding
sl@0
  1252
message string.
sl@0
  1253
sl@0
  1254
 The strerror_r function renders the same result into strerrbuf for a maximum of buflen characters and returns 0 upon success.
sl@0
  1255
sl@0
  1256
 The perror function finds the error message corresponding to the current
sl@0
  1257
value of the global variable errno and writes it, followed by a newline, to the
sl@0
  1258
standard error file descriptor.
sl@0
  1259
If the argument string is non- NULL and does not point to the null character,
sl@0
  1260
this string is prepended to the message
sl@0
  1261
string and separated from it by
sl@0
  1262
a colon and space (": ");
sl@0
  1263
otherwise, only the error message string is printed.
sl@0
  1264
sl@0
  1265
 If the error number is not recognized, these functions return an error message
sl@0
  1266
string containing "Unknown error: "
sl@0
  1267
followed by the error number in decimal.
sl@0
  1268
The strerror and strerror_r functions return EINVAL as a warning.
sl@0
  1269
Error numbers recognized by this implementation fall in
sl@0
  1270
the range 0 \< errnum \< sys_nerr .
sl@0
  1271
sl@0
  1272
 If insufficient storage is provided in strerrbuf (as specified in buflen )
sl@0
  1273
to contain the error string, strerror_r returns ERANGE and strerrbuf will contain an error message that has been truncated and NUL terminated to fit the length specified by buflen .
sl@0
  1274
sl@0
  1275
 The message strings can be accessed directly using the external
sl@0
  1276
array sys_errlist .
sl@0
  1277
The external value sys_nerr contains a count of the messages in sys_errlist .
sl@0
  1278
The use of these variables is deprecated; strerror or strerror_r should be used instead.
sl@0
  1279
sl@0
  1280
Examples:
sl@0
  1281
@code
sl@0
  1282
#include <string.h>
sl@0
  1283
#include <stdio.h>
sl@0
  1284
#include <errno.h>
sl@0
  1285
int main()
sl@0
  1286
{
sl@0
  1287
    char *ptr = strerror(ERANGE);
sl@0
  1288
    printf("strerror(ERANGE) = %s",ptr);
sl@0
  1289
    return 0;
sl@0
  1290
}
sl@0
  1291
sl@0
  1292
@endcode
sl@0
  1293
@code
sl@0
  1294
Output
sl@0
  1295
sl@0
  1296
strerror(ERANGE) = Numerical result out of range
sl@0
  1297
sl@0
  1298
@endcode
sl@0
  1299
@see intro()
sl@0
  1300
sl@0
  1301
sl@0
  1302
Bugs:
sl@0
  1303
sl@0
  1304
 For unknown error numbers, the strerror function will return its result in a static buffer which
sl@0
  1305
may be overwritten by subsequent calls. The return type for strerror is missing a type-qualifier; it should actually be const char * . Programs that use the deprecated sys_errlist variable often fail to compile because they declare it
sl@0
  1306
inconsistently. 
sl@0
  1307
 
sl@0
  1308
sl@0
  1309
@publishedAll
sl@0
  1310
@externallyDefinedApi
sl@0
  1311
*/
sl@0
  1312
sl@0
  1313
/** @fn  printf(const char *fmt, ...)
sl@0
  1314
@param fmt
sl@0
  1315
@param ...
sl@0
  1316
sl@0
  1317
Note: This description also covers the following functions -
sl@0
  1318
 fprintf()  sprintf()  snprintf()  asprintf()  vprintf()  vfprintf()  vsprintf()  vsnprintf()  vasprintf() 
sl@0
  1319
sl@0
  1320
@return   Upon successful return, these functions return the number of characters printed (not including the trailing \\0 used to  end  output  to  strings).
sl@0
  1321
The functions snprintf and vsnprintf do not write more than size bytes (including the trailing \\0). 
sl@0
  1322
If the output was truncated due to this limit then the return value
sl@0
  1323
is the number of characters (not including the trailing \\0)
sl@0
  1324
which would have been written to  the  final  string  if  enough
sl@0
  1325
space  had  been  available.  Thus,  a return value of size or more
sl@0
  1326
means that the output was truncated. 
sl@0
  1327
If an output error is encountered, a negative value is returned.
sl@0
  1328
sl@0
  1329
The  printf family of functions produces output according to a  format as described below. The  printf and  vprintf functions write output to  stdout, the standard output stream;  fprintf and  vfprintf write output to the given output  stream;  sprintf,  snprintf,  vsprintf, and  vsnprintf write to the character string  str; and  asprintf and  vasprintf dynamically allocate a new string with malloc.
sl@0
  1330
sl@0
  1331
These functions write the output under the control of a format string that specifies how subsequent arguments (or arguments accessed via the variable-length argument facilities of stdarg ) are converted for output.
sl@0
  1332
sl@0
  1333
These functions return the number of characters printed (not including the trailing '\\0' used to end output to strings) or a negative value if an output error occurs, except for snprintf and vsnprintf, which return the number of characters that would have been printed if the size were unlimited (again, not including the final '\\0').
sl@0
  1334
sl@0
  1335
The asprintf and vasprintf functions set *ret to be a pointer to a buffer sufficiently large to hold the formatted string. This pointer should be passed to free to release the allocated storage when it is no longer needed. If sufficient space cannot be allocated, asprintf and vasprintf will return -1 and set ret to be a NULL pointer.
sl@0
  1336
sl@0
  1337
The snprintf and vsnprintf functions will write at most size -1 of the characters printed into the output string (the size'th character then gets the terminating '\\0' );if the return value is greater than or equal to the size argument, the string was too short and some of the printed characters were discarded. The output is always null-terminated.
sl@0
  1338
sl@0
  1339
The sprintf and vsprintf functions effectively assume an infinite size.
sl@0
  1340
sl@0
  1341
@code
sl@0
  1342
The format string is composed of zero or more directives: ordinary characters (not % ), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the % character. The arguments must correspond properly (after type promotion) with the conversion specifier. After the %, the following appear in sequence:
sl@0
  1343
sl@0
  1344
    * An optional field, consisting of a decimal digit string followed by a $, specifying the next argument to access. If this field is not provided, the argument following the last argument accessed will be used. Arguments are numbered starting at 1. If unaccessed arguments in the format string are interspersed with ones that are accessed the results will be indeterminate.
sl@0
  1345
    * Zero or more of the following flags:
sl@0
  1346
      '#' 	The value should be converted to an "alternate form." For c, d, i, n, p, s, and u conversions, this option has no effect. For o conversions, the precision of the number is increased to force the first character of the output string to a zero (except if a zero value is printed with an explicit precision of zero). For x and X conversions, a non-zero result has the string '0x' (or '0X' for X conversions) prepended to it. For a, A, e, E, f, F, g, and G conversions, the result will always contain a decimal point, even if no digits follow it (normally, a decimal point appears in the results of those conversions only if a digit follows). For g and G conversions, trailing zeros are not removed from the result as they would otherwise be.
sl@0
  1347
      '0(zero)' 	Zero padding. For all conversions except n, the converted value is padded on the left with zeros rather than blanks. If a precision is given with a numeric conversion (d, i, o, u, i, x, and X), the 0 flag is ignored.
sl@0
  1348
      '-' 	A negative field width flag; the converted value is to be left adjusted on the field boundary. Except for n conversions, the converted value is padded on the right with blanks, rather than on the left with blanks or zeros. A - overrides a 0 if both are given.
sl@0
  1349
      ' (space)' 	A blank should be left before a positive number produced by a signed conversion (a, A, d, e, E, f, F, g, G, or i).
sl@0
  1350
      '+' 	A sign must always be placed before a number produced by a signed conversion. A + overrides a space if both are used.
sl@0
  1351
      ''' 	Decimal conversions (d, u, or i) or the integral portion of a floating point conversion (f or F) should be grouped and separated by thousands using the non-monetary separator returned by localeconv.
sl@0
  1352
    * An optional decimal digit string specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has been given) to fill out the field width.
sl@0
  1353
    * An optional precision, in the form of a period . followed by an optional digit string. If the digit string is omitted, the precision is taken as zero. This gives the minimum number of digits to appear for d, i, o, u, x, and X conversions, the number of digits to appear after the decimal-point for a, A, e, E, f, and F conversions, the maximum number of significant digits for g and G conversions, or the maximum number of characters to be printed from a string for s conversions.
sl@0
  1354
    * An optional length modifier, that specifies the size of the argument. The following length modifiers are valid for the d, i, n, o, u, x, or X conversion:
sl@0
  1355
sl@0
  1356
      Modifier        d, i              o, u, x, X                n
sl@0
  1357
      hh              signed char       unsigned char             signed char *
sl@0
  1358
      h               short             unsigned short            short *
sl@0
  1359
      l (ell)         long              unsigned long             long *
sl@0
  1360
      ll (ell ell)    long long         unsigned long long        long long *
sl@0
  1361
      j               intmax_t          uintmax_t                 intmax_t *
sl@0
  1362
      t               ptrdiff_t         (see note)                ptrdiff_t *
sl@0
  1363
      z               (see note)        size_t                    (see note)
sl@0
  1364
      q (deprecated)  quad_t            u_quad_t                  quad_t *    
sl@0
  1365
sl@0
  1366
sl@0
  1367
      Note: the t modifier, when applied to a o, u, x, or X conversion, indicates that the argument is of an unsigned type equivalent in size to a ptrdiff_t. The z modifier, when applied to a d or i conversion, indicates that the argument is of a signed type equivalent in size to a size_t. Similarly, when applied to an n conversion, it indicates that the argument is a pointer to a signed type equivalent in size to a size_t.
sl@0
  1368
sl@0
  1369
      The following length modifier is valid for the a, A, e, E, f, F, g, or G conversion:
sl@0
  1370
sl@0
  1371
      Modifier    a, A, e, E, f, F, g, G
sl@0
  1372
      l (ell)     double (ignored, same behavior as without it)
sl@0
  1373
      L           long double
sl@0
  1374
sl@0
  1375
sl@0
  1376
      The following length modifier is valid for the c or s conversion:
sl@0
  1377
sl@0
  1378
      Modifier    c         s
sl@0
  1379
      l (ell)     wint_t    wchar_t *
sl@0
  1380
sl@0
  1381
sl@0
  1382
    * A character that specifies the type of conversion to be applied. 
sl@0
  1383
sl@0
  1384
A field width or precision, or both, may be indicated by an asterisk '*' or an asterisk followed by one or more decimal digits and a '\$' instead of a digit string. In this case, an int argument supplies the field width or precision. A negative field width is treated as a left adjustment flag followed by a positive field width; a negative precision is treated as though it were missing. If a single format directive mixes positional (nn$) and non-positional arguments, the results are undefined.
sl@0
  1385
@endcode
sl@0
  1386
@code
sl@0
  1387
The conversion specifiers and their meanings are:
sl@0
  1388
diouxX
sl@0
  1389
 	The int (or appropriate variant) argument is converted to signed decimal (d and i), unsigned octal (o,) unsigned decimal (u,) or unsigned hexadecimal (x and X) notation. The letters "abcdef" are used for x conversions; the letters "ABCDEF" are used for X conversions. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros.
sl@0
  1390
DOU 	The long int argument is converted to signed decimal, unsigned octal, or unsigned decimal, as if the format had been ld, lo, or lu respectively. These conversion characters are deprecated, and will eventually disappear.
sl@0
  1391
eE 	The double argument is rounded and converted in the style [-d . ddd e \*[Pm] dd] where there is one digit before the decimal-point character and the number of digits after it is equal to the precision; if the precision is missing, it is taken as 6; if the precision is zero, no decimal-point character appears. An E conversion uses the letter 'E' (rather than 'e') to introduce the exponent. The exponent always contains at least two digits; if the value is zero, the exponent is 00.
sl@0
  1392
sl@0
  1393
For a, A, e, E, f, F, g, and G conversions, positive and negative infinity are represented as inf and -inf respectively when using the lowercase conversion character, and INF and -INF respectively when using the uppercase conversion character. Similarly, NaN is represented as nan when using the lowercase conversion, and NAN when using the uppercase conversion.
sl@0
  1394
fF 	The double argument is rounded and converted to decimal notation in the style [-ddd . ddd,] where the number of digits after the decimal-point character is equal to the precision specification. If the precision is missing, it is taken as 6; if the precision is explicitly zero, no decimal-point character appears. If a decimal point appears, at least one digit appears before it.
sl@0
  1395
gG 	The double argument is converted in style f or e (or F or E for G conversions). The precision specifies the number of significant digits. If the precision is missing, 6 digits are given; if the precision is zero, it is treated as 1. Style e is used if the exponent from its conversion is less than -4 or greater than or equal to the precision. Trailing zeros are removed from the fractional part of the result; a decimal point appears only if it is followed by at least one digit.
sl@0
  1396
aA 	The double argument is rounded and converted to hexadecimal notation in the style [-0x h . hhhp[\*[Pm]d,]] where the number of digits after the hexadecimal-point character is equal to the precision specification. If the precision is missing, it is taken as enough to represent the floating-point number exactly, and no rounding occurs. If the precision is zero, no hexadecimal-point character appears. The p is a literal character 'p' and the exponent consists of a positive or negative sign followed by a decimal number representing an exponent of 2. The A conversion uses the prefix "0X" (rather than "0x"), the letters "ABCDEF" (rather than "abcdef)" to represent the hex digits, and the letter 'P' (rather than 'p') to separate the mantissa and exponent.
sl@0
  1397
sl@0
  1398
Note that there may be multiple valid ways to represent floating-point numbers in this hexadecimal format. For example, 0x3.24p+0, 0x6.48p-1 and 0xc.9p-2 are all equivalent. The format chosen depends on the internal representation of the number, but the implementation guarantees that the length of the mantissa will be minimized. Zeroes are always represented with a mantissa of 0 (preceded by a '-' if appropriate) and an exponent of +0.
sl@0
  1399
C 	Treated as c with the l (ell) modifier.
sl@0
  1400
c 	The int argument is converted to an unsigned char , and the resulting character is written.
sl@0
  1401
sl@0
  1402
If the l (ell) modifier is used, the wint_t argument shall be converted to a wchar_t, and the (potentially multi-byte) sequence representing the single wide character is written, including any shift sequences. If a shift sequence is used, the shift state is also restored to the original state after the character.
sl@0
  1403
S 	Treated as s with the l (ell) modifier.
sl@0
  1404
s 	The char * argument is expected to be a pointer to an array of character type (pointer to a string). Characters from the array are written up to (but not including) a terminating NUL character; if a precision is specified, no more than the number specified are written. If a precision is given, no null character need be present; if the precision is not specified, or is greater than the size of the array, the array must contain a terminating NUL character.
sl@0
  1405
sl@0
  1406
If the l (ell) modifier is used, the wchar_t * argument is expected to be a pointer to an array of wide characters (pointer to a wide string). For each wide character in the string, the (potentially multi-byte) sequence representing the wide character is written, including any shift sequences. If any shift sequence is used, the shift state is also restored to the original state after the string. Wide characters from the array are written up to (but not including) a terminating wide NUL character; if a precision is specified, no more than the number of bytes specified are written (including shift sequences). Partial characters are never written. If a precision is given, no null character need be present; if the precision is not specified, or is greater than the number of bytes required to render the multibyte representation of the string, the array must contain a terminating wide NUL character.
sl@0
  1407
p 	The void * pointer argument is printed in hexadecimal (as if by '%#x' or '%#lx' ).
sl@0
  1408
n 	The number of characters written so far is stored into the integer indicated by the int * (or variant) pointer argument. No argument is converted.
sl@0
  1409
 % 	A '%' is written. No argument is converted. The complete conversion specification is '%%'.
sl@0
  1410
sl@0
  1411
@endcode
sl@0
  1412
sl@0
  1413
The decimal point character is defined in the program's locale (category LC_NUMERIC ).
sl@0
  1414
sl@0
  1415
In no case does a non-existent or small field width cause truncation of a numeric field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result. 
sl@0
  1416
sl@0
  1417
sl@0
  1418
sl@0
  1419
Examples:
sl@0
  1420
sl@0
  1421
 To print a date and time in the form "Sunday, July 3, 10:02",
sl@0
  1422
where weekday and month are pointers to strings:
sl@0
  1423
@code
sl@0
  1424
#include <stdio.h>
sl@0
  1425
fprintf(stdout, "%s, %s %d, %.2d:%.2d
sl@0
  1426
",
sl@0
  1427
        weekday, month, day, hour, min);
sl@0
  1428
sl@0
  1429
@endcode
sl@0
  1430
 To print pi
sl@0
  1431
to five decimal places:
sl@0
  1432
@code
sl@0
  1433
#include <math.h>
sl@0
  1434
#include <stdio.h>
sl@0
  1435
fprintf(stdout, "pi = %.5f
sl@0
  1436
", 4 * atan(1.0));
sl@0
  1437
sl@0
  1438
@endcode
sl@0
  1439
 To allocate a 128 byte string and print into it:
sl@0
  1440
@code
sl@0
  1441
#include <stdio.h>
sl@0
  1442
#include <stdlib.h>
sl@0
  1443
#include <stdarg.h>
sl@0
  1444
char *newfmt(const char *fmt, ...)
sl@0
  1445
{
sl@0
  1446
        char *p;
sl@0
  1447
        va_list ap;
sl@0
  1448
        if ((p = malloc(128)) == NULL)
sl@0
  1449
                return (NULL);
sl@0
  1450
        va_start(ap, fmt);
sl@0
  1451
        (void) vsnprintf(p, 128, fmt, ap);
sl@0
  1452
        va_end(ap);
sl@0
  1453
        return (p);
sl@0
  1454
}
sl@0
  1455
sl@0
  1456
@endcode
sl@0
  1457
@code
sl@0
  1458
/* this program shows printing onto the console using printf */
sl@0
  1459
#include <stdio.h>
sl@0
  1460
int main(void)
sl@0
  1461
{
sl@0
  1462
        char * msg="hello world";
sl@0
  1463
        printf("%s",msg);
sl@0
  1464
        return 0;
sl@0
  1465
}
sl@0
  1466
sl@0
  1467
@endcode
sl@0
  1468
@code
sl@0
  1469
Output
sl@0
  1470
sl@0
  1471
hello world
sl@0
  1472
sl@0
  1473
@endcode
sl@0
  1474
@code
sl@0
  1475
/* this program shows reading from console using scanf */
sl@0
  1476
#include <stdio.h>
sl@0
  1477
int main(void)
sl@0
  1478
{
sl@0
  1479
        char msg[100];
sl@0
  1480
        printf("enter message to be printed");
sl@0
  1481
        scanf("%s",msg);
sl@0
  1482
        printf("message entered is: %s",msg);
sl@0
  1483
        return 0;
sl@0
  1484
}
sl@0
  1485
sl@0
  1486
@endcode
sl@0
  1487
@code
sl@0
  1488
Output
sl@0
  1489
sl@0
  1490
enter message to be printed
sl@0
  1491
hello (assuming this is user input)
sl@0
  1492
message entered is: hello
sl@0
  1493
sl@0
  1494
@endcode
sl@0
  1495
sl@0
  1496
Security considerations:
sl@0
  1497
sl@0
  1498
 The sprintf and vsprintf functions are easily misused in a manner which enables malicious users
sl@0
  1499
to arbitrarily change a running program's functionality through
sl@0
  1500
a buffer overflow attack.
sl@0
  1501
Because sprintf and vsprintf assume an infinitely long string,
sl@0
  1502
callers must be careful not to overflow the actual space;
sl@0
  1503
this is often hard to assure.
sl@0
  1504
For safety, programmers should use the snprintf interface instead.
sl@0
  1505
sl@0
  1506
 The printf and sprintf family of functions are also easily misused in a manner
sl@0
  1507
allowing malicious users to arbitrarily change a running program's
sl@0
  1508
functionality by either causing the program
sl@0
  1509
to print potentially sensitive data "left on the stack",
sl@0
  1510
or causing it to generate a memory fault or bus error
sl@0
  1511
by dereferencing an invalid pointer. \%n can be used to write arbitrary data to potentially carefully-selected
sl@0
  1512
addresses.
sl@0
  1513
Programmers are therefore strongly advised to never pass untrusted strings
sl@0
  1514
as the format argument, as an attacker can put format specifiers in the string
sl@0
  1515
to mangle your stack,
sl@0
  1516
leading to a possible security hole.
sl@0
  1517
This holds true even if the string was built using a function like snprintf, as the resulting string may still contain user-supplied conversion specifiers
sl@0
  1518
for later interpolation by printf. Always use the proper secure idiom:
sl@0
  1519
sl@0
  1520
@code     
sl@0
  1521
snprintf(buffer, sizeof(buffer), "%s", string);
sl@0
  1522
@endcode
sl@0
  1523
@return   None of these functions support long double length modifiers. Floating point 
sl@0
  1524
format specifiers support a maximum precision of 15 digits.
sl@0
  1525
sl@0
  1526
@see printf()
sl@0
  1527
@see scanf()
sl@0
  1528
@see setlocale()
sl@0
  1529
@see wprintf()
sl@0
  1530
sl@0
  1531
sl@0
  1532
Bugs:
sl@0
  1533
sl@0
  1534
 The conversion formats \%D, \%O, and \%U are not standard and
sl@0
  1535
are provided only for backward compatibility.
sl@0
  1536
The effect of padding the \%p format with zeros (either by the 0 flag or by specifying a precision), and the benign effect (i.e., none)
sl@0
  1537
of the \# flag on \%n and \%p conversions, as well as other
sl@0
  1538
nonsensical combinations such as \%Ld, are not standard; such combinations
sl@0
  1539
should be avoided. The printf family of functions do not correctly handle multibyte characters in the format argument. 
sl@0
  1540
 
sl@0
  1541
sl@0
  1542
@publishedAll
sl@0
  1543
@externallyDefinedApi
sl@0
  1544
*/
sl@0
  1545
sl@0
  1546
/** @fn  putc(int c, FILE *fp)
sl@0
  1547
@param c
sl@0
  1548
@param fp
sl@0
  1549
sl@0
  1550
Refer to  fputc() for the documentation
sl@0
  1551
@see ferror()
sl@0
  1552
@see flockfile()
sl@0
  1553
@see fopen()
sl@0
  1554
@see getc()
sl@0
  1555
@see putwc()
sl@0
  1556
 
sl@0
  1557
sl@0
  1558
@publishedAll
sl@0
  1559
@externallyDefinedApi
sl@0
  1560
*/
sl@0
  1561
sl@0
  1562
/** @fn  putchar(int c)
sl@0
  1563
@param c
sl@0
  1564
sl@0
  1565
Refer to  fputc() for the documentation
sl@0
  1566
@see ferror()
sl@0
  1567
@see flockfile()
sl@0
  1568
@see fopen()
sl@0
  1569
@see getc()
sl@0
  1570
@see putwc()
sl@0
  1571
 
sl@0
  1572
sl@0
  1573
@publishedAll
sl@0
  1574
@externallyDefinedApi
sl@0
  1575
*/
sl@0
  1576
sl@0
  1577
/** @fn  puts(const char *str)
sl@0
  1578
@param str
sl@0
  1579
sl@0
  1580
Refer to  fputs() for the documentation
sl@0
  1581
@see ferror()
sl@0
  1582
@see fputws()
sl@0
  1583
@see putc()
sl@0
  1584
 
sl@0
  1585
sl@0
  1586
@publishedAll
sl@0
  1587
@externallyDefinedApi
sl@0
  1588
*/
sl@0
  1589
sl@0
  1590
/** @fn  remove(const char *file)
sl@0
  1591
@param file
sl@0
  1592
@return   Upon successful completion, reomve return 0.
sl@0
  1593
Otherwise, -1 is returned and the global variable errno is set to indicate the error.
sl@0
  1594
sl@0
  1595
  The remove function removes the file or directory specified by file.
sl@0
  1596
sl@0
  1597
 If file specifies a directory, remove (file); is the equivalent of rmdir (file); Otherwise, it is the equivalent of unlink (file);
sl@0
  1598
 
sl@0
  1599
sl@0
  1600
Examples:
sl@0
  1601
@code
sl@0
  1602
/* this program shows deleting a file using remove */
sl@0
  1603
#include <stdio.h>
sl@0
  1604
int main()
sl@0
  1605
{
sl@0
  1606
        char *name = "C:\input.txt";
sl@0
  1607
        FILE *fp = NULL;
sl@0
  1608
        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughtout the appln.
sl@0
  1609
        	{
sl@0
  1610
        	printf("Failed to set text-mode\n");
sl@0
  1611
        	return -1;
sl@0
  1612
        	}
sl@0
  1613
        fp = fopen(name, "w+");
sl@0
  1614
        if (fp == NULL)
sl@0
  1615
                {
sl@0
  1616
                printf ("fopen failed");
sl@0
  1617
                return -1;
sl@0
  1618
                }
sl@0
  1619
        fprintf(fp,"hello world");
sl@0
  1620
        fclose(fp);
sl@0
  1621
        
sl@0
  1622
        remove(name);
sl@0
  1623
        fp=fopen(name,"r");
sl@0
  1624
        if (fp == NULL)
sl@0
  1625
                {
sl@0
  1626
                printf ("file has been deleted already");
sl@0
  1627
                }
sl@0
  1628
        else
sl@0
  1629
                {
sl@0
  1630
                printf("remove failed");
sl@0
  1631
                return -1;
sl@0
  1632
                }
sl@0
  1633
        
sl@0
  1634
        return 0;
sl@0
  1635
}
sl@0
  1636
sl@0
  1637
@endcode
sl@0
  1638
@code
sl@0
  1639
Output
sl@0
  1640
sl@0
  1641
file has been deleted already
sl@0
  1642
sl@0
  1643
@endcode
sl@0
  1644
sl@0
  1645
Limitations:
sl@0
  1646
sl@0
  1647
- The file parameter of the remove() function should not exceed 256 characters in length.
sl@0
  1648
- P.I.P.S. only simulates link files and does not distinguish between hard and symbolic links.
sl@0
  1649
- KErrNotReady of Symbian error code is mapped to ENOENT, which typically means drive
sl@0
  1650
not found or filesystem not mounted on the drive.
sl@0
  1651
sl@0
  1652
@see rmdir()
sl@0
  1653
@see unlink()
sl@0
  1654
@see set_fmode()
sl@0
  1655
sl@0
  1656
sl@0
  1657
@capability Deferred @ref RFs::RmDir(const TDesC16&)
sl@0
  1658
sl@0
  1659
@publishedAll
sl@0
  1660
@externallyDefinedApi
sl@0
  1661
*/
sl@0
  1662
sl@0
  1663
/** @fn  rename(const char *oldpath, const char *newpath)
sl@0
  1664
@param oldpath
sl@0
  1665
@param newpath
sl@0
  1666
@return   The rename() function returns the value 0 if successful; otherwise the
sl@0
  1667
value -1 is returned and the global variable errno is set to indicate the
sl@0
  1668
error.
sl@0
  1669
sl@0
  1670
  The rename system call
sl@0
  1671
causes the link named oldpath to be renamed as to. If to exists, it is first removed.
sl@0
  1672
Both oldpath and newpath must be of the same type (that is, both directories or both
sl@0
  1673
non-directories), and must reside on the same file system.
sl@0
  1674
sl@0
  1675
 If the final component of oldpath is a symbolic link,
sl@0
  1676
the symbolic link is renamed,
sl@0
  1677
not the file or directory to which it points.
sl@0
  1678
sl@0
  1679
 If a file with a symbolic link pointing to it is renamed, then
sl@0
  1680
a subsequent open call on the symbolic link file would automatically remove the link file, i.e
sl@0
  1681
consider a symbolic file link.x pointing to a file abc.x. If the file abc.x is
sl@0
  1682
renamed to abcd.x then, a subsequent open call on link.x file would automatically remove link.x file.
sl@0
  1683
sl@0
  1684
 Note:
sl@0
  1685
 -# rename() does not differentiate between hard and soft links.
sl@0
  1686
 -# If the specified file is a  dangling link file, then this  link file will be automatically removed.
sl@0
  1687
sl@0
  1688
sl@0
  1689
sl@0
  1690
 Limitations:
sl@0
  1691
sl@0
  1692
 - The to and from parameters in rename() shouldn't exceed 256 characters.
sl@0
  1693
 - The rename() function fails if either from or to parameters refer to a file in use (that is, if either file is held open by a process).
sl@0
  1694
 - The parent directory time stamps are not affected when rename() creates a new entry. The time stamps for the new entry like time of last access
sl@0
  1695
   is equal to time of last data modification. The time of last file status change for any file would be 0.
sl@0
  1696
 - KErrNotReady of Symbian error code is mapped to ENOENT, which typically means drive
sl@0
  1697
not found or filesystem not mounted on the drive.
sl@0
  1698
sl@0
  1699
Examples:
sl@0
  1700
@code
sl@0
  1701
/*
sl@0
  1702
 * Detailed description: This sample code demonstrates usage of rename system call.
sl@0
  1703
 *
sl@0
  1704
 * Preconditions: Example.cfg file should be present in the current working directory.
sl@0
  1705
 */
sl@0
  1706
#include <stdio.h>
sl@0
  1707
int main()
sl@0
  1708
{
sl@0
  1709
  if(rename("Example.txt" , "Example2.txt") < 0 )  {
sl@0
  1710
     printf("Failed to rename Example.txt");
sl@0
  1711
     return -1;
sl@0
  1712
  }
sl@0
  1713
  printf("Rename successful");
sl@0
  1714
  return 0;
sl@0
  1715
}
sl@0
  1716
sl@0
  1717
@endcode
sl@0
  1718
@code
sl@0
  1719
Output
sl@0
  1720
sl@0
  1721
Rename successful
sl@0
  1722
sl@0
  1723
@endcode
sl@0
  1724
@see open()
sl@0
  1725
@see symlink()
sl@0
  1726
sl@0
  1727
@capability Deferred @ref RFs::Rename(const TDesC16&, const TDesC16&)
sl@0
  1728
@capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&)
sl@0
  1729
@capability Deferred @ref RFs::RmDir(const TDesC16&)
sl@0
  1730
@capability Deferred @ref RFs::SetAtt(const TDesC16&, unsigned, unsigned)
sl@0
  1731
@capability Deferred @ref RFs::Delete(const TDesC16&)
sl@0
  1732
sl@0
  1733
@publishedAll
sl@0
  1734
@externallyDefinedApi
sl@0
  1735
*/
sl@0
  1736
sl@0
  1737
/** @fn  rewind(FILE *fp)
sl@0
  1738
@param fp
sl@0
  1739
sl@0
  1740
Refer to  fseek() for the documentation
sl@0
  1741
@see lseek()
sl@0
  1742
@see ungetc()
sl@0
  1743
@see ungetwc()
sl@0
  1744
 
sl@0
  1745
sl@0
  1746
@publishedAll
sl@0
  1747
@externallyDefinedApi
sl@0
  1748
*/
sl@0
  1749
sl@0
  1750
/** @fn  scanf(const char *  fmt, ...)
sl@0
  1751
@param fmt
sl@0
  1752
@param ...
sl@0
  1753
sl@0
  1754
Note: This description also covers the following functions -
sl@0
  1755
 fscanf()  sscanf()  vscanf()  vsscanf()  vfscanf() 
sl@0
  1756
sl@0
  1757
@return   These functions return the number of input items assigned, which 
sl@0
  1758
can be fewer than provided for, or even zero, in the event of a matching failure. 
sl@0
  1759
Zero indicates that, while there was input available, no conversions were assigned; 
sl@0
  1760
typically this is due to an invalid input character, such as an alphabetic character 
sl@0
  1761
for a '\%d' conversion. The value EOF is returned if an input failure occurs before any conversion such 
sl@0
  1762
as an end-of-file occurs. If an error or end-of-file occurs after conversion has 
sl@0
  1763
begun, the number of conversions which were successfully completed is returned.
sl@0
  1764
sl@0
  1765
 
sl@0
  1766
sl@0
  1767
 The scanf family of functions scans input according to a format as described below. This format may contain conversion specifiers; the results from such conversions, if any, are 
sl@0
  1768
  stored through the pointer arguments. The scanf function reads input from the standard input stream stdin, fscanf reads input from the stream pointer stream, and sscanf reads its input from the character string pointed to by str. The vfscanf function is analogous to vfprintf and reads input from the stream pointer stream using a variable argument list of pointers (see stdarg).
sl@0
  1769
sl@0
  1770
 The vscanf function scans a variable argument list from the standard input 
sl@0
  1771
  and the vsscanf function scans it from a string; these are analogous to the vprintf and vsprintf functions respectively. Each successive pointer argument must correspond properly with each successive conversion 
sl@0
  1772
  specifier (but see the * conversion below). All conversions are introduced by the \% (percent sign) character. The format string may also contain other characters. White space (such as 
sl@0
  1773
  blanks, tabs, or newlines) in the format string match any amount of white space, including none, in the 
sl@0
  1774
  input. Everything else matches only itself. Scanning stops when an input character 
sl@0
  1775
  does not match such a format character. Scanning also stops when an input conversion 
sl@0
  1776
  cannot be made (see below).
sl@0
  1777
  
sl@0
  1778
sl@0
  1779
Examples:
sl@0
  1780
@code
sl@0
  1781
/* this program shows scanning from file using fscanf */
sl@0
  1782
#include <stdio.h>
sl@0
  1783
int main(void)
sl@0
  1784
{
sl@0
  1785
        char x;
sl@0
  1786
        int ret;
sl@0
  1787
        char* filename="c:\ScanfTest1.txt";
sl@0
  1788
        FILE *fp = NULL;
sl@0
  1789
        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughtout the appln.
sl@0
  1790
        	{
sl@0
  1791
        	printf("Failed to set text-mode\n");
sl@0
  1792
        	return -1;
sl@0
  1793
        	}
sl@0
  1794
        fp=fopen(filename,"w");
sl@0
  1795
        fprintf(fp,"%s","abcdesdafg");
sl@0
  1796
        fclose(fp);
sl@0
  1797
        fp=fopen(filename,"r");
sl@0
  1798
        ret=fscanf(fp,"%c",&x;);
sl@0
  1799
        fclose(fp);
sl@0
  1800
        printf("fscanf returned:%c",x);
sl@0
  1801
        unlink(filename);
sl@0
  1802
        getchar();
sl@0
  1803
        if(ret!= 1)
sl@0
  1804
                return -1;
sl@0
  1805
        else
sl@0
  1806
                return 0;
sl@0
  1807
}
sl@0
  1808
sl@0
  1809
@endcode
sl@0
  1810
@code
sl@0
  1811
Output
sl@0
  1812
sl@0
  1813
fscanf returned:a
sl@0
  1814
sl@0
  1815
sl@0
  1816
@endcode
sl@0
  1817
Examples:
sl@0
  1818
@code
sl@0
  1819
/* this program shows scanning from file using fscanf */
sl@0
  1820
#include <stdio.h>
sl@0
  1821
int main(void)
sl@0
  1822
{
sl@0
  1823
        char x;
sl@0
  1824
        int ret;
sl@0
  1825
        char* filename="c:\ScanfTest1.txt";
sl@0
  1826
        FILE *fp = NULL;
sl@0
  1827
        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughtout the appln.
sl@0
  1828
        	{
sl@0
  1829
        	printf("Failed to set text-mode\n");
sl@0
  1830
        	return -1;
sl@0
  1831
        	}
sl@0
  1832
        fp=fopen(filename,"w");
sl@0
  1833
        fprintf(fp,"%s","abcdesdafg");
sl@0
  1834
        fclose(fp);
sl@0
  1835
        fp=fopen(filename,"r");
sl@0
  1836
        ret=fscanf(fp,"%c",&x;);
sl@0
  1837
        fclose(fp);
sl@0
  1838
        printf("fscanf returned:%c",x);
sl@0
  1839
        unlink(filename);
sl@0
  1840
        getchar();
sl@0
  1841
        if(ret!= 1)
sl@0
  1842
                return -1;
sl@0
  1843
        else
sl@0
  1844
                return 0;
sl@0
  1845
}
sl@0
  1846
sl@0
  1847
@endcode
sl@0
  1848
@code
sl@0
  1849
Output
sl@0
  1850
sl@0
  1851
fscanf returned:a
sl@0
  1852
sl@0
  1853
sl@0
  1854
@endcode
sl@0
  1855
@return   None of these functions support long double data types.
sl@0
  1856
sl@0
  1857
@see getc()
sl@0
  1858
@see mbrtowc()
sl@0
  1859
@see printf()
sl@0
  1860
@see strtod()
sl@0
  1861
@see strtol()
sl@0
  1862
@see strtoul()
sl@0
  1863
@see wscanf()
sl@0
  1864
@see set_fmode() 
sl@0
  1865
sl@0
  1866
@publishedAll
sl@0
  1867
@externallyDefinedApi
sl@0
  1868
*/
sl@0
  1869
sl@0
  1870
/** @fn  setbuf(FILE *  fp, char *  buf)
sl@0
  1871
@param fp
sl@0
  1872
@param buf
sl@0
  1873
sl@0
  1874
Note: This description also covers the following functions -
sl@0
  1875
 setbuffer()  setlinebuf()  setvbuf() 
sl@0
  1876
sl@0
  1877
The three types of buffering available are unbuffered, block buffered, and line buffered. When an output stream is unbuffered, information appears on the destination file or terminal as soon as written; when it is block buffered many characters are saved up and written as a block; when it is line buffered characters are saved up until a newline is output or input is read from any stream attached to a terminal device (typically  stdin). The function fflush may be used to force the block out early.
sl@0
  1878
sl@0
  1879
Normally all files are block buffered. When the first I/O operation occurs on a file, malloc is called, and an optimally-sized buffer is obtained. If a stream refers to a terminal (as stdout normally does) it is line buffered. The standard error stream stderr is always unbuffered.
sl@0
  1880
sl@0
  1881
The setvbuf function may be used to alter the buffering behavior of a stream. The mode argument must be one of the following three macros:
sl@0
  1882
sl@0
  1883
@code
sl@0
  1884
_IONBF
sl@0
  1885
 	unbuffered
sl@0
  1886
_IOLBF
sl@0
  1887
 	line buffered
sl@0
  1888
_IOFBF
sl@0
  1889
 	fully buffered
sl@0
  1890
@endcode
sl@0
  1891
sl@0
  1892
The size argument may be given as zero to obtain deferred optimal-size buffer allocation as usual. If it is not zero, then except for unbuffered files, the buf argument should point to a buffer at least size bytes long; this buffer will be used instead of the current buffer. If buf is not NULL, it is the caller's responsibility to free this buffer after closing the stream.
sl@0
  1893
sl@0
  1894
The setvbuf function may be used at any time, but may have peculiar side effects (such as discarding input or flushing output) if the stream is "active". Portable applications should call it only once on any given stream, and before any I/O is performed.
sl@0
  1895
sl@0
  1896
The other three calls are, in effect, simply aliases for calls to setvbuf. Except for the lack of a return value, the setbuf function is exactly equivalent to the call
sl@0
  1897
sl@0
  1898
@code
sl@0
  1899
     setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);
sl@0
  1900
@endcode
sl@0
  1901
sl@0
  1902
The setbuffer function is the same, except that the size of the buffer is up to the caller, rather than being determined by the default BUFSIZ. The setlinebuf function is exactly equivalent to the call:
sl@0
  1903
@code
sl@0
  1904
     setvbuf(stream, (char *)NULL, _IOLBF, 0);
sl@0
  1905
@endcode
sl@0
  1906
sl@0
  1907
sl@0
  1908
Examples:
sl@0
  1909
@code
sl@0
  1910
/* this program shows setting up a buffer using setbuf * /
sl@0
  1911
#include <stdio.h>
sl@0
  1912
int main()
sl@0
  1913
{
sl@0
  1914
        FILE *fp = NULL;
sl@0
  1915
        char FullBuf[100];
sl@0
  1916
        char msg[100];
sl@0
  1917
        char * rptr;
sl@0
  1918
        char name[20] = "c:\setbuf1.txt";
sl@0
  1919
        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughtout the appln.
sl@0
  1920
        	{
sl@0
  1921
        	printf("Failed to set text-mode\n");
sl@0
  1922
        	return -1;
sl@0
  1923
        	}
sl@0
  1924
        fp = fopen(name, "w+");
sl@0
  1925
        if (fp == NULL)
sl@0
  1926
                {
sl@0
  1927
                printf ("fopen failed");
sl@0
  1928
                return -1;
sl@0
  1929
                }
sl@0
  1930
        setbuf(fp, FullBuf);  // Fully buffered
sl@0
  1931
        if (ferror(fp))
sl@0
  1932
                {
sl@0
  1933
                printf ("setbuf failed");
sl@0
  1934
                fclose(fp);
sl@0
  1935
                unlink(name);
sl@0
  1936
                return -1;
sl@0
  1937
                }
sl@0
  1938
        fprintf(fp, "we are trying to buffer 20 characters at once ");
sl@0
  1939
        
sl@0
  1940
        fclose(fp);
sl@0
  1941
        fp=fopen(name,"r");
sl@0
  1942
        rptr = fgets(msg,100,fp);
sl@0
  1943
        if(rptr == NULL)
sl@0
  1944
                {
sl@0
  1945
                printf("fgets failed");
sl@0
  1946
                fclose(fp);
sl@0
  1947
                return -1;
sl@0
  1948
                }
sl@0
  1949
        printf("file reading returned \"%s\",msg);
sl@0
  1950
        fclose(fp);
sl@0
  1951
        
sl@0
  1952
        unlink(name);
sl@0
  1953
        return 0;
sl@0
  1954
}
sl@0
  1955
sl@0
  1956
@endcode
sl@0
  1957
@code
sl@0
  1958
Output
sl@0
  1959
sl@0
  1960
file reading returned "we are trying to buffer 20 characters at once"
sl@0
  1961
sl@0
  1962
sl@0
  1963
@endcode
sl@0
  1964
@see fopen()
sl@0
  1965
@see fread()
sl@0
  1966
@see malloc()
sl@0
  1967
@see printf()
sl@0
  1968
@see set_fmode() 
sl@0
  1969
sl@0
  1970
@publishedAll
sl@0
  1971
@externallyDefinedApi
sl@0
  1972
*/
sl@0
  1973
sl@0
  1974
/** @fn  setvbuf(FILE * fp, char *  buf, int mode, size_t size)
sl@0
  1975
@param fp
sl@0
  1976
@param buf
sl@0
  1977
@param mode
sl@0
  1978
@param size
sl@0
  1979
sl@0
  1980
Refer to  setbuf() for the documentation
sl@0
  1981
@see fopen()
sl@0
  1982
@see fread()
sl@0
  1983
@see malloc()
sl@0
  1984
@see printf()
sl@0
  1985
 
sl@0
  1986
sl@0
  1987
@publishedAll
sl@0
  1988
@externallyDefinedApi
sl@0
  1989
*/
sl@0
  1990
sl@0
  1991
/** @fn  sprintf(char *  str, const char *  fmt, ...)
sl@0
  1992
@param str
sl@0
  1993
@param fmt
sl@0
  1994
@param ...
sl@0
  1995
sl@0
  1996
Refer to  printf() for the documentation
sl@0
  1997
@see printf()
sl@0
  1998
@see scanf()
sl@0
  1999
@see setlocale()
sl@0
  2000
@see wprintf()
sl@0
  2001
 
sl@0
  2002
sl@0
  2003
@publishedAll
sl@0
  2004
@externallyDefinedApi
sl@0
  2005
*/
sl@0
  2006
sl@0
  2007
/** @fn  sscanf(const char *  str, const char * fmt, ...)
sl@0
  2008
@param str
sl@0
  2009
@param fmt
sl@0
  2010
@param ...
sl@0
  2011
sl@0
  2012
Refer to  scanf() for the documentation
sl@0
  2013
@see getc()
sl@0
  2014
@see mbrtowc()
sl@0
  2015
@see printf()
sl@0
  2016
@see strtod()
sl@0
  2017
@see strtol()
sl@0
  2018
@see strtoul()
sl@0
  2019
@see wscanf()
sl@0
  2020
 
sl@0
  2021
sl@0
  2022
@publishedAll
sl@0
  2023
@externallyDefinedApi
sl@0
  2024
*/
sl@0
  2025
sl@0
  2026
/** @fn  tmpfile(void)
sl@0
  2027
sl@0
  2028
sl@0
  2029
Note: This description also covers the following functions -
sl@0
  2030
 tmpnam()  tempnam() 
sl@0
  2031
sl@0
  2032
@return   The tmpfile function
sl@0
  2033
returns a pointer to an open file stream on success, and a NULL pointer
sl@0
  2034
on error. The tmpnam and tempfile functions
sl@0
  2035
return a pointer to a file name on success, and a NULL pointer
sl@0
  2036
on error.
sl@0
  2037
sl@0
  2038
  The tmpfile function
sl@0
  2039
returns a pointer to a stream associated with a file descriptor returned
sl@0
  2040
by the routine mkstemp .
sl@0
  2041
The created file is unlinked before tmpfile returns, causing the file to be automatically deleted when the last
sl@0
  2042
reference to it is closed.
sl@0
  2043
The file is opened with the access value 'w+'.
sl@0
  2044
The file is created in the directory determined by the environment variable TMPDIR if set.
sl@0
  2045
The default location if TMPDIR is not set is /tmp .
sl@0
  2046
sl@0
  2047
@code
sl@0
  2048
 The tmpnam function returns a pointer to a file name, in the P_tmpdir directory, which did not reference an existing file at some 
sl@0
  2049
  indeterminate point in the past. P_tmpdir is defined in the include file #include <stdio.h>. If the argument str is non- NULL , the file name is copied to the buffer it references. Otherwise, 
sl@0
  2050
  the file name is copied to a static buffer. In either case, tmpnam returns a pointer to the file name.
sl@0
  2051
@endcode
sl@0
  2052
 The buffer referenced by str is expected to be at least L_tmpnam bytes in length. L_tmpnam is defined in the include file \#include \<stdio.h\>.
sl@0
  2053
sl@0
  2054
 The tempnam function
sl@0
  2055
is similar to tmpnam ,
sl@0
  2056
but provides the ability to specify the directory which will
sl@0
  2057
contain the temporary file and the file name prefix.
sl@0
  2058
sl@0
  2059
 The environment variable TMPDIR (if set), the argument tmpdir (if non- NULL ),
sl@0
  2060
the directory P_tmpdir ,
sl@0
  2061
and the directory /tmp are tried, in the listed order, as directories in which to store the
sl@0
  2062
temporary file.
sl@0
  2063
sl@0
  2064
 The argument prefix , if non- NULL , is used to specify a file name prefix, which will be the 
sl@0
  2065
  first part of the created file name. The tempnam function allocates memory in which to store the file name; 
sl@0
  2066
  the returned pointer may be used as a subsequent argument to free .
sl@0
  2067
sl@0
  2068
Examples:
sl@0
  2069
@code
sl@0
  2070
#include<stdio.h> //SEEK_SET, printf, tmpfile, FILE
sl@0
  2071
#include<sys/stat.h> //S_IWUSR
sl@0
  2072
 
sl@0
  2073
int main()
sl@0
  2074
{
sl@0
  2075
//create the tmp directory
sl@0
  2076
 mkdir("c:\tmp", S_IWUSR);
sl@0
  2077
 
sl@0
  2078
//call tmpfile to create a tempory file
sl@0
  2079
 FILE* fp = tmpfile();
sl@0
  2080
 char buf[10];
sl@0
  2081
 
sl@0
  2082
 if(fp)
sl@0
  2083
 {
sl@0
  2084
     //write onto the file
sl@0
  2085
     fprintf(fp, "%s", "hello");
sl@0
  2086
     fflush(fp);
sl@0
  2087
  
sl@0
  2088
     //seek to the beginning of the file
sl@0
  2089
     fseek(fp, SEEK_SET, 0); //beg of the file
sl@0
  2090
  
sl@0
  2091
     //read from the file
sl@0
  2092
     fscanf(fp, "%s", buf);
sl@0
  2093
     fflush(fp);
sl@0
  2094
 
sl@0
  2095
     //close the file
sl@0
  2096
     fclose(fp);
sl@0
  2097
 }
sl@0
  2098
 
sl@0
  2099
 printf("buf read: %s", buf);
sl@0
  2100
 
sl@0
  2101
 return 0;
sl@0
  2102
}
sl@0
  2103
sl@0
  2104
@endcode
sl@0
  2105
@code
sl@0
  2106
Output
sl@0
  2107
sl@0
  2108
buf read: hello
sl@0
  2109
sl@0
  2110
@endcode
sl@0
  2111
@code
sl@0
  2112
#include<stdio.h> //tmpnam, printf, FILE
sl@0
  2113
#include<sys/stat.h> //S_IWUSR
sl@0
  2114
#include<errno.h> //errno
sl@0
  2115
  
sl@0
  2116
int main()
sl@0
  2117
{
sl@0
  2118
 //create a directory c:\system emp
sl@0
  2119
 mkdir("c:\system\temp", S_IWUSR);
sl@0
  2120
  
sl@0
  2121
 char buf[L_tmpnam];
sl@0
  2122
 char rbuf[10];
sl@0
  2123
  
sl@0
  2124
 //call tmpnam() to create a file
sl@0
  2125
 char *rval = tmpnam(buf);
sl@0
  2126
  
sl@0
  2127
 errno = 0;
sl@0
  2128
 //open the file with the name returned by tmpnam()
sl@0
  2129
 FILE *fp = fopen(buf, "w");
sl@0
  2130
  
sl@0
  2131
 if (fp == NULL)
sl@0
  2132
 {
sl@0
  2133
     printf("fopen of file returned by tmpnam() failed - errno %d ", errno);
sl@0
  2134
     return -1;
sl@0
  2135
 }
sl@0
  2136
    
sl@0
  2137
 if(fp)
sl@0
  2138
 {
sl@0
  2139
    fprintf(fp, "%s", "check");
sl@0
  2140
    fclose(fp);
sl@0
  2141
 }
sl@0
  2142
   
sl@0
  2143
 fp = fopen(buf, "r");
sl@0
  2144
  
sl@0
  2145
 if(fp)
sl@0
  2146
 {
sl@0
  2147
     fscanf(fp, "%s", rbuf);
sl@0
  2148
     fclose(fp);
sl@0
  2149
 }
sl@0
  2150
  
sl@0
  2151
 printf("read from file: %s", rbuf);
sl@0
  2152
 printf("argument buf: %s", buf);
sl@0
  2153
 printf("return value: %s", rval);
sl@0
  2154
  
sl@0
  2155
 return 0;
sl@0
  2156
}
sl@0
  2157
sl@0
  2158
@endcode
sl@0
  2159
@code
sl@0
  2160
Output
sl@0
  2161
sl@0
  2162
read from file: check
sl@0
  2163
argument buf: /System/temp/tmp.0.U9UPTx
sl@0
  2164
return value: /System/temp/tmp.0.U9UPTx
sl@0
  2165
sl@0
  2166
@endcode
sl@0
  2167
sl@0
  2168
Limitations:
sl@0
  2169
sl@0
  2170
- The str parameter in tmpnam() respectively should not exceed 256 characters in length.
sl@0
  2171
- The tmpdir parameter in tempnam() respectively should not exceed 256 characters in length. 
sl@0
  2172
sl@0
  2173
@see mktemp()
sl@0
  2174
sl@0
  2175
sl@0
  2176
sl@0
  2177
@capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&)
sl@0
  2178
sl@0
  2179
@publishedAll
sl@0
  2180
@externallyDefinedApi
sl@0
  2181
*/
sl@0
  2182
sl@0
  2183
/** @fn  tmpfile64(void)
sl@0
  2184
sl@0
  2185
For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0
sl@0
  2186
sl@0
  2187
@see tmpfile()
sl@0
  2188
sl@0
  2189
@publishedAll
sl@0
  2190
@externallyDefinedApi
sl@0
  2191
*/
sl@0
  2192
sl@0
  2193
/** @fn  tmpnam(char *str)
sl@0
  2194
@param str
sl@0
  2195
sl@0
  2196
Refer to  tmpfile() for the documentation
sl@0
  2197
@see mktemp()
sl@0
  2198
sl@0
  2199
sl@0
  2200
sl@0
  2201
@capability Deferred @ref RFs::MkDir(const TDesC16&)
sl@0
  2202
@capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&)
sl@0
  2203
sl@0
  2204
@publishedAll
sl@0
  2205
@externallyDefinedApi
sl@0
  2206
*/
sl@0
  2207
sl@0
  2208
/** @fn  ungetc(int c, FILE *fp)
sl@0
  2209
@param c
sl@0
  2210
@param fp
sl@0
  2211
@return   The ungetc function returns the character pushed-back after the conversion,
sl@0
  2212
or EOF if the operation fails.
sl@0
  2213
If the value of the argument c character equals EOF ,
sl@0
  2214
the operation will fail and the fp will remain unchanged.
sl@0
  2215
sl@0
  2216
  The ungetc function pushes the character c (converted to an unsigned char)
sl@0
  2217
back onto the input stream pointed to by fp .
sl@0
  2218
The pushed-back characters will be returned by subsequent reads on the
sl@0
  2219
stream (in reverse order).
sl@0
  2220
A successful intervening call,
sl@0
  2221
using the same stream,
sl@0
  2222
to one of the file positioning functions
sl@0
  2223
( fsetpos or rewind )
sl@0
  2224
will discard the pushed back characters.
sl@0
  2225
sl@0
  2226
 One character of push-back is guaranteed,
sl@0
  2227
but as long as there is sufficient memory,
sl@0
  2228
an effectively infinite amount of pushback is allowed.
sl@0
  2229
sl@0
  2230
 If a character is successfully pushed-back,
sl@0
  2231
the end-of-file indicator for the stream is cleared.
sl@0
  2232
The file-position indicator is decremented
sl@0
  2233
by each successful call to ungetc ;
sl@0
  2234
if its value was 0 before a call, its value is unspecified after
sl@0
  2235
the call.
sl@0
  2236
sl@0
  2237
sl@0
  2238
Examples:
sl@0
  2239
@code
sl@0
  2240
/* this pushing character to file stream using ungetc */
sl@0
  2241
#include <stdio.h>
sl@0
  2242
int main(void)
sl@0
  2243
{
sl@0
  2244
        int c;
sl@0
  2245
        FILE *fp = NULL;
sl@0
  2246
        if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughtout the appln.
sl@0
  2247
        	{
sl@0
  2248
        	printf("Failed to set text-mode\n");
sl@0
  2249
        	return -1;
sl@0
  2250
        	}
sl@0
  2251
        fp = fopen("c:\input.txt", "w");
sl@0
  2252
        fprintf(fp, "%s", "abcdefghijklmn");
sl@0
  2253
        fprintf(fp, "%c", '');
sl@0
  2254
        fprintf(fp, "%s", "fdsfdsafsdabcdefghijklmn");
sl@0
  2255
        fclose(fp);
sl@0
  2256
        char * name = "C:\input.txt";
sl@0
  2257
        fp = fopen(name, "w+");
sl@0
  2258
        if (fp == NULL)
sl@0
  2259
                {
sl@0
  2260
                printf ("fopen failed");
sl@0
  2261
                return -1;
sl@0
  2262
                }
sl@0
  2263
        if(ungetc('a',fp)!='a') printf("ungetc failed");
sl@0
  2264
        
sl@0
  2265
        fseek(fp,-1,SEEK_CUR);
sl@0
  2266
        c=getc(fp);
sl@0
  2267
        printf("character read from stream is \"%c\",c);
sl@0
  2268
        fclose(fp);
sl@0
  2269
}
sl@0
  2270
sl@0
  2271
@endcode
sl@0
  2272
@code
sl@0
  2273
Output
sl@0
  2274
sl@0
  2275
 character read from stream is "a"
sl@0
  2276
sl@0
  2277
@endcode
sl@0
  2278
@see fseek()
sl@0
  2279
@see getc()
sl@0
  2280
@see ungetwc()
sl@0
  2281
@see set_fmode() 
sl@0
  2282
sl@0
  2283
@publishedAll
sl@0
  2284
@externallyDefinedApi
sl@0
  2285
*/
sl@0
  2286
sl@0
  2287
/** @fn  vfprintf(FILE *fp, const char *fmt0, va_list ap)
sl@0
  2288
@param fp
sl@0
  2289
@param fmt0
sl@0
  2290
@param ap
sl@0
  2291
sl@0
  2292
Refer to  printf() for the documentation
sl@0
  2293
@see printf()
sl@0
  2294
@see scanf()
sl@0
  2295
@see setlocale()
sl@0
  2296
@see wprintf()
sl@0
  2297
 
sl@0
  2298
sl@0
  2299
@publishedAll
sl@0
  2300
@externallyDefinedApi
sl@0
  2301
*/
sl@0
  2302
sl@0
  2303
/** @fn  vprintf(const char *  fmt, va_list ap)
sl@0
  2304
@param fmt
sl@0
  2305
@param ap
sl@0
  2306
sl@0
  2307
Refer to  printf() for the documentation
sl@0
  2308
@see printf()
sl@0
  2309
@see scanf()
sl@0
  2310
@see setlocale()
sl@0
  2311
@see wprintf()
sl@0
  2312
 
sl@0
  2313
sl@0
  2314
@publishedAll
sl@0
  2315
@externallyDefinedApi
sl@0
  2316
*/
sl@0
  2317
sl@0
  2318
/** @fn  vsprintf(char *  str, const char *fmt, va_list ap)
sl@0
  2319
@param str
sl@0
  2320
@param fmt
sl@0
  2321
@param ap
sl@0
  2322
sl@0
  2323
Refer to  printf() for the documentation
sl@0
  2324
@see printf()
sl@0
  2325
@see scanf()
sl@0
  2326
@see setlocale()
sl@0
  2327
@see wprintf()
sl@0
  2328
 
sl@0
  2329
sl@0
  2330
@publishedAll
sl@0
  2331
@externallyDefinedApi
sl@0
  2332
*/
sl@0
  2333
sl@0
  2334
/** @fn  snprintf(char *  str, size_t n, const char *  fmt, ...)
sl@0
  2335
@param str
sl@0
  2336
@param n
sl@0
  2337
@param fmt
sl@0
  2338
@param ...
sl@0
  2339
sl@0
  2340
Refer to  printf() for the documentation
sl@0
  2341
@see printf()
sl@0
  2342
@see scanf()
sl@0
  2343
@see setlocale()
sl@0
  2344
@see wprintf()
sl@0
  2345
 
sl@0
  2346
sl@0
  2347
@publishedAll
sl@0
  2348
@externallyDefinedApi
sl@0
  2349
*/
sl@0
  2350
sl@0
  2351
/** @fn  vfscanf(FILE *  stream, const char *  format, va_list ap)
sl@0
  2352
@param stream
sl@0
  2353
@param format
sl@0
  2354
@param ap
sl@0
  2355
sl@0
  2356
Refer to  scanf() for the documentation
sl@0
  2357
@see getc()
sl@0
  2358
@see mbrtowc()
sl@0
  2359
@see printf()
sl@0
  2360
@see strtod()
sl@0
  2361
@see strtol()
sl@0
  2362
@see strtoul()
sl@0
  2363
@see wscanf()
sl@0
  2364
 
sl@0
  2365
sl@0
  2366
@publishedAll
sl@0
  2367
@externallyDefinedApi
sl@0
  2368
*/
sl@0
  2369
sl@0
  2370
/** @fn  vscanf(const char *fmt, va_list ap)
sl@0
  2371
@param fmt
sl@0
  2372
@param ap
sl@0
  2373
sl@0
  2374
Refer to  scanf() for the documentation
sl@0
  2375
@see getc()
sl@0
  2376
@see mbrtowc()
sl@0
  2377
@see printf()
sl@0
  2378
@see strtod()
sl@0
  2379
@see strtol()
sl@0
  2380
@see strtoul()
sl@0
  2381
@see wscanf()
sl@0
  2382
 
sl@0
  2383
sl@0
  2384
@publishedAll
sl@0
  2385
@externallyDefinedApi
sl@0
  2386
*/
sl@0
  2387
sl@0
  2388
/** @fn  vsnprintf(char *  str, size_t n, const char *  fmt, va_list ap)
sl@0
  2389
@param str
sl@0
  2390
@param n
sl@0
  2391
@param fmt
sl@0
  2392
@param ap
sl@0
  2393
sl@0
  2394
Refer to  printf() for the documentation
sl@0
  2395
@see printf()
sl@0
  2396
@see scanf()
sl@0
  2397
@see setlocale()
sl@0
  2398
@see wprintf()
sl@0
  2399
 
sl@0
  2400
sl@0
  2401
@publishedAll
sl@0
  2402
@externallyDefinedApi
sl@0
  2403
*/
sl@0
  2404
sl@0
  2405
/** @fn  vsscanf(const char *  str, const char *  format, va_list ap)
sl@0
  2406
@param str
sl@0
  2407
@param format
sl@0
  2408
@param ap
sl@0
  2409
sl@0
  2410
Refer to  scanf() for the documentation
sl@0
  2411
@see getc()
sl@0
  2412
@see mbrtowc()
sl@0
  2413
@see printf()
sl@0
  2414
@see strtod()
sl@0
  2415
@see strtol()
sl@0
  2416
@see strtoul()
sl@0
  2417
@see wscanf()
sl@0
  2418
 
sl@0
  2419
sl@0
  2420
@publishedAll
sl@0
  2421
@externallyDefinedApi
sl@0
  2422
*/
sl@0
  2423
sl@0
  2424
/** @fn  fdopen(int fd, const char *mode)
sl@0
  2425
@param fd
sl@0
  2426
@param mode
sl@0
  2427
sl@0
  2428
Refer to  fopen() for the documentation
sl@0
  2429
@see open()
sl@0
  2430
@see fclose()
sl@0
  2431
@see fileno()
sl@0
  2432
@see fseek()
sl@0
  2433
 
sl@0
  2434
sl@0
  2435
@publishedAll
sl@0
  2436
@externallyDefinedApi
sl@0
  2437
*/
sl@0
  2438
sl@0
  2439
/** @fn  fileno(FILE *fp)
sl@0
  2440
@param fp
sl@0
  2441
sl@0
  2442
Refer to  clearerr() for the documentation
sl@0
  2443
@see open()
sl@0
  2444
@see flockfile()
sl@0
  2445
 
sl@0
  2446
sl@0
  2447
@publishedAll
sl@0
  2448
@externallyDefinedApi
sl@0
  2449
*/
sl@0
  2450
sl@0
  2451
/** @fn  popen(const char *command, const char *mode)
sl@0
  2452
@param command
sl@0
  2453
@param mode
sl@0
  2454
sl@0
  2455
Notes:
sl@0
  2456
sl@0
  2457
1. This description also covers the pclose() function.
sl@0
  2458
sl@0
  2459
2. When a child process created using popen() exits, the parent process receives a SIGCHLD signal.
sl@0
  2460
sl@0
  2461
@return   The popen function returns NULL if the fork
sl@0
  2462
or pipe calls fail,
sl@0
  2463
or if it cannot allocate memory. The pclose function returns -1 if stream is not associated with a "popened" command, if stream already "pclosed" or if wait4
sl@0
  2464
returns an error.
sl@0
  2465
sl@0
  2466
  The popen function opens a process by creating a pipe, forking, and invoking 
sl@0
  2467
the shell. Since a pipe is by definition unidirectional, the type argument may specify only reading or writing, not both. The resulting 
sl@0
  2468
stream is correspondingly read-only ("r") or write-only "w". If type is anything 
sl@0
  2469
other than this the behavior is undefined.
sl@0
  2470
sl@0
  2471
 The command argument is a pointer to a null-terminated string containing a shell command line.
sl@0
  2472
This command is passed to /bin/sh using the - c flag; interpretation, if any, is performed by the shell.
sl@0
  2473
sl@0
  2474
 The return value from popen is a normal standard I/O stream in all respects save that it must be closed with pclose rather than fclose. Writing to such a stream writes to the standard input of the 
sl@0
  2475
  command. The command's standard output is the same as that of the process 
sl@0
  2476
  that called popen, unless this is altered by the command itself. Conversely, reading 
sl@0
  2477
  from a "popened" stream reads the command's standard output, and the command's 
sl@0
  2478
  standard input is the same as that of the process that called popen.
sl@0
  2479
sl@0
  2480
 Note that output popen streams are fully buffered by default.
sl@0
  2481
sl@0
  2482
 The pclose function waits for the associated process to terminate
sl@0
  2483
and returns the exit status of the command
sl@0
  2484
as returned by
sl@0
  2485
wait4.
sl@0
  2486
sl@0
  2487
sl@0
  2488
sl@0
  2489
@see pipe()
sl@0
  2490
@see fclose()
sl@0
  2491
@see fflush()
sl@0
  2492
@see fopen()
sl@0
  2493
@see system()
sl@0
  2494
sl@0
  2495
sl@0
  2496
Bugs:
sl@0
  2497
sl@0
  2498
 Since the standard input of a command opened for reading
sl@0
  2499
shares its seek offset with the process that called popen, if the original process has done a buffered read,
sl@0
  2500
the command's input position may not be as expected.
sl@0
  2501
Similarly, the output from a command opened for writing
sl@0
  2502
may become intermingled with that of the original process.
sl@0
  2503
The latter can be avoided by calling fflush before popen. Failure to execute the shell
sl@0
  2504
is indistinguishable from the shell's failure to execute command,
sl@0
  2505
or an immediate exit of the command.
sl@0
  2506
The only hint is an exit status of 127. The popen function
sl@0
  2507
always calls sh and never calls csh. 
sl@0
  2508
 
sl@0
  2509
sl@0
  2510
@publishedAll
sl@0
  2511
@externallyDefinedApi
sl@0
  2512
*/
sl@0
  2513
sl@0
  2514
/** @fn popen3(const char *file, const char *cmd, char** envp, int fds[3])
sl@0
  2515
sl@0
  2516
Open stdin, stdout, and stderr streams and start external executable.
sl@0
  2517
sl@0
  2518
Note: When a child process created using popen3() exits, the parent process receives a SIGCHLD signal.
sl@0
  2519
sl@0
  2520
@publishedAll
sl@0
  2521
@externallyDefinedApi
sl@0
  2522
*/
sl@0
  2523
sl@0
  2524
/** @fn  ftrylockfile(FILE *fp)
sl@0
  2525
@param fp
sl@0
  2526
sl@0
  2527
Refer to  flockfile() for the documentation
sl@0
  2528
@see getc_unlocked()
sl@0
  2529
@see putc_unlocked()
sl@0
  2530
 
sl@0
  2531
sl@0
  2532
@publishedAll
sl@0
  2533
@externallyDefinedApi
sl@0
  2534
*/
sl@0
  2535
sl@0
  2536
/** @fn  flockfile(FILE *fp)
sl@0
  2537
@param fp
sl@0
  2538
sl@0
  2539
Note: This description also covers the following functions -
sl@0
  2540
 ftrylockfile()  funlockfile() 
sl@0
  2541
sl@0
  2542
@return   The flockfile and funlockfile functions return no value. The ftrylockfile function
sl@0
  2543
returns zero if the stream was successfully locked,non-zero otherwise.
sl@0
  2544
sl@0
  2545
These functions provide explicit application-level locking of stdio streams.
sl@0
  2546
They can be used to avoid output from multiple threads being interspersed,
sl@0
  2547
input being dispersed among multiple readers, and to avoid the overhead
sl@0
  2548
of locking the stream for each operation.
sl@0
  2549
sl@0
  2550
 The flockfile function acquires an exclusive lock on the specified stream. 
sl@0
  2551
  If another thread has already locked the stream flockfile will block until the lock is released.
sl@0
  2552
sl@0
  2553
 The ftrylockfile function is a non-blocking version of flockfile; if the lock cannot be acquired immediately ftrylockfile returns non-zero instead of blocking.
sl@0
  2554
sl@0
  2555
 The funlockfile function releases the lock on a stream acquired by an earlier call to flockfile or ftrylockfile.
sl@0
  2556
sl@0
  2557
 These functions behave as if there is a lock count associated with each stream. 
sl@0
  2558
  Each time flockfile is called on the stream the count is incremented and each 
sl@0
  2559
  time funlockfile is called on the stream the count is decremented. The 
sl@0
  2560
  lock is only actually released when the count reaches zero.
sl@0
  2561
  
sl@0
  2562
  
sl@0
  2563
Examples:
sl@0
  2564
@code
sl@0
  2565
#include <stdio.h>
sl@0
  2566
#include <unistd.h>
sl@0
  2567
#include <pthread.h> //link to the lib -libpthread
sl@0
  2568
 
sl@0
  2569
void* somefun(void* args)
sl@0
  2570
{
sl@0
  2571
FILE *fp = (FILE *)args;
sl@0
  2572
printf("in thr 2");
sl@0
  2573
flockfile(fp);
sl@0
  2574
printf("aquired lock!");
sl@0
  2575
fputc('a', fp); //fputc_unlocked() is more relevant
sl@0
  2576
printf("after a from thr 2");
sl@0
  2577
sleep(3);
sl@0
  2578
printf("after sleep from thr 2");
sl@0
  2579
fputc('b', fp);
sl@0
  2580
printf("after b from thr 2");
sl@0
  2581
fputc('c', fp);
sl@0
  2582
printf("after c from thr 2");
sl@0
  2583
funlockfile(fp);
sl@0
  2584
fclose(fp);
sl@0
  2585
}
sl@0
  2586
int main()
sl@0
  2587
{
sl@0
  2588
pthread_t obj;
sl@0
  2589
FILE *fp = NULL;
sl@0
  2590
if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughtout the appln.
sl@0
  2591
	{
sl@0
  2592
    printf("Failed to set text-mode\n");
sl@0
  2593
    return -1;
sl@0
  2594
	}
sl@0
  2595
fp = fopen("c:\chk.txt", "w");
sl@0
  2596
if(fp)
sl@0
  2597
{
sl@0
  2598
        flockfile(fp);
sl@0
  2599
        fputc('x', fp); //fputc_unlocked() is more relevant
sl@0
  2600
        printf("after x from thr 1");
sl@0
  2601
        sleep(5);
sl@0
  2602
        printf("after sleep from thr 1");
sl@0
  2603
        pthread_create(&obj;, NULL, somefun, fp);
sl@0
  2604
        printf("after calling thr 2 from thr 1");
sl@0
  2605
        fputc('y', fp);
sl@0
  2606
        printf("after y from thr 1");
sl@0
  2607
        fputc('z', fp);
sl@0
  2608
        printf("after z from thr 1");
sl@0
  2609
        funlockfile(fp);
sl@0
  2610
        printf("gave up lock in thr 1");
sl@0
  2611
}
sl@0
  2612
pthread_exit((void *)0);
sl@0
  2613
}
sl@0
  2614
sl@0
  2615
@endcode
sl@0
  2616
@code
sl@0
  2617
Output
sl@0
  2618
sl@0
  2619
after x from thr 1
sl@0
  2620
after sleep from thr 1
sl@0
  2621
in thr 2
sl@0
  2622
after calling thr 2 from thr 1
sl@0
  2623
after y from thr 1
sl@0
  2624
after z from thr 1
sl@0
  2625
gave up lock in thr 1
sl@0
  2626
acquired lock!
sl@0
  2627
after a from thr 2
sl@0
  2628
after sleep from thr 2
sl@0
  2629
after b from thr 2
sl@0
  2630
after c from thr 2
sl@0
  2631
  
sl@0
  2632
Note: The printing takes quite some time and hence the
sl@0
  2633
output may not look exactly like the above one.
sl@0
  2634
(try printing to the files if you are very particular)
sl@0
  2635
 
sl@0
  2636
sl@0
  2637
@endcode
sl@0
  2638
@code
sl@0
  2639
#include <stdio.h>
sl@0
  2640
#include <unistd.h>
sl@0
  2641
#include <pthread.h> //link to lib -libpthread
sl@0
  2642
#include <errno.h>
sl@0
  2643
 
sl@0
  2644
void* somefun(void* args)
sl@0
  2645
{
sl@0
  2646
 
sl@0
  2647
FILE *fp = (FILE *)args;
sl@0
  2648
 
sl@0
  2649
printf("in thr 2
sl@0
  2650
");
sl@0
  2651
 
sl@0
  2652
int i = ftrylockfile(fp);
sl@0
  2653
if(i == 0)
sl@0
  2654
{
sl@0
  2655
        printf("aquired lock!");
sl@0
  2656
        fputc('a', fp);
sl@0
  2657
        printf("after a from thr 2");
sl@0
  2658
        sleep(3);
sl@0
  2659
        printf("after sleep from thr 2");
sl@0
  2660
        fputc('b', fp);
sl@0
  2661
        printf("after b from thr 2");
sl@0
  2662
        fputc('c', fp);
sl@0
  2663
        printf("after c from thr 2");
sl@0
  2664
        funlockfile(fp);
sl@0
  2665
        printf("gave up lock in thr 2");
sl@0
  2666
}
sl@0
  2667
else
sl@0
  2668
        printf("couldn't aquire lock");
sl@0
  2669
}
sl@0
  2670
int main()
sl@0
  2671
{
sl@0
  2672
pthread_t obj;
sl@0
  2673
FILE *fp = NULL;
sl@0
  2674
if( set_fmode('t') != 0 )					// setting text-mode as default file opening mode throughtout the appln.
sl@0
  2675
	{
sl@0
  2676
    printf("Failed to set text-mode\n");
sl@0
  2677
    return -1;
sl@0
  2678
	}
sl@0
  2679
fp = fopen("c:\chk.txt", "w");
sl@0
  2680
 
sl@0
  2681
if(fp)
sl@0
  2682
{
sl@0
  2683
        flockfile(fp);
sl@0
  2684
        fputc('x', fp);
sl@0
  2685
        printf("after x from thr 1");
sl@0
  2686
        sleep(5);
sl@0
  2687
        printf("after sleep from thr 1");
sl@0
  2688
        pthread_create(&obj;, NULL, somefun, fp);
sl@0
  2689
        printf("after calling thr 2 from thr 1");
sl@0
  2690
        fputc('y', fp);
sl@0
  2691
        printf("after y from thr 1");
sl@0
  2692
        fputc('z', fp);
sl@0
  2693
        printf("after z from thr 1");
sl@0
  2694
        funlockfile(fp);
sl@0
  2695
        printf("gave up lock in thr 1");
sl@0
  2696
        sleep(5);
sl@0
  2697
        fclose(fp);
sl@0
  2698
}
sl@0
  2699
pthread_exit((void *)0);
sl@0
  2700
}
sl@0
  2701
sl@0
  2702
@endcode
sl@0
  2703
@code
sl@0
  2704
Output
sl@0
  2705
sl@0
  2706
after x from thr 1
sl@0
  2707
after sleep from thr 1
sl@0
  2708
in thr 2
sl@0
  2709
couldn't acquire lock
sl@0
  2710
after calling thr 2 from thr 1
sl@0
  2711
after y from thr 1
sl@0
  2712
after z from thr 1
sl@0
  2713
gave up lock in thr 1
sl@0
  2714
  
sl@0
  2715
Note: The printing takes quite some time and hence the
sl@0
  2716
output may not look exactly like the above one.
sl@0
  2717
(try printing to the files if you are very particular)
sl@0
  2718
  
sl@0
  2719
sl@0
  2720
@endcode
sl@0
  2721
@see getc_unlocked()
sl@0
  2722
@see putc_unlocked()
sl@0
  2723
@see set_fmode() 
sl@0
  2724
sl@0
  2725
@publishedAll
sl@0
  2726
@externallyDefinedApi
sl@0
  2727
*/
sl@0
  2728
sl@0
  2729
/** @fn  funlockfile(FILE *fp)
sl@0
  2730
@param fp
sl@0
  2731
sl@0
  2732
Refer to  flockfile() for the documentation
sl@0
  2733
@see getc_unlocked()
sl@0
  2734
@see putc_unlocked()
sl@0
  2735
 
sl@0
  2736
sl@0
  2737
@publishedAll
sl@0
  2738
@externallyDefinedApi
sl@0
  2739
*/
sl@0
  2740
sl@0
  2741
/** @fn  getc_unlocked(FILE *fp)
sl@0
  2742
@param fp
sl@0
  2743
sl@0
  2744
Refer to  fgetc() for the documentation
sl@0
  2745
@see ferror()
sl@0
  2746
@see flockfile()
sl@0
  2747
@see fopen()
sl@0
  2748
@see fread()
sl@0
  2749
@see getwc()
sl@0
  2750
@see putc()
sl@0
  2751
@see ungetc()
sl@0
  2752
 
sl@0
  2753
sl@0
  2754
@publishedAll
sl@0
  2755
@externallyDefinedApi
sl@0
  2756
*/
sl@0
  2757
sl@0
  2758
/** @fn  getchar_unlocked(void)
sl@0
  2759
sl@0
  2760
sl@0
  2761
Refer to  fgetc() for the documentation
sl@0
  2762
@see ferror()
sl@0
  2763
@see flockfile()
sl@0
  2764
@see fopen()
sl@0
  2765
@see fread()
sl@0
  2766
@see getwc()
sl@0
  2767
@see putc()
sl@0
  2768
@see ungetc()
sl@0
  2769
 
sl@0
  2770
sl@0
  2771
@publishedAll
sl@0
  2772
@externallyDefinedApi
sl@0
  2773
*/
sl@0
  2774
sl@0
  2775
/** @fn  putc_unlocked(int ch, FILE *fp)
sl@0
  2776
@param ch
sl@0
  2777
@param fp
sl@0
  2778
sl@0
  2779
Refer to  fputc() for the documentation
sl@0
  2780
@see ferror()
sl@0
  2781
@see flockfile()
sl@0
  2782
@see fopen()
sl@0
  2783
@see getc()
sl@0
  2784
@see putwc()
sl@0
  2785
 
sl@0
  2786
sl@0
  2787
@publishedAll
sl@0
  2788
@externallyDefinedApi
sl@0
  2789
*/
sl@0
  2790
sl@0
  2791
/** @fn  putchar_unlocked(int ch)
sl@0
  2792
@param ch
sl@0
  2793
sl@0
  2794
Refer to  fputc() for the documentation
sl@0
  2795
@see ferror()
sl@0
  2796
@see flockfile()
sl@0
  2797
@see fopen()
sl@0
  2798
@see getc()
sl@0
  2799
@see putwc()
sl@0
  2800
 
sl@0
  2801
sl@0
  2802
@publishedAll
sl@0
  2803
@externallyDefinedApi
sl@0
  2804
*/
sl@0
  2805
sl@0
  2806
/** @fn  getw(FILE *fp)
sl@0
  2807
@param fp
sl@0
  2808
sl@0
  2809
Refer to  fgetc() for the documentation
sl@0
  2810
@see ferror()
sl@0
  2811
@see flockfile()
sl@0
  2812
@see fopen()
sl@0
  2813
@see fread()
sl@0
  2814
@see getwc()
sl@0
  2815
@see putc()
sl@0
  2816
@see ungetc()
sl@0
  2817
 
sl@0
  2818
sl@0
  2819
@publishedAll
sl@0
  2820
@externallyDefinedApi
sl@0
  2821
*/
sl@0
  2822
sl@0
  2823
/** @fn  putw(int w, FILE *fp)
sl@0
  2824
@param w
sl@0
  2825
@param fp
sl@0
  2826
sl@0
  2827
Refer to  fputc() for the documentation
sl@0
  2828
@see ferror()
sl@0
  2829
@see flockfile()
sl@0
  2830
@see fopen()
sl@0
  2831
@see getc()
sl@0
  2832
@see putwc()
sl@0
  2833
 
sl@0
  2834
sl@0
  2835
@publishedAll
sl@0
  2836
@externallyDefinedApi
sl@0
  2837
*/
sl@0
  2838
sl@0
  2839
/** @fn tempnam(const char *, const char *)
sl@0
  2840
Refer to tmpfile() for the documentation
sl@0
  2841
@publishedAll
sl@0
  2842
@externallyDefinedApi
sl@0
  2843
*/
sl@0
  2844
sl@0
  2845
/** @fn  asprintf(char **str, const char *fmt, ...)
sl@0
  2846
@param str
sl@0
  2847
@param fmt
sl@0
  2848
@param ...
sl@0
  2849
sl@0
  2850
Refer to  printf() for the documentation
sl@0
  2851
@see printf()
sl@0
  2852
@see scanf()
sl@0
  2853
@see setlocale()
sl@0
  2854
@see wprintf()
sl@0
  2855
 
sl@0
  2856
sl@0
  2857
@publishedAll
sl@0
  2858
@externallyDefinedApi
sl@0
  2859
*/
sl@0
  2860
sl@0
  2861
/** @fn  setbuffer(FILE *fp, char *buf, int size)
sl@0
  2862
@param fp
sl@0
  2863
@param buf
sl@0
  2864
@param size
sl@0
  2865
sl@0
  2866
Refer to  setbuf() for the documentation
sl@0
  2867
@see fopen()
sl@0
  2868
@see fread()
sl@0
  2869
@see malloc()
sl@0
  2870
@see printf()
sl@0
  2871
 
sl@0
  2872
sl@0
  2873
@publishedAll
sl@0
  2874
@externallyDefinedApi
sl@0
  2875
*/
sl@0
  2876
sl@0
  2877
/** @fn  setlinebuf(FILE *fp)
sl@0
  2878
@param fp
sl@0
  2879
sl@0
  2880
Refer to  setbuf() for the documentation
sl@0
  2881
@see fopen()
sl@0
  2882
@see fread()
sl@0
  2883
@see malloc()
sl@0
  2884
@see printf()
sl@0
  2885
 
sl@0
  2886
sl@0
  2887
@publishedAll
sl@0
  2888
@externallyDefinedApi
sl@0
  2889
*/
sl@0
  2890
sl@0
  2891
/** @fn  vasprintf(char **str, const char *fmt, va_list ap)
sl@0
  2892
@param str
sl@0
  2893
@param fmt
sl@0
  2894
@param ap
sl@0
  2895
sl@0
  2896
Refer to  printf() for the documentation
sl@0
  2897
@see printf()
sl@0
  2898
@see scanf()
sl@0
  2899
@see setlocale()
sl@0
  2900
@see wprintf()
sl@0
  2901
 
sl@0
  2902
sl@0
  2903
@publishedAll
sl@0
  2904
@externallyDefinedApi
sl@0
  2905
*/
sl@0
  2906
sl@0
  2907
/** @fn  ftruncate(int fd, off_t length)
sl@0
  2908
@param fd
sl@0
  2909
@param length
sl@0
  2910
sl@0
  2911
Refer to  truncate() for the documentation
sl@0
  2912
@see open()
sl@0
  2913
 
sl@0
  2914
sl@0
  2915
@publishedAll
sl@0
  2916
@externallyDefinedApi
sl@0
  2917
*/
sl@0
  2918
sl@0
  2919
/** @fn  lseek(int fildes, off_t offset, int whence)
sl@0
  2920
@param fildes
sl@0
  2921
@param offset
sl@0
  2922
@param whence
sl@0
  2923
@return   Upon successful completion, lseek returns the resulting offset location as measured in bytes from the
sl@0
  2924
beginning of the file.
sl@0
  2925
Otherwise,
sl@0
  2926
a value of -1 is returned and errno is set to indicate
sl@0
  2927
the error.
sl@0
  2928
sl@0
  2929
The  lseek system call repositions the offset of the file descriptor  fildes to the argument  offset according to the directive  whence. 
sl@0
  2930
The argument  fildes must be an open file descriptor. The  lseek system call repositions the file position pointer associated with the file descriptor  fildes as follows:
sl@0
  2931
@code
sl@0
  2932
	If whence is SEEK_SET, the offset is set to offset bytes.
sl@0
  2933
	If whence is SEEK_CUR, the offset is set to its current location plus offset bytes.
sl@0
  2934
	If whence is SEEK_END, the offset is set to the size of the file plus offset bytes.
sl@0
  2935
@endcode
sl@0
  2936
Some devices are incapable of seeking. The value of the pointer associated with such a device is undefined.
sl@0
  2937
sl@0
  2938
Note: lseek function allows the file offset to be set beyond the existing end-of-file, data in the seeked slot is undefined, and hence the read operation in seeked slot is 
sl@0
  2939
undefined untill data is actually written into it. lseek beyond existing end-of-file increases the file size accordingly.
sl@0
  2940
sl@0
  2941
sl@0
  2942
sl@0
  2943
Examples:
sl@0
  2944
@code
sl@0
  2945
/* Detailed description  : Example for lseek usage.*/
sl@0
  2946
#include <stdio.h>
sl@0
  2947
#include <sys/stat.h>
sl@0
  2948
#include <fcntl.h>
sl@0
  2949
#include <sys/types.h>
sl@0
  2950
int main()
sl@0
  2951
{
sl@0
  2952
int fd = 0;
sl@0
  2953
 fd = open("lseek.txt"  , O_CREAT | O_RDWR , 0666);
sl@0
  2954
  if(lseek(fd , 0 , SEEK_SET) < 0 ) {
sl@0
  2955
     printf("Lseek on file lseek.txt failed");
sl@0
  2956
      return -1;
sl@0
  2957
  }
sl@0
  2958
  printf("Lseek on lseek.txt passed ");
sl@0
  2959
 return 0;
sl@0
  2960
}
sl@0
  2961
sl@0
  2962
@endcode
sl@0
  2963
@code
sl@0
  2964
Output
sl@0
  2965
sl@0
  2966
Lseek on lseek.txt passed
sl@0
  2967
sl@0
  2968
@endcode
sl@0
  2969
@see dup()
sl@0
  2970
@see open()
sl@0
  2971
 
sl@0
  2972
sl@0
  2973
@publishedAll
sl@0
  2974
@externallyDefinedApi
sl@0
  2975
*/
sl@0
  2976
sl@0
  2977
sl@0
  2978
/** @fn  truncate(const char *path, off_t length)
sl@0
  2979
@param path
sl@0
  2980
@param length
sl@0
  2981
sl@0
  2982
Note: This description also covers the following functions -
sl@0
  2983
 ftruncate() 
sl@0
  2984
sl@0
  2985
@return   Upon successful completion, both truncate() and ftruncate() return 0; otherwise, 
sl@0
  2986
they return -1 and set errno to indicate the error.
sl@0
  2987
sl@0
  2988
  The truncate system call
sl@0
  2989
causes the file named by path or referenced by fd to be truncated to length bytes in size.
sl@0
  2990
If the file
sl@0
  2991
was larger than this size, the extra data
sl@0
  2992
is lost.
sl@0
  2993
If the file was smaller than this size,
sl@0
  2994
it will be extended as if by writing bytes with the value zero.
sl@0
  2995
With ftruncate ,
sl@0
  2996
the file must be open for writing.
sl@0
  2997
sl@0
  2998
Examples:
sl@0
  2999
@code
sl@0
  3000
//example for truncate
sl@0
  3001
#include<unistd.h>
sl@0
  3002
#include<stdio.h>
sl@0
  3003
#include <sys/stat.h>
sl@0
  3004
int test_truncate()
sl@0
  3005
{
sl@0
  3006
        int retVal, retVal2, retSize, retSize2;
sl@0
  3007
        struct stat buf;
sl@0
  3008
        ssize_t size;
sl@0
  3009
        char *buffer = "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwx";
sl@0
  3010
        int fp = open("c:	est.txt", O_RDWR|O_CREAT);
sl@0
  3011
        size = write(fp,buffer,50);
sl@0
  3012
        close(fp);
sl@0
  3013
        retVal2 = stat("c:	est.txt", &buf; );
sl@0
  3014
        if ( !retVal2 )
sl@0
  3015
        {
sl@0
  3016
        retSize = buf.st_size;
sl@0
  3017
        printf("Size before: %d", retSize);
sl@0
  3018
        retVal = truncate("c:	est.txt", retSize/2 );
sl@0
  3019
        }
sl@0
  3020
        else
sl@0
  3021
        {
sl@0
  3022
        printf("Failed");
sl@0
  3023
        }
sl@0
  3024
        retVal2 = stat( "c:	est.txt", &buf; );
sl@0
  3025
        if ( !retVal2 )
sl@0
  3026
                {
sl@0
  3027
                retSize2 = buf.st_size;
sl@0
  3028
                if( retSize2 == (retSize/2 ) )
sl@0
  3029
                        {
sl@0
  3030
                        printf("Size after: %d", retSize2);
sl@0
  3031
                        printf("Truncate passed");
sl@0
  3032
                        return 0;
sl@0
  3033
                        }
sl@0
  3034
                else
sl@0
  3035
                        {
sl@0
  3036
                        printf("Failed");
sl@0
  3037
                        return -1;
sl@0
  3038
                        }
sl@0
  3039
                }
sl@0
  3040
        else
sl@0
  3041
                {
sl@0
  3042
                printf("Failed");
sl@0
  3043
                return -1;
sl@0
  3044
                }
sl@0
  3045
}
sl@0
  3046
sl@0
  3047
Output
sl@0
  3048
Size before: 50
sl@0
  3049
Size after: 25
sl@0
  3050
Ttruncate Passed
sl@0
  3051
@endcode
sl@0
  3052
sl@0
  3053
@code
sl@0
  3054
//example for ftruncate
sl@0
  3055
#include<unistd.h>
sl@0
  3056
#include<stdio.h>
sl@0
  3057
int test_ftruncate()
sl@0
  3058
{
sl@0
  3059
//assuming that the file exists and has some //data in it
sl@0
  3060
   int fp = open("c:	est.txt", O_RDWR);
sl@0
  3061
   int retVal, retVal2, retSize, retSize2;
sl@0
  3062
   struct stat buf;
sl@0
  3063
   if(fp != -1)
sl@0
  3064
   {
sl@0
  3065
     retVal2 = fstat( fp, &buf; );
sl@0
  3066
     if ( !retVal2 )
sl@0
  3067
     {
sl@0
  3068
        retSize = buf.st_size;
sl@0
  3069
        printf("Size before: %d", retSize);
sl@0
  3070
        retVal = ftruncate( fp, retSize/2 );
sl@0
  3071
        close(fp);
sl@0
  3072
     }
sl@0
  3073
     else
sl@0
  3074
     {
sl@0
  3075
        printf("Failed");
sl@0
  3076
     }
sl@0
  3077
     fp = open("c:	est.txt", O_RDONLY);
sl@0
  3078
     if((fp != -1) && (!retVal))
sl@0
  3079
     {
sl@0
  3080
        retVal2 = fstat( fp, &buf; );
sl@0
  3081
        if ( !retVal2 )
sl@0
  3082
        {
sl@0
  3083
          retSize2 = buf.st_size;
sl@0
  3084
          if( retSize2 == (retSize/2 ) )
sl@0
  3085
          {
sl@0
  3086
            printf("Size after: %d", retSize2);
sl@0
  3087
            printf("Ftruncate Passed");
sl@0
  3088
          }
sl@0
  3089
          else
sl@0
  3090
          {
sl@0
  3091
            printf("Failed");
sl@0
  3092
          }
sl@0
  3093
     }
sl@0
  3094
     else
sl@0
  3095
     {
sl@0
  3096
       printf("Failed");
sl@0
  3097
     }
sl@0
  3098
  }
sl@0
  3099
}
sl@0
  3100
sl@0
  3101
Output
sl@0
  3102
Size before: 100
sl@0
  3103
Size after: 50
sl@0
  3104
Ftruncate Passed
sl@0
  3105
sl@0
  3106
@endcode
sl@0
  3107
@see open()
sl@0
  3108
sl@0
  3109
sl@0
  3110
Bugs:
sl@0
  3111
sl@0
  3112
 These calls should be generalized to allow ranges
sl@0
  3113
of bytes in a file to be discarded. Use of truncate to extend a file is not portable. 
sl@0
  3114
 
sl@0
  3115
sl@0
  3116
@publishedAll
sl@0
  3117
@externallyDefinedApi
sl@0
  3118
*/
sl@0
  3119
sl@0
  3120
/** @fn int setecho(int fd, uint8_t echoval)
sl@0
  3121
@param fd
sl@0
  3122
@param echoval
sl@0
  3123
sl@0
  3124
Turns On/Off the echo for the input characters.
sl@0
  3125
If echoval is 0, the echo is turned off and nothing gets echoed on the console.
sl@0
  3126
If echoval is 1, the echo is turned on.
sl@0
  3127
If echoval is anything else, the echo is turned off and the given printable character
sl@0
  3128
will be echoed instead the actual input character.
sl@0
  3129
sl@0
  3130
Notes:
sl@0
  3131
The given fd should be that of a console.
sl@0
  3132
If the stdio redirection server is used to redirect the stdin/stdout of a process and
sl@0
  3133
if the given fd maps to one of those, then the stdin will only be affected by this call.
sl@0
  3134
Write operations on this fd will not be affected.
sl@0
  3135
The earlier behavior is retained if setecho() fails.
sl@0
  3136
sl@0
  3137
@return Upon successfull completion it returns 0, otherwise -1, setting the errno.
sl@0
  3138
sl@0
  3139
@publishedAll
sl@0
  3140
@externallyDefinedApi
sl@0
  3141
*/
sl@0
  3142
sl@0
  3143
/** @def va_list
sl@0
  3144
sl@0
  3145
The type va_list is defined for variables used to traverse the list.
sl@0
  3146
sl@0
  3147
@publishedAll
sl@0
  3148
@externallyDefinedApi
sl@0
  3149
*/
sl@0
  3150
sl@0
  3151
/** @def vfscanf
sl@0
  3152
sl@0
  3153
To be used for vfscanf(..)
sl@0
  3154
sl@0
  3155
@publishedAll
sl@0
  3156
@externallyDefinedApi
sl@0
  3157
*/
sl@0
  3158
sl@0
  3159
/** @def __SNBF	
sl@0
  3160
sl@0
  3161
unbuffered 
sl@0
  3162
sl@0
  3163
@publishedAll
sl@0
  3164
@externallyDefinedApi
sl@0
  3165
*/
sl@0
  3166
sl@0
  3167
/** @def __SRD	
sl@0
  3168
sl@0
  3169
OK to read
sl@0
  3170
sl@0
  3171
@publishedAll
sl@0
  3172
@externallyDefinedApi
sl@0
  3173
*/
sl@0
  3174
sl@0
  3175
/** @def __SLBF	
sl@0
  3176
sl@0
  3177
line buffered
sl@0
  3178
sl@0
  3179
@publishedAll
sl@0
  3180
@externallyDefinedApi
sl@0
  3181
*/
sl@0
  3182
sl@0
  3183
/** @def __SWR	
sl@0
  3184
sl@0
  3185
OK to write
sl@0
  3186
sl@0
  3187
@publishedAll
sl@0
  3188
@externallyDefinedApi
sl@0
  3189
*/
sl@0
  3190
sl@0
  3191
/** @def __SRW	
sl@0
  3192
sl@0
  3193
open for reading & writing
sl@0
  3194
sl@0
  3195
@publishedAll
sl@0
  3196
@externallyDefinedApi
sl@0
  3197
*/
sl@0
  3198
sl@0
  3199
/** @def __SEOF	
sl@0
  3200
sl@0
  3201
found EOF
sl@0
  3202
sl@0
  3203
@publishedAll
sl@0
  3204
@externallyDefinedApi
sl@0
  3205
*/
sl@0
  3206
sl@0
  3207
/** @def __SERR	
sl@0
  3208
sl@0
  3209
found error
sl@0
  3210
sl@0
  3211
@publishedAll
sl@0
  3212
@externallyDefinedApi
sl@0
  3213
*/
sl@0
  3214
sl@0
  3215
/** @def __SMBF	
sl@0
  3216
sl@0
  3217
_buf is from malloc
sl@0
  3218
sl@0
  3219
@publishedAll
sl@0
  3220
@externallyDefinedApi
sl@0
  3221
*/
sl@0
  3222
sl@0
  3223
/** @def __SAPP	
sl@0
  3224
sl@0
  3225
fdopen()ed in append mode
sl@0
  3226
sl@0
  3227
@publishedAll
sl@0
  3228
@externallyDefinedApi
sl@0
  3229
*/
sl@0
  3230
sl@0
  3231
/** @def __SSTR	
sl@0
  3232
sl@0
  3233
this is an sprintf or snprintf string 
sl@0
  3234
sl@0
  3235
@publishedAll
sl@0
  3236
@externallyDefinedApi
sl@0
  3237
*/
sl@0
  3238
sl@0
  3239
/** @def __SOPT	
sl@0
  3240
sl@0
  3241
do fseek() optimization
sl@0
  3242
sl@0
  3243
@publishedAll
sl@0
  3244
@externallyDefinedApi
sl@0
  3245
*/
sl@0
  3246
sl@0
  3247
/** @def __SNPT	
sl@0
  3248
sl@0
  3249
do not do fseek() optimization 
sl@0
  3250
sl@0
  3251
@publishedAll
sl@0
  3252
@externallyDefinedApi
sl@0
  3253
*/
sl@0
  3254
sl@0
  3255
/** @def __SOFF	
sl@0
  3256
sl@0
  3257
set iff _offset is in fact correct
sl@0
  3258
sl@0
  3259
@publishedAll
sl@0
  3260
@externallyDefinedApi
sl@0
  3261
*/
sl@0
  3262
sl@0
  3263
/** @def __SMOD	
sl@0
  3264
sl@0
  3265
true; fgetln modified _p text
sl@0
  3266
sl@0
  3267
@publishedAll
sl@0
  3268
@externallyDefinedApi
sl@0
  3269
*/
sl@0
  3270
sl@0
  3271
/** @def __SALC	
sl@0
  3272
sl@0
  3273
allocate string space dynamically
sl@0
  3274
sl@0
  3275
@publishedAll
sl@0
  3276
@externallyDefinedApi
sl@0
  3277
*/
sl@0
  3278
sl@0
  3279
/** @def __SIGN	
sl@0
  3280
sl@0
  3281
ignore this file in _fwalk
sl@0
  3282
sl@0
  3283
@publishedAll
sl@0
  3284
@externallyDefinedApi
sl@0
  3285
*/
sl@0
  3286
sl@0
  3287
/** @def _IOFBF	
sl@0
  3288
sl@0
  3289
setvbuf should set fully buffered
sl@0
  3290
sl@0
  3291
@publishedAll
sl@0
  3292
@externallyDefinedApi
sl@0
  3293
*/
sl@0
  3294
sl@0
  3295
/** @def _IOLBF	
sl@0
  3296
sl@0
  3297
setvbuf should set line buffered 
sl@0
  3298
sl@0
  3299
@publishedAll
sl@0
  3300
@externallyDefinedApi
sl@0
  3301
*/
sl@0
  3302
sl@0
  3303
/** @def _IONBF	
sl@0
  3304
sl@0
  3305
setvbuf should set unbuffered 
sl@0
  3306
sl@0
  3307
@publishedAll
sl@0
  3308
@externallyDefinedApi
sl@0
  3309
*/
sl@0
  3310
sl@0
  3311
/** @def BUFSIZ	
sl@0
  3312
sl@0
  3313
size of buffer used by setbuf 
sl@0
  3314
sl@0
  3315
@publishedAll
sl@0
  3316
@externallyDefinedApi
sl@0
  3317
*/
sl@0
  3318
sl@0
  3319
/** @def EOF	
sl@0
  3320
sl@0
  3321
End of file
sl@0
  3322
sl@0
  3323
@publishedAll
sl@0
  3324
@externallyDefinedApi
sl@0
  3325
*/
sl@0
  3326
sl@0
  3327
/** @def FOPEN_MAX
sl@0
  3328
sl@0
  3329
must be less than OPEN_MAX
sl@0
  3330
sl@0
  3331
@publishedAll
sl@0
  3332
@externallyDefinedApi
sl@0
  3333
*/
sl@0
  3334
sl@0
  3335
/** @def FILENAME_MAX
sl@0
  3336
sl@0
  3337
must be less than PATH_MAX 
sl@0
  3338
sl@0
  3339
@publishedAll
sl@0
  3340
@externallyDefinedApi
sl@0
  3341
*/
sl@0
  3342
sl@0
  3343
/** @def SEEK_END
sl@0
  3344
sl@0
  3345
set file offset to EOF plus offset
sl@0
  3346
sl@0
  3347
@publishedAll
sl@0
  3348
@externallyDefinedApi
sl@0
  3349
*/
sl@0
  3350
sl@0
  3351
/** @def SEEK_CUR
sl@0
  3352
sl@0
  3353
set file offset to current plus offset
sl@0
  3354
sl@0
  3355
@publishedAll
sl@0
  3356
@externallyDefinedApi
sl@0
  3357
*/
sl@0
  3358
sl@0
  3359
/** @def SEEK_SET
sl@0
  3360
sl@0
  3361
set file offset to offset
sl@0
  3362
sl@0
  3363
@publishedAll
sl@0
  3364
@externallyDefinedApi
sl@0
  3365
*/
sl@0
  3366
sl@0
  3367
/** @def TMP_MAX
sl@0
  3368
sl@0
  3369
temporary max value
sl@0
  3370
sl@0
  3371
@publishedAll
sl@0
  3372
@externallyDefinedApi
sl@0
  3373
*/
sl@0
  3374
sl@0
  3375
/** @def L_tmpnam
sl@0
  3376
sl@0
  3377
must be == PATH_MAX
sl@0
  3378
sl@0
  3379
@publishedAll
sl@0
  3380
@externallyDefinedApi
sl@0
  3381
*/
sl@0
  3382
sl@0
  3383
/** @def stdin
sl@0
  3384
sl@0
  3385
standard input variable
sl@0
  3386
sl@0
  3387
@publishedAll
sl@0
  3388
@externallyDefinedApi
sl@0
  3389
*/
sl@0
  3390
sl@0
  3391
/** @def stdout
sl@0
  3392
sl@0
  3393
standard output variable
sl@0
  3394
sl@0
  3395
@publishedAll
sl@0
  3396
@externallyDefinedApi
sl@0
  3397
*/
sl@0
  3398
sl@0
  3399
/** @def stderr
sl@0
  3400
sl@0
  3401
standard error variable
sl@0
  3402
sl@0
  3403
@publishedAll
sl@0
  3404
@externallyDefinedApi
sl@0
  3405
*/
sl@0
  3406
sl@0
  3407
/** @def L_cuserid
sl@0
  3408
sl@0
  3409
size for cuserid(3)
sl@0
  3410
sl@0
  3411
@publishedAll
sl@0
  3412
@externallyDefinedApi
sl@0
  3413
*/
sl@0
  3414
sl@0
  3415
/** @def L_ctermid
sl@0
  3416
sl@0
  3417
size for ctermid(3)
sl@0
  3418
sl@0
  3419
@publishedAll
sl@0
  3420
@externallyDefinedApi
sl@0
  3421
*/
sl@0
  3422
sl@0
  3423
sl@0
  3424
/** @def __isthreaded
sl@0
  3425
sl@0
  3426
defined to isthreaded()
sl@0
  3427
sl@0
  3428
@publishedAll
sl@0
  3429
@externallyDefinedApi
sl@0
  3430
*/
sl@0
  3431
sl@0
  3432
/** @def feof(p)
sl@0
  3433
sl@0
  3434
Functions defined in ANSI C standard.
sl@0
  3435
sl@0
  3436
@publishedAll
sl@0
  3437
@externallyDefinedApi
sl@0
  3438
*/
sl@0
  3439
sl@0
  3440
/** @def ferror(p)
sl@0
  3441
sl@0
  3442
Functions defined in ANSI C standard.
sl@0
  3443
sl@0
  3444
@publishedAll
sl@0
  3445
@externallyDefinedApi
sl@0
  3446
*/
sl@0
  3447
sl@0
  3448
/** @def clearerr(p)
sl@0
  3449
sl@0
  3450
Functions defined in ANSI C standard.
sl@0
  3451
sl@0
  3452
@publishedAll
sl@0
  3453
@externallyDefinedApi
sl@0
  3454
*/
sl@0
  3455
sl@0
  3456
/** @def fileno(p)
sl@0
  3457
sl@0
  3458
Functions defined in ANSI C standard.
sl@0
  3459
sl@0
  3460
@publishedAll
sl@0
  3461
@externallyDefinedApi
sl@0
  3462
*/
sl@0
  3463
sl@0
  3464
/** @def getc(fp)
sl@0
  3465
sl@0
  3466
Functions defined in ANSI C standard.
sl@0
  3467
sl@0
  3468
@publishedAll
sl@0
  3469
@externallyDefinedApi
sl@0
  3470
*/
sl@0
  3471
sl@0
  3472
/** @def getchar()
sl@0
  3473
sl@0
  3474
Defined to getc(stdin)
sl@0
  3475
sl@0
  3476
@publishedAll
sl@0
  3477
@externallyDefinedApi
sl@0
  3478
*/
sl@0
  3479
sl@0
  3480
/** @def putchar(x)
sl@0
  3481
sl@0
  3482
defined to putc(x,stdout)
sl@0
  3483
sl@0
  3484
@publishedAll
sl@0
  3485
@externallyDefinedApi
sl@0
  3486
*/
sl@0
  3487
sl@0
  3488
/** @struct __sbuf
sl@0
  3489
sl@0
  3490
stdio buffers 
sl@0
  3491
sl@0
  3492
@publishedAll
sl@0
  3493
@externallyDefinedApi
sl@0
  3494
*/
sl@0
  3495
sl@0
  3496
/** @var __sbuf::_base
sl@0
  3497
Pointer to the buffer
sl@0
  3498
*/
sl@0
  3499
sl@0
  3500
/** @var __sbuf::_size
sl@0
  3501
size of the buffer
sl@0
  3502
*/
sl@0
  3503
sl@0
  3504
/** @struct __sFILE
sl@0
  3505
sl@0
  3506
stdio state file variables.
sl@0
  3507
sl@0
  3508
@publishedAll
sl@0
  3509
@externallyDefinedApi
sl@0
  3510
*/
sl@0
  3511
sl@0
  3512
/** @typedef  typedef __off_t fpos_t
sl@0
  3513
sl@0
  3514
Represents file position
sl@0
  3515
sl@0
  3516
@publishedAll
sl@0
  3517
@externallyDefinedApi
sl@0
  3518
*/
sl@0
  3519
sl@0
  3520
/** @typedef  typedef __off_t fpos64_t
sl@0
  3521
sl@0
  3522
Represents large file position
sl@0
  3523
sl@0
  3524
@publishedAll
sl@0
  3525
@externallyDefinedApi
sl@0
  3526
*/
sl@0
  3527
sl@0
  3528
/** @typedef  typedef	__size_t	size_t
sl@0
  3529
sl@0
  3530
A type to define sizes of strings and memory blocks.
sl@0
  3531
sl@0
  3532
@publishedAll
sl@0
  3533
@externallyDefinedApi
sl@0
  3534
*/
sl@0
  3535
sl@0
  3536
/** @typedef  typedef	__va_list	va_list
sl@0
  3537
sl@0
  3538
A void pointer which can be interpreted as an argument list.
sl@0
  3539
sl@0
  3540
@publishedAll
sl@0
  3541
@externallyDefinedApi
sl@0
  3542
*/
sl@0
  3543
sl@0
  3544
sl@0
  3545
/** @fn tmpdirname(void)
sl@0
  3546
sl@0
  3547
@return Upon successful completion tmpdirname() will return the path of the private directory of that process.
sl@0
  3548
sl@0
  3549
Note:String that the function will return is not to be modified.
sl@0
  3550
sl@0
  3551
Examples:
sl@0
  3552
sl@0
  3553
@code
sl@0
  3554
sl@0
  3555
/* Illustrates how to use tmpdirname() API */
sl@0
  3556
#include <stdio.h>
sl@0
  3557
int main()
sl@0
  3558
	{
sl@0
  3559
	char *ptr;
sl@0
  3560
	ptr=tmpdirname();
sl@0
  3561
	printf("%s\n",ptr);
sl@0
  3562
	return 0;	
sl@0
  3563
	}
sl@0
  3564
@endcode
sl@0
  3565
sl@0
  3566
@publishedAll
sl@0
  3567
@released
sl@0
  3568
*/
sl@0
  3569
sl@0
  3570
/** @fn  set_fmode(char mode)
sl@0
  3571
@param mode
sl@0
  3572
@return  set_fmode() returns 0 on success, otherwise returns -1 with an errno set to EINVAL. 
sl@0
  3573
sl@0
  3574
set_fmode(), get_fmode() are used to provide text-mode support.
sl@0
  3575
sl@0
  3576
Using set_fmode(), User can set file opening mode explicitly to either text or binary i.e. it can take only 't' or 'b' as parameter.
sl@0
  3577
sl@0
  3578
Notes: 1>. User is supposed to use this before opening a file or at the start of the application. The mode that is set using set_fmode()
sl@0
  3579
      is fixed till the file is closed or till the application terminates.  In case the user wants to change the mode once the file
sl@0
  3580
      has been opened and before it is closed, the buffer needs to be flushed explicitly.
sl@0
  3581
      
sl@0
  3582
      2>. If the user mixes the two file modes, there might be unexpected behaviour.
sl@0
  3583
	  For example, a file is opened in text mode, written with 20 bytes and closed. 
sl@0
  3584
	  Again the file is opened in binary mode and 20 bytes is read. If the 20 bytes written earlier had '\n's among them, 
sl@0
  3585
	  the read data will not be complete.
sl@0
  3586
	   
sl@0
  3587
Examples:
sl@0
  3588
@code
sl@0
  3589
/*
sl@0
  3590
 * Detailed description : To set the mode of a file to either text/binary explicitly
sl@0
  3591
 */
sl@0
  3592
#include <stdio.h>
sl@0
  3593
int main() 
sl@0
  3594
{
sl@0
  3595
  int ret;
sl@0
  3596
  ret = set_fmode('t');	
sl@0
  3597
  if(ret != 0 ) 
sl@0
  3598
  {
sl@0
  3599
     printf("Failed to set text mode\n") ;
sl@0
  3600
     return -1 ;
sl@0
  3601
  }
sl@0
  3602
  printf("Successfully able to set text mode\n") ;
sl@0
  3603
  if (get_fmode() != 't')
sl@0
  3604
  {
sl@0
  3605
     printf("Failed to Retrieve file-mode\n") ;
sl@0
  3606
     return -1 ;      
sl@0
  3607
  }	
sl@0
  3608
  printf("Successfully able to Retrieve file-mode\n") ;
sl@0
  3609
  getchar();
sl@0
  3610
  return 0 ;
sl@0
  3611
}
sl@0
  3612
sl@0
  3613
@endcode
sl@0
  3614
sl@0
  3615
@see get_fmode()
sl@0
  3616
@see fopen()
sl@0
  3617
@see fclose()
sl@0
  3618
@see setvbuf()
sl@0
  3619
@see ftell()
sl@0
  3620
@see fseek()
sl@0
  3621
@see fread()
sl@0
  3622
@see fwrite()
sl@0
  3623
@see fputs()
sl@0
  3624
@see fputc()
sl@0
  3625
@see fgets()
sl@0
  3626
@see fgetc()
sl@0
  3627
@see fprintf()
sl@0
  3628
@see fscanf()
sl@0
  3629
sl@0
  3630
@publishedAll
sl@0
  3631
@externallyDefinedApi
sl@0
  3632
*/
sl@0
  3633
sl@0
  3634
/** @fn  get_fmode( )
sl@0
  3635
@return   get_fmode() returns the current file open mode as either 't' or 'b'. 't' is returned if text-mode is set 
sl@0
  3636
		  explicitly using set_fmode(), otherwise 'b' binary-mode is returned which is default in symbian.
sl@0
  3637
		   
sl@0
  3638
Examples:
sl@0
  3639
@code
sl@0
  3640
/*
sl@0
  3641
 * Detailed description : To Retrieve the current mode of a file
sl@0
  3642
 */
sl@0
  3643
#include <stdio.h>
sl@0
  3644
int main() 
sl@0
  3645
{
sl@0
  3646
  int ret;
sl@0
  3647
  ret = set_fmode('t');	
sl@0
  3648
  if(ret != 0 ) 
sl@0
  3649
  {
sl@0
  3650
     printf("Failed to set text mode\n") ;
sl@0
  3651
     return -1 ;
sl@0
  3652
  }
sl@0
  3653
  printf("Successfully able to set text mode\n") ;
sl@0
  3654
  if (get_fmode() != 't')
sl@0
  3655
  {
sl@0
  3656
     printf("Failed to Retrieve file-mode\n") ;
sl@0
  3657
     return -1 ;      
sl@0
  3658
  }	
sl@0
  3659
  printf("Successfully able to Retrieve file-mode\n") ;
sl@0
  3660
  getchar();
sl@0
  3661
  return 0 ;
sl@0
  3662
}
sl@0
  3663
sl@0
  3664
@endcode
sl@0
  3665
sl@0
  3666
Examples:
sl@0
  3667
@code
sl@0
  3668
/*
sl@0
  3669
 * Detailed description : General example to illustrate set_fmode(), get_fmode()
sl@0
  3670
 */
sl@0
  3671
#include <stdio.h>
sl@0
  3672
int main()
sl@0
  3673
{
sl@0
  3674
    char *data = "helloworld\nfine";
sl@0
  3675
    char *p = NULL;
sl@0
  3676
    int ret = 0;
sl@0
  3677
    FILE *fw = NULL, *fr = NULL;
sl@0
  3678
    
sl@0
  3679
    ret = set_fmode('t');                   			// To set text-mode using set_fmode()
sl@0
  3680
	if(ret != 0 ) 
sl@0
  3681
		{
sl@0
  3682
		printf("Failed to set text mode") ;
sl@0
  3683
		return -1 ;
sl@0
  3684
		}
sl@0
  3685
	if (get_fmode() != 't')
sl@0
  3686
		{
sl@0
  3687
		printf("Failed to Retrieve file-mode") ;
sl@0
  3688
		return -1 ;      
sl@0
  3689
		}	
sl@0
  3690
sl@0
  3691
    fw = fopen("c:\\temp_tc.txt", "w");
sl@0
  3692
    int count = fwrite(data, 1, strlen(data), fw);
sl@0
  3693
	if(count != strlen(data))
sl@0
  3694
		{
sl@0
  3695
		printf("fwrite() failed\n");
sl@0
  3696
		goto end;
sl@0
  3697
		}
sl@0
  3698
    fclose(fw);
sl@0
  3699
    fw = fopen("c:\\temp_tc_out.txt", "w");
sl@0
  3700
    fr = fopen("c:\\temp_tc.txt", "r");
sl@0
  3701
    p = (char *)malloc(count+1);                        // extra one is for holding '\0'
sl@0
  3702
	if( !p )
sl@0
  3703
		{
sl@0
  3704
		printf("malloc() failed\n");
sl@0
  3705
		goto end;
sl@0
  3706
		}
sl@0
  3707
    char *retn = fgets(p, count, fr);
sl@0
  3708
    //ret = fread(p, 1, 11, fr);
sl@0
  3709
    if(strlen(p) != 11)
sl@0
  3710
        {
sl@0
  3711
        printf("1st read failed\n");
sl@0
  3712
        goto end;
sl@0
  3713
        }
sl@0
  3714
    int pos = ftell(fr);                              	// 12 -> offset
sl@0
  3715
    printf("pos After 1st read: %d\n", pos);
sl@0
  3716
    fseek(fr,pos,SEEK_SET);
sl@0
  3717
    ret = fread(p+11,1,4,fr);
sl@0
  3718
    if( ret != 4)
sl@0
  3719
        {
sl@0
  3720
        printf("Failed to read using fread()\n");
sl@0
  3721
        goto end;
sl@0
  3722
        }
sl@0
  3723
    p[count] = '\0';
sl@0
  3724
    pos = ftell(fr);                            		// 16 -> offset
sl@0
  3725
    printf("pos After 2nd read: %d\n", pos);
sl@0
  3726
    getchar();
sl@0
  3727
    count = fwrite(p, 1, strlen(p), fw);
sl@0
  3728
    if(count != strlen(p))
sl@0
  3729
        {
sl@0
  3730
        printf(" Failed to write onto another file\n");
sl@0
  3731
        getchar();
sl@0
  3732
        }
sl@0
  3733
    else
sl@0
  3734
        {
sl@0
  3735
        printf("Passed to write onto another file\n");
sl@0
  3736
        getchar();
sl@0
  3737
        }
sl@0
  3738
	end: 
sl@0
  3739
	if(p)
sl@0
  3740
		{
sl@0
  3741
		free(p);
sl@0
  3742
		p = NULL;
sl@0
  3743
		}
sl@0
  3744
	if(fr)
sl@0
  3745
		fclose(fr);
sl@0
  3746
	if(fw)
sl@0
  3747
		fclose(fw);
sl@0
  3748
    return 0;                                                   
sl@0
  3749
} 
sl@0
  3750
@endcode
sl@0
  3751
sl@0
  3752
@code
sl@0
  3753
sl@0
  3754
Output:
sl@0
  3755
pos After 1st read: 12
sl@0
  3756
pos After 2nd read: 20
sl@0
  3757
Passed to write onto another file
sl@0
  3758
sl@0
  3759
@endcode
sl@0
  3760
sl@0
  3761
@see set_fmode()
sl@0
  3762
sl@0
  3763
@publishedAll
sl@0
  3764
@externallyDefinedApi
sl@0
  3765
*/