sl@0: /** @file ../include/stdio.h sl@0: @internalComponent sl@0: */ sl@0: sl@0: /** @fn clearerr(FILE *fp) sl@0: @param fp sl@0: sl@0: Note: This description also covers the following functions - sl@0: feof() ferror() fileno() sl@0: sl@0: The function clearerr clears the end-of-file and error indicators for the stream pointed sl@0: to by fp. sl@0: sl@0: 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: The end-of-file indicator can only be cleared by the function clearerr. sl@0: sl@0: The function ferror tests the error indicator for the stream pointed to by fp, returning non-zero if it is set. sl@0: The error indicator can only be reset by the clearerr function. sl@0: sl@0: The function fileno examines the argument fp and returns its integer descriptor. sl@0: sl@0: Examples: sl@0: @code sl@0: /* this program shows finding error set using ferror sl@0: * and clearing it using clearerr functions */ sl@0: #include sl@0: int main() sl@0: { sl@0: char a; sl@0: if( set_fmode('t') != 0 ) // setting text-mode as default file opening mode throughout the appln. sl@0: { sl@0: printf("Failed to set text-mode\n"); sl@0: return -1; sl@0: } sl@0: FILE* fp = fopen("c:\input.txt", "w"); sl@0: fprintf(fp, "%s", "abcdefghijklmn"); sl@0: fprintf(fp, "%c", ''); sl@0: fprintf(fp, "%s", "fdsfdsafsdabcdefghijklmn"); sl@0: fclose(fp); sl@0: fp=fopen("c:\input.txt","r"); sl@0: if (fp == NULL) sl@0: { sl@0: printf("fopen failed"); sl@0: return -1; sl@0: } sl@0: else sl@0: { sl@0: fwrite(&a;, sizeof(char), 1, fp); sl@0: if (ferror (fp)) sl@0: printf("error set in file stream"); sl@0: else sl@0: { sl@0: fclose(fp); sl@0: return -1; sl@0: } sl@0: clearerr(fp); sl@0: if (!ferror(fp)) sl@0: printf("error cleared in file stream"); sl@0: else printf("error still unexpected set in file stream"); sl@0: fclose (fp); sl@0: } sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: error set in file stream sl@0: error cleared in file stream sl@0: sl@0: @endcode sl@0: @see open() sl@0: @see flockfile() sl@0: @see set_fmode() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fclose(FILE *fp) sl@0: @param fp sl@0: @return Upon successful completion 0 is returned. sl@0: Otherwise, EOF is returned and the global variable errno is set to indicate the error. sl@0: In either case no further access to the stream is possible. sl@0: sl@0: The fclose function dissociates the named stream from its underlying file or set of functions. If the stream was sl@0: being used for output any buffered data is written first using fflush . sl@0: sl@0: Examples: sl@0: @code sl@0: /* this program shows opening and closing of a file using fclose api */ sl@0: #include sl@0: int main() sl@0: { sl@0: FILE *fp; sl@0: if( set_fmode('t') != 0 ) // setting text-mode as default file opening mode throughout the appln. sl@0: { sl@0: printf("Failed to set text-mode\n"); sl@0: return -1; sl@0: } sl@0: fp = fopen("c:\input.txt", "w+"); sl@0: if(fp == NULL) sl@0: { sl@0: printf("file opening failed"); sl@0: return -1; sl@0: } sl@0: sl@0: printf("file opened successfully: Perform file operations now"); sl@0: sl@0: if(!fclose(fp)) sl@0: { sl@0: printf("file closed successfully"); sl@0: return 0; sl@0: } sl@0: else sl@0: { sl@0: printf("file closing failed"); sl@0: return -1; sl@0: } sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: file opened successfully: Perform file operations now sl@0: file closed successfully sl@0: sl@0: @endcode sl@0: sl@0: Notes: sl@0: sl@0: The fclose function sl@0: does not handle NULL arguments; they will result in a segmentation sl@0: violation. sl@0: This is intentional - it makes it easier to make sure programs written sl@0: under are bug free. This behaviour is an implementation detail and programs should not sl@0: rely upon it. sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn feof(FILE *fp) sl@0: @param fp sl@0: sl@0: Refer to clearerr() for the documentation sl@0: @see open() sl@0: @see flockfile() sl@0: @see set_fmode() sl@0: sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn ferror(FILE *fp) sl@0: @param fp sl@0: sl@0: Refer to clearerr() for the documentation sl@0: @see open() sl@0: @see flockfile() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fseeko(FILE *stream, off_t offset, int whence) sl@0: @param stream sl@0: @param offset sl@0: @param whence sl@0: sl@0: For full documentation see: http://opengroup.org/onlinepubs/007908775/xsh/fseek.html sl@0: sl@0: @see fseek() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fseeko64(FILE *stream, off64_t offset, int whence) sl@0: @param stream sl@0: @param offset sl@0: @param whence sl@0: sl@0: For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0 sl@0: sl@0: @see fseeko() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn ftello(FILE *stream) sl@0: @param stream sl@0: sl@0: For full documentation see: http://opengroup.org/onlinepubs/007908775/xsh/fseek.html sl@0: sl@0: @see ftell() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn ftello64(FILE *stream) sl@0: @param stream sl@0: sl@0: For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0 sl@0: sl@0: @see ftello() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fflush(FILE *fp) sl@0: @param fp sl@0: sl@0: @return Upon successful completion 0 is returned. sl@0: Otherwise, EOF is returned and the global variable errno is set to indicate the error. sl@0: sl@0: 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: The open status of the stream is unaffected. sl@0: sl@0: If the fp argument is NULL, fflush flushes all open output streams. sl@0: sl@0: Examples: sl@0: @code sl@0: /* this program shows flushing user space buffered data using fflush */ sl@0: #include sl@0: int main() sl@0: { sl@0: FILE *fp = NULL; sl@0: int retval = 0; sl@0: char name[20] = "c:\flush1.txt"; sl@0: if( set_fmode('t') != 0 ) // setting text-mode as default file opening mode throughout the appln. sl@0: { sl@0: printf("Failed to set text-mode\n"); sl@0: return -1; sl@0: } sl@0: fp = fopen(name, "w+"); sl@0: if(fp == NULL) sl@0: { sl@0: printf("Error : File open"); sl@0: return -1; sl@0: } sl@0: setvbuf(fp, NULL, _IOFBF, 100); // set to full buffering with NULL buffer sl@0: fprintf(fp, "we are trying to buffer 100 characters at once with NULL buffer."); sl@0: sl@0: retval = fflush(fp); sl@0: if (retval) sl@0: { sl@0: printf("fflush failed"); sl@0: fclose(fp); sl@0: unlink(name); sl@0: return -1; sl@0: } sl@0: else printf("Buffer successfully flushed"); sl@0: fclose(fp); sl@0: unlink(name); sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: we are trying to buffer 100 characters at once with NULL buffer. sl@0: Buffer successfully flushed sl@0: sl@0: @endcode sl@0: @see write() sl@0: @see fclose() sl@0: @see fopen() sl@0: @see setbuf() sl@0: @see set_fmode() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fgetc(FILE *fp) sl@0: @param fp sl@0: sl@0: Note: This description also covers the following functions - sl@0: getc() getc_unlocked() getchar() getchar_unlocked() getw() sl@0: sl@0: @return If successful, these routines return the next requested object sl@0: from the stream. Character values are returned as an unsigned char converted to an int. sl@0: If the stream is at end-of-file or a read error occurs, sl@0: the routines return EOF. The routines and ferror must be used to distinguish between end-of-file and error. sl@0: If an error occurs, the global variable errno is set to indicate the error. sl@0: The end-of-file condition is remembered, even on a terminal, and all sl@0: subsequent attempts to read will return EOF until the condition is cleared with sl@0: sl@0: The fgetc function sl@0: 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: sl@0: The getc function sl@0: acts essentially identically to fgetc, but is a macro that expands in-line. sl@0: sl@0: The getchar function sl@0: is equivalent to getc (stdin.); sl@0: sl@0: The getw function sl@0: obtains the next int sl@0: (if present) sl@0: from the stream pointed at by stream. sl@0: sl@0: The getc_unlocked and getchar_unlocked functions are equivalent to getc and getchar respectively, sl@0: except that the caller is responsible for locking the stream sl@0: with flockfile before calling them. sl@0: These functions may be used to avoid the overhead of locking the stream sl@0: for each character, and to avoid input being dispersed among multiple sl@0: threads reading from the same stream. sl@0: sl@0: Examples: sl@0: @code sl@0: /* this program shows reading from file using getc */ sl@0: /* consider input.txt has the following content: */ sl@0: /* hi */ sl@0: #include sl@0: int main(void) sl@0: { sl@0: int retval; sl@0: FILE *fp = NULL; sl@0: if( set_fmode('t') != 0 ) // setting text-mode as default file opening mode throughout the appln. sl@0: { sl@0: printf("Failed to set text-mode\n"); sl@0: return -1; sl@0: } sl@0: fp = fopen("c:\input.txt", "w"); sl@0: fprintf(fp, "%s", "abcdefghijklmn"); sl@0: fprintf(fp, "%c", '\n'); sl@0: fprintf(fp, "%s", "fdsfdsafsdabcdefghijklmn"); sl@0: fclose(fp); sl@0: fp = fopen("C:\input.txt","r"); sl@0: if(fp == NULL) sl@0: { sl@0: printf("fopen failed"); sl@0: return -1; sl@0: } sl@0: while((int)(retval = getc(fp) )!= EOF) sl@0: { sl@0: printf("%c", retval); sl@0: } sl@0: fclose(fp); sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: hi sl@0: sl@0: @endcode sl@0: @see ferror() sl@0: @see flockfile() sl@0: @see fopen() sl@0: @see fread() sl@0: @see getwc() sl@0: @see putc() sl@0: @see ungetc() sl@0: @see set_fmode() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fgetpos(FILE * fp, fpos_t * pos) sl@0: @param fp sl@0: @param pos sl@0: Refer to fseek() for the documentation sl@0: @see lseek() sl@0: @see ungetc() sl@0: @see ungetwc() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fgetpos64(FILE * fp, fpos64_t * pos) sl@0: @param fp sl@0: @param pos sl@0: sl@0: For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0 sl@0: sl@0: sl@0: @see fgetpos() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fgets(char *buf, int n, FILE *fp) sl@0: @param buf sl@0: @param n sl@0: @param fp sl@0: sl@0: Note: This description also covers the following functions - sl@0: gets() sl@0: sl@0: @return Upon successful completion fgets and gets return a pointer to the string. If end-of-file occurs before any sl@0: characters are read they return NULL and the buffer contents remain unchanged. If an error occurs they sl@0: 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: callers must use feof and ferror to determine which occurred. sl@0: sl@0: The fgets function reads at most one less than the number of characters sl@0: 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: 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: sl@0: The gets function is equivalent to fgets with an infinite size and a stream of stdin, sl@0: except that the newline character (if any) is not stored in the string. sl@0: It is the caller's responsibility to ensure that the input line,if any, is sufficiently short to fit in the string. sl@0: sl@0: Examples: sl@0: @code sl@0: /* this program shows reading characters from a file using fgets */ sl@0: /* consider input.txt has the following content: */ sl@0: /* abcdefghijklmn */ sl@0: /* fdsfdsafsdabcdefghijklmn */ sl@0: #include sl@0: int main(void) sl@0: { sl@0: char buf[20]; sl@0: FILE *fp = NULL; sl@0: if( set_fmode('t') != 0 ) // setting text-mode as default file opening mode throughout the appln. sl@0: { sl@0: printf("Failed to set text-mode\n"); sl@0: return -1; sl@0: } sl@0: fp = fopen("c:\input.txt", "w"); sl@0: fprintf(fp, "%s", "abcdefghijklmn"); sl@0: fprintf(fp, "%c", ""); sl@0: fprintf(fp, "%s", "fdsfdsafsdabcdefghijklmn"); sl@0: fclose(fp); sl@0: sl@0: fp = fopen("C:\input.txt","r"); sl@0: if(fp == NULL) sl@0: { sl@0: printf("fopen failed"); sl@0: return -1; sl@0: } sl@0: if(fgets(buf,18,fp) != NULL) sl@0: printf("%s", buf); sl@0: else sl@0: printf("Buffer is empty"); sl@0: sl@0: buf[0] = '\0'; sl@0: if(fgets(buf,2,fp) != NULL) sl@0: printf("%s", buf); sl@0: else sl@0: printf("Buffer is empty"); sl@0: fclose(fp); sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: abcdefghijklmn sl@0: fdsfdsafsdabcdefghijklmn sl@0: sl@0: @endcode sl@0: sl@0: Security considerations: sl@0: sl@0: The gets function cannot be used securely. sl@0: Because of its lack of bounds checking,and the inability for the calling program sl@0: to reliably determine the length of the next incoming line,the use of this function enables malicious users sl@0: to arbitrarily change a running program's functionality through a buffer overflow attack. sl@0: It is strongly suggested that the fgets function be used in all cases. sl@0: @see feof() sl@0: @see ferror() sl@0: @see fgetln() sl@0: @see set_fmode() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fopen(const char *file, const char *mode) sl@0: @param file sl@0: @param mode sl@0: sl@0: Note: This description also covers the following functions - sl@0: fdopen() freopen() sl@0: sl@0: @return Upon successful completion fopen, fdopen and freopen return a FILE pointer. sl@0: Otherwise, NULL is returned and the global variable errno is set to indicate the error. sl@0: sl@0: 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: For more details, see set_fmode(). sl@0: sl@0: The fopen function opens the file whose name is the string pointed to by file and associates a stream with it. sl@0: sl@0: The argument mode points to a string beginning with one of the following sequences (Additional characters may follow these sequences.): sl@0: @code sl@0: "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: "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: "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: "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: "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: "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: @endcode sl@0: 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: sl@0: 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: sl@0: 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: sl@0: 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: sl@0: 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: sl@0: 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: @code sl@0: * Streams originally opened with mode "r" can only be reopened with that same mode. sl@0: * Streams originally opened with mode "a" can be reopened with the same mode, or mode "w." sl@0: * Streams originally opened with mode "w" can be reopened with the same mode, or mode "a." sl@0: * Streams originally opened with mode "r+," "w+," or "a+" can be reopened with any mode. sl@0: @endcode sl@0: The primary use of the freopen function is to change the file associated with a standard text stream (stderr, stdin, or stdout). sl@0: sl@0: sl@0: sl@0: Examples: sl@0: @code sl@0: /* This program shows opening a file in default binary mode with write combination,write data and close */ sl@0: /* again open in append mode and write data */ sl@0: /* Check file c:\fopen.txt */ sl@0: #include sl@0: int main(void) sl@0: { sl@0: FILE *fp; sl@0: char name[20] = "c:\fopen1.txt"; sl@0: sl@0: if ((fp = fopen (name, "w")) == NULL) // Opens file in default binary mode sl@0: { sl@0: printf("Error creating file"); sl@0: return -1; sl@0: } sl@0: printf("Opened file"); sl@0: fprintf(fp, "helloworld\n"); sl@0: printf("Wrote to file"); sl@0: fclose (fp); sl@0: printf("Closed file"); sl@0: if ((fp = fopen (name, "a")) == NULL) sl@0: { sl@0: printf("Error opening file"); sl@0: return -1; sl@0: } sl@0: printf("Opened file for appending"); sl@0: fprintf(fp, "fine"); sl@0: fclose (fp); sl@0: printf("closed file, check output in c:\ fopen.txt file"); sl@0: unlink(name); sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: Opened file sl@0: Wrote to file sl@0: Closed file sl@0: Opened file for appending sl@0: closed file, check output in c:\fopen.txt file sl@0: sl@0: Note: fopen.txt file contains:- sl@0: helloworld\nfine sl@0: sl@0: @endcode sl@0: sl@0: sl@0: @code sl@0: /* This program shows opening a file explicitly in text-mode using set_fmode() with write combination,write data and close */ sl@0: /* again open in append mode and write data */ sl@0: /* Check file c:\fopen.txt */ sl@0: #include sl@0: int main(void) sl@0: { sl@0: FILE *fp; sl@0: char name[20] = "c:\fopen1.txt"; sl@0: if( set_fmode('t') != 0 ) sl@0: { sl@0: printf("Failed to set text-mode\n"); sl@0: return -1; sl@0: } sl@0: if(get_fmode() != 't') sl@0: { sl@0: printf(" Failed to retrieve the text-mode set using set_fmode()\n"); sl@0: return -1; sl@0: } sl@0: if ((fp = fopen (name, "w")) == NULL) // Opens file in text-mode sl@0: { sl@0: printf("Error creating file"); sl@0: return -1; sl@0: } sl@0: printf("Opened file"); sl@0: fprintf(fp, "helloworld\n"); sl@0: printf("Wrote to file"); sl@0: fclose (fp); sl@0: printf("Closed file"); sl@0: if ((fp = fopen (name, "a")) == NULL) sl@0: { sl@0: printf("Error opening file"); sl@0: return -1; sl@0: } sl@0: printf("Opened file for appending"); sl@0: fprintf(fp, "fine"); sl@0: fclose (fp); sl@0: printf("closed file, check output in c:\ fopen.txt file"); sl@0: unlink(name); sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: Opened file sl@0: Wrote to file sl@0: Closed file sl@0: Opened file for appending sl@0: closed file, check output in c:\fopen.txt file sl@0: sl@0: Note: fopen.txt file contains:- sl@0: helloworld sl@0: fine sl@0: sl@0: @endcode sl@0: sl@0: sl@0: Notes: sl@0: sl@0: -# Mode values for group and others are be ignored. sl@0: -# The execute bit and setuid on exec bit are ignored. sl@0: -# The default working directory of a process is initialized to C:\\private\\UID sl@0: (UID of the calling application) and any data written into this directory persists sl@0: between phone resets. sl@0: -# If the specified file is a symbolic link and the file it is pointing to sl@0: is invalid the symbolic link file will be automatically removed. sl@0: sl@0: Limitations: sl@0: sl@0: A file in cannot be created with write-only permission and attempting to sl@0: create one will result in a file with read-write permission. Creating a new file sl@0: with the O_CREAT flag does not alter the time stamp of its parent directory. The sl@0: newly created entry has only two time stamps: access and modification. Creation sl@0: time stamp is not supported and access time stamp is initially equal to modification sl@0: time stamp. open, fclose and fflush. sl@0: sl@0: KErrNotReady of symbian error code is mapped to ENOENT, which typically means drive sl@0: not found or filesystem not mounted on the drive. sl@0: sl@0: @see open() sl@0: @see fclose() sl@0: @see fileno() sl@0: @see fseek() sl@0: @see set_fmode() sl@0: @see get_fmode() sl@0: sl@0: sl@0: sl@0: @capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&) sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fopen64(const char *file, const char *mode) sl@0: @param file sl@0: @param mode sl@0: sl@0: sl@0: @return Upon successful completion fopen64() return a FILE pointer. sl@0: Otherwise, NULL is returned and the global variable errno is set to indicate the error. sl@0: sl@0: For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0 sl@0: sl@0: @see fopen() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fprintf(FILE *fp, const char *fmt, ...) sl@0: @param fp sl@0: @param fmt sl@0: @param ... sl@0: sl@0: Refer to printf() for the documentation sl@0: @see printf() sl@0: @see scanf() sl@0: @see setlocale() sl@0: @see wprintf() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fputc(int c, FILE *fp) sl@0: @param c sl@0: @param fp sl@0: sl@0: Note: This description also covers the following functions - sl@0: putc() putc_unlocked() putchar() putchar_unlocked() putw() sl@0: sl@0: @return The functions, fputc, putc, putchar, putc_unlocked, and putchar_unlocked return the character written. sl@0: If an error occurs, the value EOF is returned. sl@0: The putw function returns 0 on success; EOF is returned if a write error occurs, sl@0: or if an attempt is made to write to a read-only stream. sl@0: sl@0: The fputc function writes the character c (converted to an "unsigned char") sl@0: to the output stream pointed to by fp. sl@0: sl@0: The putc macro that is identically to fputc, but is a macro that expands in-line. sl@0: It may evaluate stream more than once, so arguments given to putc should not be expressions with potential side effects. sl@0: sl@0: The putchar function is identical to putc with an output stream of stdout. sl@0: sl@0: The putw function writes the specified int to the named output stream. sl@0: sl@0: The putc_unlocked and putchar_unlocked functions are equivalent to putc and putchar respectively, sl@0: except that the caller is responsible for locking the stream with flockfile before calling them. sl@0: These functions may be used to avoid the overhead of locking the stream for each character, sl@0: and to avoid output being interspersed from multiple threads writing to the same stream. sl@0: sl@0: sl@0: Examples: sl@0: @code sl@0: #include sl@0: int main() sl@0: { sl@0: FILE * fp; sl@0: if( set_fmode('t') != 0 ) // setting text-mode as default file opening mode throughout the appln. sl@0: { sl@0: printf("Failed to set text-mode\n"); sl@0: return -1; sl@0: } sl@0: fp=fopen("C:\input.txt","w+"); sl@0: sl@0: if(fp==NULL) sl@0: { sl@0: printf("file opening failed"); sl@0: return -1; sl@0: } sl@0: if(putc('a',fp)!='a') sl@0: { sl@0: printf("putc failed"); sl@0: fclose(fp); sl@0: return -1; sl@0: } sl@0: else printf("character successfully put by putc"); sl@0: sl@0: fclose(fp); sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: character successfully put by putc sl@0: sl@0: @endcode sl@0: @see ferror() sl@0: @see flockfile() sl@0: @see fopen() sl@0: @see getc() sl@0: @see putwc() sl@0: @see set_fmode() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fputs(const char *s, FILE *fp) sl@0: @param s sl@0: @param fp sl@0: sl@0: Note: This description also covers the following functions - sl@0: puts() sl@0: sl@0: @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: sl@0: The function fputs writes the string pointed to by s to the stream pointed to by fp. sl@0: sl@0: The function puts writes the string s, and a terminating newline character, sl@0: to the stream stdout. sl@0: sl@0: sl@0: Examples: sl@0: @code sl@0: /*this program shows writing characters from a file using fputs */ sl@0: /* consider input.txt has the following content: */ sl@0: /* hello world */ sl@0: #include sl@0: int main(void) sl@0: { sl@0: int wretval; sl@0: char rs1[50],rs2[50]; sl@0: char *rptr; sl@0: int retval; sl@0: FILE *fp = NULL; sl@0: if( set_fmode('t') != 0 ) // setting text-mode as default file opening mode throughout the appln. sl@0: { sl@0: printf("Failed to set text-mode\n"); sl@0: return -1; sl@0: } sl@0: fp = fopen("c:\input.txt", "w"); sl@0: fprintf(fp, "%s", "abcdefghijklmn"); sl@0: fprintf(fp, "%c", ""); sl@0: fprintf(fp, "%s", "fdsfdsafsdabcdefghijklmn"); sl@0: fclose(fp); sl@0: fp = fopen("c:\input.txt","r"); sl@0: if(fp == NULL) sl@0: { sl@0: printf("fopen failed"); sl@0: return -1; sl@0: } sl@0: rptr = fgets(rs1,12,fp); sl@0: if(rptr == NULL) sl@0: { sl@0: printf("fgets failed"); sl@0: fclose(fp); sl@0: return -1; sl@0: } sl@0: fclose(fp); sl@0: fp = fopen("c:\puts1.txt","w+"); sl@0: if(fp == NULL) sl@0: { sl@0: printf("fopen failed"); sl@0: return -1; sl@0: } sl@0: wretval = fputs(rs1,fp); sl@0: if(wretval == EOF) sl@0: { sl@0: printf("fputs failed"); sl@0: fclose(fp); sl@0: return -1; sl@0: } sl@0: fclose(fp); sl@0: fp = fopen("C:\puts1.txt","r"); sl@0: if(fp == NULL) sl@0: { sl@0: printf("fopen failed"); sl@0: return -1; sl@0: } sl@0: rptr = fgets(rs2,12,fp); sl@0: if(rptr == NULL) sl@0: { sl@0: printf("fgets failed"); sl@0: fclose(fp); sl@0: return -1; sl@0: } sl@0: printf("file reading returned \"%s\",rs2); sl@0: fclose(fp); sl@0: unlink("C:\puts1.txt"); sl@0: sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: file reading returned "abcdefghijk" sl@0: sl@0: @endcode sl@0: @see ferror() sl@0: @see fputws() sl@0: @see putc() sl@0: @see set_fmode() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fread(void * buf, size_t size, size_t count, FILE * fp) sl@0: @param buf sl@0: @param size sl@0: @param count sl@0: @param fp sl@0: sl@0: Note: This description also covers the following functions - sl@0: fwrite() sl@0: sl@0: @return The functions fread and fwrite advance the file position indicator for the stream sl@0: by the number of bytes read or written. sl@0: They return the number of objects read or written. sl@0: If an error occurs, or the end-of-file is reached, sl@0: 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: 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: sl@0: 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: sl@0: 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: sl@0: sl@0: Examples: sl@0: @code sl@0: /* this program shows reading characters from a file using fread */ sl@0: /* consider input.txt has the following content: */ sl@0: /* hi */ sl@0: #include sl@0: int main() sl@0: { sl@0: char a; sl@0: FILE *fp = NULL; sl@0: if( set_fmode('t') != 0 ) // setting text-mode as default file opening mode throughtout the appln. sl@0: { sl@0: printf("Failed to set text-mode\n"); sl@0: return -1; sl@0: } sl@0: fp = fopen("c:\input.txt", "w"); sl@0: fprintf(fp, "%s", "abcdefghijklmn"); sl@0: fprintf(fp, "%c", '\n'); sl@0: fprintf(fp, "%s", "fdsfdsafsdabcdefghijklmn"); sl@0: fclose(fp); sl@0: fp = fopen("c:\input.txt", "r"); sl@0: if (fp == NULL) sl@0: { sl@0: printf ("fopen failed"); sl@0: return -1; sl@0: } sl@0: // read single chars at a time, stopping on EOF or error: sl@0: while (fread(&a;, sizeof(char), 1, fp), !feof(fp) && !ferror(fp)) sl@0: { sl@0: printf("I read \"%c\",a); sl@0: } sl@0: if (ferror(fp)) //Some error occurred sl@0: { sl@0: fclose(fp); sl@0: return -1; sl@0: } sl@0: fclose(fp); sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: I read "h" sl@0: I read "i" sl@0: sl@0: @endcode sl@0: @see read() sl@0: @see write() sl@0: @see set_fmode() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn freopen(const char *file, const char *mode, FILE *fp) sl@0: @param file sl@0: @param mode sl@0: @param fp sl@0: sl@0: Refer to fopen() for the documentation sl@0: @see open() sl@0: @see fclose() sl@0: @see fileno() sl@0: @see fseek() sl@0: sl@0: sl@0: sl@0: @capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&) sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn freopen64(const char *file, const char *mode, FILE *fp) sl@0: @param file sl@0: @param mode sl@0: @param fp sl@0: sl@0: For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0 sl@0: sl@0: @see freopen() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fscanf(FILE * fp, const char * fmt, ...) sl@0: @param fp sl@0: @param fmt sl@0: @param ... sl@0: sl@0: Refer to scanf() for the documentation sl@0: @see getc() sl@0: @see mbrtowc() sl@0: @see printf() sl@0: @see strtod() sl@0: @see strtol() sl@0: @see strtoul() sl@0: @see wscanf() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fseek(FILE *fp, long offset, int whence) sl@0: @param fp sl@0: @param offset sl@0: @param whence sl@0: sl@0: Note: This description also covers the following functions - sl@0: ftell() rewind() fgetpos() fsetpos() sl@0: sl@0: @return The rewind function returns no value. sl@0: 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: sl@0: The fseek function sets the file position indicator for the stream pointed to by fp. sl@0: The new position, measured in bytes, is obtained by adding offset bytes to the position specified by whence. sl@0: If whence is set to SEEK_SET, SEEK_CUR, or SEEK_END, the offset is relative to the start of the file, sl@0: the current position indicator, or end-of-file, respectively. sl@0: A successful call to the fseek function clears the end-of-file indicator for the stream and sl@0: undoes any effects of the ungetc and ungetwc functions on the same stream. sl@0: 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: sl@0: The ftell function obtains the current value of the file position indicator for the stream pointed to by fp. sl@0: sl@0: 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: sl@0: @code sl@0: (void)fseek(fp, 0L, SEEK_SET) sl@0: sl@0: @endcode sl@0: sl@0: except that the error indicator for the stream is also cleared. sl@0: Since rewind does not return a value, an application wishing to detect errors should clear errno, sl@0: then call rewind, and if errno is non-zero, assume an error has occurred. sl@0: The fgetpos and fsetpos functions are alternate interfaces for retrieving and setting the current position sl@0: in the file, similar to ftell and fseek, except that the current position is stored in an opaque object of sl@0: type fpos_t pointed to by pos. These functions provide a portable way to seek to offsets larger than those that sl@0: can be represented by a long int. They may also store additional state information in the fpos_t object to sl@0: facilitate seeking within files containing multibyte characters with state-dependent encodings. sl@0: Although fpos_t has traditionally been an integral type, applications cannot assume that it is; sl@0: in particular, they must not perform arithmetic on objects of this type. sl@0: If the stream is a wide character stream, the position specified by the combination of offset and whence must sl@0: contain the first byte of a multibyte sequence. sl@0: sl@0: Notes: Specific to text-mode Support: sl@0: 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: For more details, see set_fmode(). sl@0: 2. Offset set using fseek() in text-mode will not be appropriate because every newline will be converted to symbian specific sl@0: line-encodings( \n --> \r\n), thereby returning inappropriate offset values. sl@0: Thus, fseek(), ftell() will not return values as expected by the User. sl@0: 3. Offset value returned from ftell() can be used to pass to fseek() and sl@0: will not affect the functionality of any next read, write operations. sl@0: sl@0: sl@0: Examples: sl@0: @code sl@0: /* this program shows setting file offset using fseek */ sl@0: #include sl@0: int main(void) sl@0: { sl@0: int retval; sl@0: FILE *fp = NULL; sl@0: if( set_fmode('t') != 0 ) // setting text-mode as default file opening mode throughtout the appln. sl@0: { sl@0: printf("Failed to set text-mode\n"); sl@0: return -1; sl@0: } sl@0: fp = fopen("c:\input.txt", "w"); // opens file in default binary mode, hence fseek() works fine. sl@0: fprintf(fp, "%s", "abcdefghijklmn"); sl@0: fprintf(fp, "%c", ''); sl@0: fprintf(fp, "%s", "fdsfdsafsdabcdefghijklmn"); sl@0: fclose(fp); sl@0: fp = fopen("c:\input.txt", "r"); sl@0: if (fp == NULL) sl@0: { sl@0: printf ("fopen failed"); sl@0: return -1; sl@0: } sl@0: retval = fseek(fp, 3, SEEK_SET); // seek to the 20th byte of the file sl@0: if (retval) sl@0: { sl@0: printf ("fseek failed"); sl@0: return -1; sl@0: } sl@0: sl@0: long pos = ftell(fp); sl@0: if (pos ==3) sl@0: { sl@0: printf("offset setting proper"); sl@0: } sl@0: fclose(fp); sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: offset setting proper sl@0: sl@0: @endcode sl@0: sl@0: sl@0: sl@0: sl@0: @see lseek() sl@0: @see ungetc() sl@0: @see ungetwc() sl@0: @see set_fmode() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fsetpos(FILE *iop, const fpos_t *pos) sl@0: @param iop sl@0: @param pos sl@0: sl@0: Refer to fseek() for the documentation sl@0: @see lseek() sl@0: @see ungetc() sl@0: @see ungetwc() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fsetpos64(FILE *iop, const fpos64_t *pos) sl@0: @param iop sl@0: @param pos sl@0: sl@0: For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0 sl@0: sl@0: @see fsetpos() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn ftell(FILE *fp) sl@0: @param fp sl@0: sl@0: Refer to fseek(), set_fmode() for the documentation sl@0: @see lseek() sl@0: @see ungetc() sl@0: @see ungetwc() sl@0: @see set_fmode() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fwrite(const void * buf, size_t size, size_t count, FILE * fp) sl@0: @param buf sl@0: @param size sl@0: @param count sl@0: @param fp sl@0: sl@0: Refer to fread() for the documentation sl@0: @see read() sl@0: @see write() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn getc(FILE *fp) sl@0: @param fp sl@0: sl@0: Refer to fgetc() for the documentation sl@0: @see ferror() sl@0: @see flockfile() sl@0: @see fopen() sl@0: @see fread() sl@0: @see getwc() sl@0: @see putc() sl@0: @see ungetc() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn getchar() sl@0: @param sl@0: sl@0: Refer to fgetc() for the documentation sl@0: @see ferror() sl@0: @see flockfile() sl@0: @see fopen() sl@0: @see fread() sl@0: @see getwc() sl@0: @see putc() sl@0: @see ungetc() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn gets(char *str) sl@0: @param str sl@0: sl@0: Refer to fgets() for the documentation sl@0: @see feof() sl@0: @see ferror() sl@0: @see fgetln() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn perror(const char *string) sl@0: @param string sl@0: sl@0: Note: This description also covers the following functions - sl@0: strerror() strerror_r() sl@0: sl@0: @return strerror function returns the appropriate error description string, sl@0: or an unknown error message if the error code is unknown. The value of errno sl@0: is not changed for a successful call and is set to a nonzero value upon error. sl@0: The strerror_r function returns 0 on success and -1 on failure, setting sl@0: errno. sl@0: sl@0: The strerror , strerror_r and perror functions look up the error message string corresponding to an sl@0: error number. sl@0: sl@0: The strerror function accepts an error number argument errnum and returns a pointer to the corresponding sl@0: message string. sl@0: sl@0: The strerror_r function renders the same result into strerrbuf for a maximum of buflen characters and returns 0 upon success. sl@0: sl@0: The perror function finds the error message corresponding to the current sl@0: value of the global variable errno and writes it, followed by a newline, to the sl@0: standard error file descriptor. sl@0: If the argument string is non- NULL and does not point to the null character, sl@0: this string is prepended to the message sl@0: string and separated from it by sl@0: a colon and space (": "); sl@0: otherwise, only the error message string is printed. sl@0: sl@0: If the error number is not recognized, these functions return an error message sl@0: string containing "Unknown error: " sl@0: followed by the error number in decimal. sl@0: The strerror and strerror_r functions return EINVAL as a warning. sl@0: Error numbers recognized by this implementation fall in sl@0: the range 0 \< errnum \< sys_nerr . sl@0: sl@0: If insufficient storage is provided in strerrbuf (as specified in buflen ) sl@0: 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: sl@0: The message strings can be accessed directly using the external sl@0: array sys_errlist . sl@0: The external value sys_nerr contains a count of the messages in sys_errlist . sl@0: The use of these variables is deprecated; strerror or strerror_r should be used instead. sl@0: sl@0: Examples: sl@0: @code sl@0: #include sl@0: #include sl@0: #include sl@0: int main() sl@0: { sl@0: char *ptr = strerror(ERANGE); sl@0: printf("strerror(ERANGE) = %s",ptr); sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: strerror(ERANGE) = Numerical result out of range sl@0: sl@0: @endcode sl@0: @see intro() sl@0: sl@0: sl@0: Bugs: sl@0: sl@0: For unknown error numbers, the strerror function will return its result in a static buffer which sl@0: 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: inconsistently. sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn printf(const char *fmt, ...) sl@0: @param fmt sl@0: @param ... sl@0: sl@0: Note: This description also covers the following functions - sl@0: fprintf() sprintf() snprintf() asprintf() vprintf() vfprintf() vsprintf() vsnprintf() vasprintf() sl@0: sl@0: @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: The functions snprintf and vsnprintf do not write more than size bytes (including the trailing \\0). sl@0: If the output was truncated due to this limit then the return value sl@0: is the number of characters (not including the trailing \\0) sl@0: which would have been written to the final string if enough sl@0: space had been available. Thus, a return value of size or more sl@0: means that the output was truncated. sl@0: If an output error is encountered, a negative value is returned. sl@0: sl@0: 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: sl@0: 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: sl@0: 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: sl@0: 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: sl@0: 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: sl@0: The sprintf and vsprintf functions effectively assume an infinite size. sl@0: sl@0: @code sl@0: 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: sl@0: * 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: * Zero or more of the following flags: sl@0: '#' 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: '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: '-' 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: ' (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: '+' A sign must always be placed before a number produced by a signed conversion. A + overrides a space if both are used. sl@0: ''' 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: * 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: * 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: * 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: sl@0: Modifier d, i o, u, x, X n sl@0: hh signed char unsigned char signed char * sl@0: h short unsigned short short * sl@0: l (ell) long unsigned long long * sl@0: ll (ell ell) long long unsigned long long long long * sl@0: j intmax_t uintmax_t intmax_t * sl@0: t ptrdiff_t (see note) ptrdiff_t * sl@0: z (see note) size_t (see note) sl@0: q (deprecated) quad_t u_quad_t quad_t * sl@0: sl@0: sl@0: 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: sl@0: The following length modifier is valid for the a, A, e, E, f, F, g, or G conversion: sl@0: sl@0: Modifier a, A, e, E, f, F, g, G sl@0: l (ell) double (ignored, same behavior as without it) sl@0: L long double sl@0: sl@0: sl@0: The following length modifier is valid for the c or s conversion: sl@0: sl@0: Modifier c s sl@0: l (ell) wint_t wchar_t * sl@0: sl@0: sl@0: * A character that specifies the type of conversion to be applied. sl@0: sl@0: 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: @endcode sl@0: @code sl@0: The conversion specifiers and their meanings are: sl@0: diouxX sl@0: 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: 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: 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: sl@0: 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: 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: 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: 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: sl@0: 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: C Treated as c with the l (ell) modifier. sl@0: c The int argument is converted to an unsigned char , and the resulting character is written. sl@0: sl@0: 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: S Treated as s with the l (ell) modifier. sl@0: 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: sl@0: 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: p The void * pointer argument is printed in hexadecimal (as if by '%#x' or '%#lx' ). sl@0: 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: % A '%' is written. No argument is converted. The complete conversion specification is '%%'. sl@0: sl@0: @endcode sl@0: sl@0: The decimal point character is defined in the program's locale (category LC_NUMERIC ). sl@0: sl@0: 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: sl@0: sl@0: sl@0: Examples: sl@0: sl@0: To print a date and time in the form "Sunday, July 3, 10:02", sl@0: where weekday and month are pointers to strings: sl@0: @code sl@0: #include sl@0: fprintf(stdout, "%s, %s %d, %.2d:%.2d sl@0: ", sl@0: weekday, month, day, hour, min); sl@0: sl@0: @endcode sl@0: To print pi sl@0: to five decimal places: sl@0: @code sl@0: #include sl@0: #include sl@0: fprintf(stdout, "pi = %.5f sl@0: ", 4 * atan(1.0)); sl@0: sl@0: @endcode sl@0: To allocate a 128 byte string and print into it: sl@0: @code sl@0: #include sl@0: #include sl@0: #include sl@0: char *newfmt(const char *fmt, ...) sl@0: { sl@0: char *p; sl@0: va_list ap; sl@0: if ((p = malloc(128)) == NULL) sl@0: return (NULL); sl@0: va_start(ap, fmt); sl@0: (void) vsnprintf(p, 128, fmt, ap); sl@0: va_end(ap); sl@0: return (p); sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: /* this program shows printing onto the console using printf */ sl@0: #include sl@0: int main(void) sl@0: { sl@0: char * msg="hello world"; sl@0: printf("%s",msg); sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: hello world sl@0: sl@0: @endcode sl@0: @code sl@0: /* this program shows reading from console using scanf */ sl@0: #include sl@0: int main(void) sl@0: { sl@0: char msg[100]; sl@0: printf("enter message to be printed"); sl@0: scanf("%s",msg); sl@0: printf("message entered is: %s",msg); sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: enter message to be printed sl@0: hello (assuming this is user input) sl@0: message entered is: hello sl@0: sl@0: @endcode sl@0: sl@0: Security considerations: sl@0: sl@0: The sprintf and vsprintf functions are easily misused in a manner which enables malicious users sl@0: to arbitrarily change a running program's functionality through sl@0: a buffer overflow attack. sl@0: Because sprintf and vsprintf assume an infinitely long string, sl@0: callers must be careful not to overflow the actual space; sl@0: this is often hard to assure. sl@0: For safety, programmers should use the snprintf interface instead. sl@0: sl@0: The printf and sprintf family of functions are also easily misused in a manner sl@0: allowing malicious users to arbitrarily change a running program's sl@0: functionality by either causing the program sl@0: to print potentially sensitive data "left on the stack", sl@0: or causing it to generate a memory fault or bus error sl@0: by dereferencing an invalid pointer. \%n can be used to write arbitrary data to potentially carefully-selected sl@0: addresses. sl@0: Programmers are therefore strongly advised to never pass untrusted strings sl@0: as the format argument, as an attacker can put format specifiers in the string sl@0: to mangle your stack, sl@0: leading to a possible security hole. sl@0: 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: for later interpolation by printf. Always use the proper secure idiom: sl@0: sl@0: @code sl@0: snprintf(buffer, sizeof(buffer), "%s", string); sl@0: @endcode sl@0: @return None of these functions support long double length modifiers. Floating point sl@0: format specifiers support a maximum precision of 15 digits. sl@0: sl@0: @see printf() sl@0: @see scanf() sl@0: @see setlocale() sl@0: @see wprintf() sl@0: sl@0: sl@0: Bugs: sl@0: sl@0: The conversion formats \%D, \%O, and \%U are not standard and sl@0: are provided only for backward compatibility. sl@0: 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: of the \# flag on \%n and \%p conversions, as well as other sl@0: nonsensical combinations such as \%Ld, are not standard; such combinations sl@0: should be avoided. The printf family of functions do not correctly handle multibyte characters in the format argument. sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn putc(int c, FILE *fp) sl@0: @param c sl@0: @param fp sl@0: sl@0: Refer to fputc() for the documentation sl@0: @see ferror() sl@0: @see flockfile() sl@0: @see fopen() sl@0: @see getc() sl@0: @see putwc() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn putchar(int c) sl@0: @param c sl@0: sl@0: Refer to fputc() for the documentation sl@0: @see ferror() sl@0: @see flockfile() sl@0: @see fopen() sl@0: @see getc() sl@0: @see putwc() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn puts(const char *str) sl@0: @param str sl@0: sl@0: Refer to fputs() for the documentation sl@0: @see ferror() sl@0: @see fputws() sl@0: @see putc() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn remove(const char *file) sl@0: @param file sl@0: @return Upon successful completion, reomve return 0. sl@0: Otherwise, -1 is returned and the global variable errno is set to indicate the error. sl@0: sl@0: The remove function removes the file or directory specified by file. sl@0: sl@0: If file specifies a directory, remove (file); is the equivalent of rmdir (file); Otherwise, it is the equivalent of unlink (file); sl@0: sl@0: sl@0: Examples: sl@0: @code sl@0: /* this program shows deleting a file using remove */ sl@0: #include sl@0: int main() sl@0: { sl@0: char *name = "C:\input.txt"; sl@0: FILE *fp = NULL; sl@0: if( set_fmode('t') != 0 ) // setting text-mode as default file opening mode throughtout the appln. sl@0: { sl@0: printf("Failed to set text-mode\n"); sl@0: return -1; sl@0: } sl@0: fp = fopen(name, "w+"); sl@0: if (fp == NULL) sl@0: { sl@0: printf ("fopen failed"); sl@0: return -1; sl@0: } sl@0: fprintf(fp,"hello world"); sl@0: fclose(fp); sl@0: sl@0: remove(name); sl@0: fp=fopen(name,"r"); sl@0: if (fp == NULL) sl@0: { sl@0: printf ("file has been deleted already"); sl@0: } sl@0: else sl@0: { sl@0: printf("remove failed"); sl@0: return -1; sl@0: } sl@0: sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: file has been deleted already sl@0: sl@0: @endcode sl@0: sl@0: Limitations: sl@0: sl@0: - The file parameter of the remove() function should not exceed 256 characters in length. sl@0: - P.I.P.S. only simulates link files and does not distinguish between hard and symbolic links. sl@0: - KErrNotReady of Symbian error code is mapped to ENOENT, which typically means drive sl@0: not found or filesystem not mounted on the drive. sl@0: sl@0: @see rmdir() sl@0: @see unlink() sl@0: @see set_fmode() sl@0: sl@0: sl@0: @capability Deferred @ref RFs::RmDir(const TDesC16&) sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn rename(const char *oldpath, const char *newpath) sl@0: @param oldpath sl@0: @param newpath sl@0: @return The rename() function returns the value 0 if successful; otherwise the sl@0: value -1 is returned and the global variable errno is set to indicate the sl@0: error. sl@0: sl@0: The rename system call sl@0: causes the link named oldpath to be renamed as to. If to exists, it is first removed. sl@0: Both oldpath and newpath must be of the same type (that is, both directories or both sl@0: non-directories), and must reside on the same file system. sl@0: sl@0: If the final component of oldpath is a symbolic link, sl@0: the symbolic link is renamed, sl@0: not the file or directory to which it points. sl@0: sl@0: If a file with a symbolic link pointing to it is renamed, then sl@0: a subsequent open call on the symbolic link file would automatically remove the link file, i.e sl@0: consider a symbolic file link.x pointing to a file abc.x. If the file abc.x is sl@0: renamed to abcd.x then, a subsequent open call on link.x file would automatically remove link.x file. sl@0: sl@0: Note: sl@0: -# rename() does not differentiate between hard and soft links. sl@0: -# If the specified file is a dangling link file, then this link file will be automatically removed. sl@0: sl@0: sl@0: sl@0: Limitations: sl@0: sl@0: - The to and from parameters in rename() shouldn't exceed 256 characters. sl@0: - 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: - 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: is equal to time of last data modification. The time of last file status change for any file would be 0. sl@0: - KErrNotReady of Symbian error code is mapped to ENOENT, which typically means drive sl@0: not found or filesystem not mounted on the drive. sl@0: sl@0: Examples: sl@0: @code sl@0: /* sl@0: * Detailed description: This sample code demonstrates usage of rename system call. sl@0: * sl@0: * Preconditions: Example.cfg file should be present in the current working directory. sl@0: */ sl@0: #include sl@0: int main() sl@0: { sl@0: if(rename("Example.txt" , "Example2.txt") < 0 ) { sl@0: printf("Failed to rename Example.txt"); sl@0: return -1; sl@0: } sl@0: printf("Rename successful"); sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: Rename successful sl@0: sl@0: @endcode sl@0: @see open() sl@0: @see symlink() sl@0: sl@0: @capability Deferred @ref RFs::Rename(const TDesC16&, const TDesC16&) sl@0: @capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&) sl@0: @capability Deferred @ref RFs::RmDir(const TDesC16&) sl@0: @capability Deferred @ref RFs::SetAtt(const TDesC16&, unsigned, unsigned) sl@0: @capability Deferred @ref RFs::Delete(const TDesC16&) sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn rewind(FILE *fp) sl@0: @param fp sl@0: sl@0: Refer to fseek() for the documentation sl@0: @see lseek() sl@0: @see ungetc() sl@0: @see ungetwc() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn scanf(const char * fmt, ...) sl@0: @param fmt sl@0: @param ... sl@0: sl@0: Note: This description also covers the following functions - sl@0: fscanf() sscanf() vscanf() vsscanf() vfscanf() sl@0: sl@0: @return These functions return the number of input items assigned, which sl@0: can be fewer than provided for, or even zero, in the event of a matching failure. sl@0: Zero indicates that, while there was input available, no conversions were assigned; sl@0: typically this is due to an invalid input character, such as an alphabetic character sl@0: for a '\%d' conversion. The value EOF is returned if an input failure occurs before any conversion such sl@0: as an end-of-file occurs. If an error or end-of-file occurs after conversion has sl@0: begun, the number of conversions which were successfully completed is returned. sl@0: sl@0: sl@0: sl@0: 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: 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: sl@0: The vscanf function scans a variable argument list from the standard input sl@0: 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: 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: blanks, tabs, or newlines) in the format string match any amount of white space, including none, in the sl@0: input. Everything else matches only itself. Scanning stops when an input character sl@0: does not match such a format character. Scanning also stops when an input conversion sl@0: cannot be made (see below). sl@0: sl@0: sl@0: Examples: sl@0: @code sl@0: /* this program shows scanning from file using fscanf */ sl@0: #include sl@0: int main(void) sl@0: { sl@0: char x; sl@0: int ret; sl@0: char* filename="c:\ScanfTest1.txt"; sl@0: FILE *fp = NULL; sl@0: if( set_fmode('t') != 0 ) // setting text-mode as default file opening mode throughtout the appln. sl@0: { sl@0: printf("Failed to set text-mode\n"); sl@0: return -1; sl@0: } sl@0: fp=fopen(filename,"w"); sl@0: fprintf(fp,"%s","abcdesdafg"); sl@0: fclose(fp); sl@0: fp=fopen(filename,"r"); sl@0: ret=fscanf(fp,"%c",&x;); sl@0: fclose(fp); sl@0: printf("fscanf returned:%c",x); sl@0: unlink(filename); sl@0: getchar(); sl@0: if(ret!= 1) sl@0: return -1; sl@0: else sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: fscanf returned:a sl@0: sl@0: sl@0: @endcode sl@0: Examples: sl@0: @code sl@0: /* this program shows scanning from file using fscanf */ sl@0: #include sl@0: int main(void) sl@0: { sl@0: char x; sl@0: int ret; sl@0: char* filename="c:\ScanfTest1.txt"; sl@0: FILE *fp = NULL; sl@0: if( set_fmode('t') != 0 ) // setting text-mode as default file opening mode throughtout the appln. sl@0: { sl@0: printf("Failed to set text-mode\n"); sl@0: return -1; sl@0: } sl@0: fp=fopen(filename,"w"); sl@0: fprintf(fp,"%s","abcdesdafg"); sl@0: fclose(fp); sl@0: fp=fopen(filename,"r"); sl@0: ret=fscanf(fp,"%c",&x;); sl@0: fclose(fp); sl@0: printf("fscanf returned:%c",x); sl@0: unlink(filename); sl@0: getchar(); sl@0: if(ret!= 1) sl@0: return -1; sl@0: else sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: fscanf returned:a sl@0: sl@0: sl@0: @endcode sl@0: @return None of these functions support long double data types. sl@0: sl@0: @see getc() sl@0: @see mbrtowc() sl@0: @see printf() sl@0: @see strtod() sl@0: @see strtol() sl@0: @see strtoul() sl@0: @see wscanf() sl@0: @see set_fmode() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn setbuf(FILE * fp, char * buf) sl@0: @param fp sl@0: @param buf sl@0: sl@0: Note: This description also covers the following functions - sl@0: setbuffer() setlinebuf() setvbuf() sl@0: sl@0: 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: sl@0: 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: sl@0: 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: sl@0: @code sl@0: _IONBF sl@0: unbuffered sl@0: _IOLBF sl@0: line buffered sl@0: _IOFBF sl@0: fully buffered sl@0: @endcode sl@0: sl@0: 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: sl@0: 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: sl@0: 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: sl@0: @code sl@0: setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); sl@0: @endcode sl@0: sl@0: 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: @code sl@0: setvbuf(stream, (char *)NULL, _IOLBF, 0); sl@0: @endcode sl@0: sl@0: sl@0: Examples: sl@0: @code sl@0: /* this program shows setting up a buffer using setbuf * / sl@0: #include sl@0: int main() sl@0: { sl@0: FILE *fp = NULL; sl@0: char FullBuf[100]; sl@0: char msg[100]; sl@0: char * rptr; sl@0: char name[20] = "c:\setbuf1.txt"; sl@0: if( set_fmode('t') != 0 ) // setting text-mode as default file opening mode throughtout the appln. sl@0: { sl@0: printf("Failed to set text-mode\n"); sl@0: return -1; sl@0: } sl@0: fp = fopen(name, "w+"); sl@0: if (fp == NULL) sl@0: { sl@0: printf ("fopen failed"); sl@0: return -1; sl@0: } sl@0: setbuf(fp, FullBuf); // Fully buffered sl@0: if (ferror(fp)) sl@0: { sl@0: printf ("setbuf failed"); sl@0: fclose(fp); sl@0: unlink(name); sl@0: return -1; sl@0: } sl@0: fprintf(fp, "we are trying to buffer 20 characters at once "); sl@0: sl@0: fclose(fp); sl@0: fp=fopen(name,"r"); sl@0: rptr = fgets(msg,100,fp); sl@0: if(rptr == NULL) sl@0: { sl@0: printf("fgets failed"); sl@0: fclose(fp); sl@0: return -1; sl@0: } sl@0: printf("file reading returned \"%s\",msg); sl@0: fclose(fp); sl@0: sl@0: unlink(name); sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: file reading returned "we are trying to buffer 20 characters at once" sl@0: sl@0: sl@0: @endcode sl@0: @see fopen() sl@0: @see fread() sl@0: @see malloc() sl@0: @see printf() sl@0: @see set_fmode() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn setvbuf(FILE * fp, char * buf, int mode, size_t size) sl@0: @param fp sl@0: @param buf sl@0: @param mode sl@0: @param size sl@0: sl@0: Refer to setbuf() for the documentation sl@0: @see fopen() sl@0: @see fread() sl@0: @see malloc() sl@0: @see printf() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn sprintf(char * str, const char * fmt, ...) sl@0: @param str sl@0: @param fmt sl@0: @param ... sl@0: sl@0: Refer to printf() for the documentation sl@0: @see printf() sl@0: @see scanf() sl@0: @see setlocale() sl@0: @see wprintf() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn sscanf(const char * str, const char * fmt, ...) sl@0: @param str sl@0: @param fmt sl@0: @param ... sl@0: sl@0: Refer to scanf() for the documentation sl@0: @see getc() sl@0: @see mbrtowc() sl@0: @see printf() sl@0: @see strtod() sl@0: @see strtol() sl@0: @see strtoul() sl@0: @see wscanf() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn tmpfile(void) sl@0: sl@0: sl@0: Note: This description also covers the following functions - sl@0: tmpnam() tempnam() sl@0: sl@0: @return The tmpfile function sl@0: returns a pointer to an open file stream on success, and a NULL pointer sl@0: on error. The tmpnam and tempfile functions sl@0: return a pointer to a file name on success, and a NULL pointer sl@0: on error. sl@0: sl@0: The tmpfile function sl@0: returns a pointer to a stream associated with a file descriptor returned sl@0: by the routine mkstemp . sl@0: The created file is unlinked before tmpfile returns, causing the file to be automatically deleted when the last sl@0: reference to it is closed. sl@0: The file is opened with the access value 'w+'. sl@0: The file is created in the directory determined by the environment variable TMPDIR if set. sl@0: The default location if TMPDIR is not set is /tmp . sl@0: sl@0: @code sl@0: 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: indeterminate point in the past. P_tmpdir is defined in the include file #include . If the argument str is non- NULL , the file name is copied to the buffer it references. Otherwise, sl@0: the file name is copied to a static buffer. In either case, tmpnam returns a pointer to the file name. sl@0: @endcode sl@0: 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 \. sl@0: sl@0: The tempnam function sl@0: is similar to tmpnam , sl@0: but provides the ability to specify the directory which will sl@0: contain the temporary file and the file name prefix. sl@0: sl@0: The environment variable TMPDIR (if set), the argument tmpdir (if non- NULL ), sl@0: the directory P_tmpdir , sl@0: and the directory /tmp are tried, in the listed order, as directories in which to store the sl@0: temporary file. sl@0: sl@0: The argument prefix , if non- NULL , is used to specify a file name prefix, which will be the sl@0: first part of the created file name. The tempnam function allocates memory in which to store the file name; sl@0: the returned pointer may be used as a subsequent argument to free . sl@0: sl@0: Examples: sl@0: @code sl@0: #include //SEEK_SET, printf, tmpfile, FILE sl@0: #include //S_IWUSR sl@0: sl@0: int main() sl@0: { sl@0: //create the tmp directory sl@0: mkdir("c:\tmp", S_IWUSR); sl@0: sl@0: //call tmpfile to create a tempory file sl@0: FILE* fp = tmpfile(); sl@0: char buf[10]; sl@0: sl@0: if(fp) sl@0: { sl@0: //write onto the file sl@0: fprintf(fp, "%s", "hello"); sl@0: fflush(fp); sl@0: sl@0: //seek to the beginning of the file sl@0: fseek(fp, SEEK_SET, 0); //beg of the file sl@0: sl@0: //read from the file sl@0: fscanf(fp, "%s", buf); sl@0: fflush(fp); sl@0: sl@0: //close the file sl@0: fclose(fp); sl@0: } sl@0: sl@0: printf("buf read: %s", buf); sl@0: sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: buf read: hello sl@0: sl@0: @endcode sl@0: @code sl@0: #include //tmpnam, printf, FILE sl@0: #include //S_IWUSR sl@0: #include //errno sl@0: sl@0: int main() sl@0: { sl@0: //create a directory c:\system emp sl@0: mkdir("c:\system\temp", S_IWUSR); sl@0: sl@0: char buf[L_tmpnam]; sl@0: char rbuf[10]; sl@0: sl@0: //call tmpnam() to create a file sl@0: char *rval = tmpnam(buf); sl@0: sl@0: errno = 0; sl@0: //open the file with the name returned by tmpnam() sl@0: FILE *fp = fopen(buf, "w"); sl@0: sl@0: if (fp == NULL) sl@0: { sl@0: printf("fopen of file returned by tmpnam() failed - errno %d ", errno); sl@0: return -1; sl@0: } sl@0: sl@0: if(fp) sl@0: { sl@0: fprintf(fp, "%s", "check"); sl@0: fclose(fp); sl@0: } sl@0: sl@0: fp = fopen(buf, "r"); sl@0: sl@0: if(fp) sl@0: { sl@0: fscanf(fp, "%s", rbuf); sl@0: fclose(fp); sl@0: } sl@0: sl@0: printf("read from file: %s", rbuf); sl@0: printf("argument buf: %s", buf); sl@0: printf("return value: %s", rval); sl@0: sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: read from file: check sl@0: argument buf: /System/temp/tmp.0.U9UPTx sl@0: return value: /System/temp/tmp.0.U9UPTx sl@0: sl@0: @endcode sl@0: sl@0: Limitations: sl@0: sl@0: - The str parameter in tmpnam() respectively should not exceed 256 characters in length. sl@0: - The tmpdir parameter in tempnam() respectively should not exceed 256 characters in length. sl@0: sl@0: @see mktemp() sl@0: sl@0: sl@0: sl@0: @capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&) sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn tmpfile64(void) sl@0: sl@0: For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0 sl@0: sl@0: @see tmpfile() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn tmpnam(char *str) sl@0: @param str sl@0: sl@0: Refer to tmpfile() for the documentation sl@0: @see mktemp() sl@0: sl@0: sl@0: sl@0: @capability Deferred @ref RFs::MkDir(const TDesC16&) sl@0: @capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&) sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn ungetc(int c, FILE *fp) sl@0: @param c sl@0: @param fp sl@0: @return The ungetc function returns the character pushed-back after the conversion, sl@0: or EOF if the operation fails. sl@0: If the value of the argument c character equals EOF , sl@0: the operation will fail and the fp will remain unchanged. sl@0: sl@0: The ungetc function pushes the character c (converted to an unsigned char) sl@0: back onto the input stream pointed to by fp . sl@0: The pushed-back characters will be returned by subsequent reads on the sl@0: stream (in reverse order). sl@0: A successful intervening call, sl@0: using the same stream, sl@0: to one of the file positioning functions sl@0: ( fsetpos or rewind ) sl@0: will discard the pushed back characters. sl@0: sl@0: One character of push-back is guaranteed, sl@0: but as long as there is sufficient memory, sl@0: an effectively infinite amount of pushback is allowed. sl@0: sl@0: If a character is successfully pushed-back, sl@0: the end-of-file indicator for the stream is cleared. sl@0: The file-position indicator is decremented sl@0: by each successful call to ungetc ; sl@0: if its value was 0 before a call, its value is unspecified after sl@0: the call. sl@0: sl@0: sl@0: Examples: sl@0: @code sl@0: /* this pushing character to file stream using ungetc */ sl@0: #include sl@0: int main(void) sl@0: { sl@0: int c; sl@0: FILE *fp = NULL; sl@0: if( set_fmode('t') != 0 ) // setting text-mode as default file opening mode throughtout the appln. sl@0: { sl@0: printf("Failed to set text-mode\n"); sl@0: return -1; sl@0: } sl@0: fp = fopen("c:\input.txt", "w"); sl@0: fprintf(fp, "%s", "abcdefghijklmn"); sl@0: fprintf(fp, "%c", ''); sl@0: fprintf(fp, "%s", "fdsfdsafsdabcdefghijklmn"); sl@0: fclose(fp); sl@0: char * name = "C:\input.txt"; sl@0: fp = fopen(name, "w+"); sl@0: if (fp == NULL) sl@0: { sl@0: printf ("fopen failed"); sl@0: return -1; sl@0: } sl@0: if(ungetc('a',fp)!='a') printf("ungetc failed"); sl@0: sl@0: fseek(fp,-1,SEEK_CUR); sl@0: c=getc(fp); sl@0: printf("character read from stream is \"%c\",c); sl@0: fclose(fp); sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: character read from stream is "a" sl@0: sl@0: @endcode sl@0: @see fseek() sl@0: @see getc() sl@0: @see ungetwc() sl@0: @see set_fmode() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn vfprintf(FILE *fp, const char *fmt0, va_list ap) sl@0: @param fp sl@0: @param fmt0 sl@0: @param ap sl@0: sl@0: Refer to printf() for the documentation sl@0: @see printf() sl@0: @see scanf() sl@0: @see setlocale() sl@0: @see wprintf() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn vprintf(const char * fmt, va_list ap) sl@0: @param fmt sl@0: @param ap sl@0: sl@0: Refer to printf() for the documentation sl@0: @see printf() sl@0: @see scanf() sl@0: @see setlocale() sl@0: @see wprintf() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn vsprintf(char * str, const char *fmt, va_list ap) sl@0: @param str sl@0: @param fmt sl@0: @param ap sl@0: sl@0: Refer to printf() for the documentation sl@0: @see printf() sl@0: @see scanf() sl@0: @see setlocale() sl@0: @see wprintf() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn snprintf(char * str, size_t n, const char * fmt, ...) sl@0: @param str sl@0: @param n sl@0: @param fmt sl@0: @param ... sl@0: sl@0: Refer to printf() for the documentation sl@0: @see printf() sl@0: @see scanf() sl@0: @see setlocale() sl@0: @see wprintf() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn vfscanf(FILE * stream, const char * format, va_list ap) sl@0: @param stream sl@0: @param format sl@0: @param ap sl@0: sl@0: Refer to scanf() for the documentation sl@0: @see getc() sl@0: @see mbrtowc() sl@0: @see printf() sl@0: @see strtod() sl@0: @see strtol() sl@0: @see strtoul() sl@0: @see wscanf() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn vscanf(const char *fmt, va_list ap) sl@0: @param fmt sl@0: @param ap sl@0: sl@0: Refer to scanf() for the documentation sl@0: @see getc() sl@0: @see mbrtowc() sl@0: @see printf() sl@0: @see strtod() sl@0: @see strtol() sl@0: @see strtoul() sl@0: @see wscanf() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn vsnprintf(char * str, size_t n, const char * fmt, va_list ap) sl@0: @param str sl@0: @param n sl@0: @param fmt sl@0: @param ap sl@0: sl@0: Refer to printf() for the documentation sl@0: @see printf() sl@0: @see scanf() sl@0: @see setlocale() sl@0: @see wprintf() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn vsscanf(const char * str, const char * format, va_list ap) sl@0: @param str sl@0: @param format sl@0: @param ap sl@0: sl@0: Refer to scanf() for the documentation sl@0: @see getc() sl@0: @see mbrtowc() sl@0: @see printf() sl@0: @see strtod() sl@0: @see strtol() sl@0: @see strtoul() sl@0: @see wscanf() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fdopen(int fd, const char *mode) sl@0: @param fd sl@0: @param mode sl@0: sl@0: Refer to fopen() for the documentation sl@0: @see open() sl@0: @see fclose() sl@0: @see fileno() sl@0: @see fseek() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn fileno(FILE *fp) sl@0: @param fp sl@0: sl@0: Refer to clearerr() for the documentation sl@0: @see open() sl@0: @see flockfile() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn popen(const char *command, const char *mode) sl@0: @param command sl@0: @param mode sl@0: sl@0: Notes: sl@0: sl@0: 1. This description also covers the pclose() function. sl@0: sl@0: 2. When a child process created using popen() exits, the parent process receives a SIGCHLD signal. sl@0: sl@0: @return The popen function returns NULL if the fork sl@0: or pipe calls fail, sl@0: 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: returns an error. sl@0: sl@0: The popen function opens a process by creating a pipe, forking, and invoking sl@0: the shell. Since a pipe is by definition unidirectional, the type argument may specify only reading or writing, not both. The resulting sl@0: stream is correspondingly read-only ("r") or write-only "w". If type is anything sl@0: other than this the behavior is undefined. sl@0: sl@0: The command argument is a pointer to a null-terminated string containing a shell command line. sl@0: This command is passed to /bin/sh using the - c flag; interpretation, if any, is performed by the shell. sl@0: sl@0: 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: command. The command's standard output is the same as that of the process sl@0: that called popen, unless this is altered by the command itself. Conversely, reading sl@0: from a "popened" stream reads the command's standard output, and the command's sl@0: standard input is the same as that of the process that called popen. sl@0: sl@0: Note that output popen streams are fully buffered by default. sl@0: sl@0: The pclose function waits for the associated process to terminate sl@0: and returns the exit status of the command sl@0: as returned by sl@0: wait4. sl@0: sl@0: sl@0: sl@0: @see pipe() sl@0: @see fclose() sl@0: @see fflush() sl@0: @see fopen() sl@0: @see system() sl@0: sl@0: sl@0: Bugs: sl@0: sl@0: Since the standard input of a command opened for reading sl@0: shares its seek offset with the process that called popen, if the original process has done a buffered read, sl@0: the command's input position may not be as expected. sl@0: Similarly, the output from a command opened for writing sl@0: may become intermingled with that of the original process. sl@0: The latter can be avoided by calling fflush before popen. Failure to execute the shell sl@0: is indistinguishable from the shell's failure to execute command, sl@0: or an immediate exit of the command. sl@0: The only hint is an exit status of 127. The popen function sl@0: always calls sh and never calls csh. sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn popen3(const char *file, const char *cmd, char** envp, int fds[3]) sl@0: sl@0: Open stdin, stdout, and stderr streams and start external executable. sl@0: sl@0: Note: When a child process created using popen3() exits, the parent process receives a SIGCHLD signal. sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn ftrylockfile(FILE *fp) sl@0: @param fp sl@0: sl@0: Refer to flockfile() for the documentation sl@0: @see getc_unlocked() sl@0: @see putc_unlocked() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn flockfile(FILE *fp) sl@0: @param fp sl@0: sl@0: Note: This description also covers the following functions - sl@0: ftrylockfile() funlockfile() sl@0: sl@0: @return The flockfile and funlockfile functions return no value. The ftrylockfile function sl@0: returns zero if the stream was successfully locked,non-zero otherwise. sl@0: sl@0: These functions provide explicit application-level locking of stdio streams. sl@0: They can be used to avoid output from multiple threads being interspersed, sl@0: input being dispersed among multiple readers, and to avoid the overhead sl@0: of locking the stream for each operation. sl@0: sl@0: The flockfile function acquires an exclusive lock on the specified stream. sl@0: If another thread has already locked the stream flockfile will block until the lock is released. sl@0: sl@0: 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: sl@0: The funlockfile function releases the lock on a stream acquired by an earlier call to flockfile or ftrylockfile. sl@0: sl@0: These functions behave as if there is a lock count associated with each stream. sl@0: Each time flockfile is called on the stream the count is incremented and each sl@0: time funlockfile is called on the stream the count is decremented. The sl@0: lock is only actually released when the count reaches zero. sl@0: sl@0: sl@0: Examples: sl@0: @code sl@0: #include sl@0: #include sl@0: #include //link to the lib -libpthread sl@0: sl@0: void* somefun(void* args) sl@0: { sl@0: FILE *fp = (FILE *)args; sl@0: printf("in thr 2"); sl@0: flockfile(fp); sl@0: printf("aquired lock!"); sl@0: fputc('a', fp); //fputc_unlocked() is more relevant sl@0: printf("after a from thr 2"); sl@0: sleep(3); sl@0: printf("after sleep from thr 2"); sl@0: fputc('b', fp); sl@0: printf("after b from thr 2"); sl@0: fputc('c', fp); sl@0: printf("after c from thr 2"); sl@0: funlockfile(fp); sl@0: fclose(fp); sl@0: } sl@0: int main() sl@0: { sl@0: pthread_t obj; sl@0: FILE *fp = NULL; sl@0: if( set_fmode('t') != 0 ) // setting text-mode as default file opening mode throughtout the appln. sl@0: { sl@0: printf("Failed to set text-mode\n"); sl@0: return -1; sl@0: } sl@0: fp = fopen("c:\chk.txt", "w"); sl@0: if(fp) sl@0: { sl@0: flockfile(fp); sl@0: fputc('x', fp); //fputc_unlocked() is more relevant sl@0: printf("after x from thr 1"); sl@0: sleep(5); sl@0: printf("after sleep from thr 1"); sl@0: pthread_create(&obj;, NULL, somefun, fp); sl@0: printf("after calling thr 2 from thr 1"); sl@0: fputc('y', fp); sl@0: printf("after y from thr 1"); sl@0: fputc('z', fp); sl@0: printf("after z from thr 1"); sl@0: funlockfile(fp); sl@0: printf("gave up lock in thr 1"); sl@0: } sl@0: pthread_exit((void *)0); sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: after x from thr 1 sl@0: after sleep from thr 1 sl@0: in thr 2 sl@0: after calling thr 2 from thr 1 sl@0: after y from thr 1 sl@0: after z from thr 1 sl@0: gave up lock in thr 1 sl@0: acquired lock! sl@0: after a from thr 2 sl@0: after sleep from thr 2 sl@0: after b from thr 2 sl@0: after c from thr 2 sl@0: sl@0: Note: The printing takes quite some time and hence the sl@0: output may not look exactly like the above one. sl@0: (try printing to the files if you are very particular) sl@0: sl@0: sl@0: @endcode sl@0: @code sl@0: #include sl@0: #include sl@0: #include //link to lib -libpthread sl@0: #include sl@0: sl@0: void* somefun(void* args) sl@0: { sl@0: sl@0: FILE *fp = (FILE *)args; sl@0: sl@0: printf("in thr 2 sl@0: "); sl@0: sl@0: int i = ftrylockfile(fp); sl@0: if(i == 0) sl@0: { sl@0: printf("aquired lock!"); sl@0: fputc('a', fp); sl@0: printf("after a from thr 2"); sl@0: sleep(3); sl@0: printf("after sleep from thr 2"); sl@0: fputc('b', fp); sl@0: printf("after b from thr 2"); sl@0: fputc('c', fp); sl@0: printf("after c from thr 2"); sl@0: funlockfile(fp); sl@0: printf("gave up lock in thr 2"); sl@0: } sl@0: else sl@0: printf("couldn't aquire lock"); sl@0: } sl@0: int main() sl@0: { sl@0: pthread_t obj; sl@0: FILE *fp = NULL; sl@0: if( set_fmode('t') != 0 ) // setting text-mode as default file opening mode throughtout the appln. sl@0: { sl@0: printf("Failed to set text-mode\n"); sl@0: return -1; sl@0: } sl@0: fp = fopen("c:\chk.txt", "w"); sl@0: sl@0: if(fp) sl@0: { sl@0: flockfile(fp); sl@0: fputc('x', fp); sl@0: printf("after x from thr 1"); sl@0: sleep(5); sl@0: printf("after sleep from thr 1"); sl@0: pthread_create(&obj;, NULL, somefun, fp); sl@0: printf("after calling thr 2 from thr 1"); sl@0: fputc('y', fp); sl@0: printf("after y from thr 1"); sl@0: fputc('z', fp); sl@0: printf("after z from thr 1"); sl@0: funlockfile(fp); sl@0: printf("gave up lock in thr 1"); sl@0: sleep(5); sl@0: fclose(fp); sl@0: } sl@0: pthread_exit((void *)0); sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: after x from thr 1 sl@0: after sleep from thr 1 sl@0: in thr 2 sl@0: couldn't acquire lock sl@0: after calling thr 2 from thr 1 sl@0: after y from thr 1 sl@0: after z from thr 1 sl@0: gave up lock in thr 1 sl@0: sl@0: Note: The printing takes quite some time and hence the sl@0: output may not look exactly like the above one. sl@0: (try printing to the files if you are very particular) sl@0: sl@0: sl@0: @endcode sl@0: @see getc_unlocked() sl@0: @see putc_unlocked() sl@0: @see set_fmode() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn funlockfile(FILE *fp) sl@0: @param fp sl@0: sl@0: Refer to flockfile() for the documentation sl@0: @see getc_unlocked() sl@0: @see putc_unlocked() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn getc_unlocked(FILE *fp) sl@0: @param fp sl@0: sl@0: Refer to fgetc() for the documentation sl@0: @see ferror() sl@0: @see flockfile() sl@0: @see fopen() sl@0: @see fread() sl@0: @see getwc() sl@0: @see putc() sl@0: @see ungetc() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn getchar_unlocked(void) sl@0: sl@0: sl@0: Refer to fgetc() for the documentation sl@0: @see ferror() sl@0: @see flockfile() sl@0: @see fopen() sl@0: @see fread() sl@0: @see getwc() sl@0: @see putc() sl@0: @see ungetc() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn putc_unlocked(int ch, FILE *fp) sl@0: @param ch sl@0: @param fp sl@0: sl@0: Refer to fputc() for the documentation sl@0: @see ferror() sl@0: @see flockfile() sl@0: @see fopen() sl@0: @see getc() sl@0: @see putwc() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn putchar_unlocked(int ch) sl@0: @param ch sl@0: sl@0: Refer to fputc() for the documentation sl@0: @see ferror() sl@0: @see flockfile() sl@0: @see fopen() sl@0: @see getc() sl@0: @see putwc() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn getw(FILE *fp) sl@0: @param fp sl@0: sl@0: Refer to fgetc() for the documentation sl@0: @see ferror() sl@0: @see flockfile() sl@0: @see fopen() sl@0: @see fread() sl@0: @see getwc() sl@0: @see putc() sl@0: @see ungetc() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn putw(int w, FILE *fp) sl@0: @param w sl@0: @param fp sl@0: sl@0: Refer to fputc() for the documentation sl@0: @see ferror() sl@0: @see flockfile() sl@0: @see fopen() sl@0: @see getc() sl@0: @see putwc() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn tempnam(const char *, const char *) sl@0: Refer to tmpfile() for the documentation sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn asprintf(char **str, const char *fmt, ...) sl@0: @param str sl@0: @param fmt sl@0: @param ... sl@0: sl@0: Refer to printf() for the documentation sl@0: @see printf() sl@0: @see scanf() sl@0: @see setlocale() sl@0: @see wprintf() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn setbuffer(FILE *fp, char *buf, int size) sl@0: @param fp sl@0: @param buf sl@0: @param size sl@0: sl@0: Refer to setbuf() for the documentation sl@0: @see fopen() sl@0: @see fread() sl@0: @see malloc() sl@0: @see printf() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn setlinebuf(FILE *fp) sl@0: @param fp sl@0: sl@0: Refer to setbuf() for the documentation sl@0: @see fopen() sl@0: @see fread() sl@0: @see malloc() sl@0: @see printf() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn vasprintf(char **str, const char *fmt, va_list ap) sl@0: @param str sl@0: @param fmt sl@0: @param ap sl@0: sl@0: Refer to printf() for the documentation sl@0: @see printf() sl@0: @see scanf() sl@0: @see setlocale() sl@0: @see wprintf() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn ftruncate(int fd, off_t length) sl@0: @param fd sl@0: @param length sl@0: sl@0: Refer to truncate() for the documentation sl@0: @see open() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn lseek(int fildes, off_t offset, int whence) sl@0: @param fildes sl@0: @param offset sl@0: @param whence sl@0: @return Upon successful completion, lseek returns the resulting offset location as measured in bytes from the sl@0: beginning of the file. sl@0: Otherwise, sl@0: a value of -1 is returned and errno is set to indicate sl@0: the error. sl@0: sl@0: The lseek system call repositions the offset of the file descriptor fildes to the argument offset according to the directive whence. sl@0: 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: @code sl@0: If whence is SEEK_SET, the offset is set to offset bytes. sl@0: If whence is SEEK_CUR, the offset is set to its current location plus offset bytes. sl@0: If whence is SEEK_END, the offset is set to the size of the file plus offset bytes. sl@0: @endcode sl@0: Some devices are incapable of seeking. The value of the pointer associated with such a device is undefined. sl@0: sl@0: 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: undefined untill data is actually written into it. lseek beyond existing end-of-file increases the file size accordingly. sl@0: sl@0: sl@0: sl@0: Examples: sl@0: @code sl@0: /* Detailed description : Example for lseek usage.*/ sl@0: #include sl@0: #include sl@0: #include sl@0: #include sl@0: int main() sl@0: { sl@0: int fd = 0; sl@0: fd = open("lseek.txt" , O_CREAT | O_RDWR , 0666); sl@0: if(lseek(fd , 0 , SEEK_SET) < 0 ) { sl@0: printf("Lseek on file lseek.txt failed"); sl@0: return -1; sl@0: } sl@0: printf("Lseek on lseek.txt passed "); sl@0: return 0; sl@0: } sl@0: sl@0: @endcode sl@0: @code sl@0: Output sl@0: sl@0: Lseek on lseek.txt passed sl@0: sl@0: @endcode sl@0: @see dup() sl@0: @see open() sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: sl@0: /** @fn truncate(const char *path, off_t length) sl@0: @param path sl@0: @param length sl@0: sl@0: Note: This description also covers the following functions - sl@0: ftruncate() sl@0: sl@0: @return Upon successful completion, both truncate() and ftruncate() return 0; otherwise, sl@0: they return -1 and set errno to indicate the error. sl@0: sl@0: The truncate system call sl@0: causes the file named by path or referenced by fd to be truncated to length bytes in size. sl@0: If the file sl@0: was larger than this size, the extra data sl@0: is lost. sl@0: If the file was smaller than this size, sl@0: it will be extended as if by writing bytes with the value zero. sl@0: With ftruncate , sl@0: the file must be open for writing. sl@0: sl@0: Examples: sl@0: @code sl@0: //example for truncate sl@0: #include sl@0: #include sl@0: #include sl@0: int test_truncate() sl@0: { sl@0: int retVal, retVal2, retSize, retSize2; sl@0: struct stat buf; sl@0: ssize_t size; sl@0: char *buffer = "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwx"; sl@0: int fp = open("c: est.txt", O_RDWR|O_CREAT); sl@0: size = write(fp,buffer,50); sl@0: close(fp); sl@0: retVal2 = stat("c: est.txt", &buf; ); sl@0: if ( !retVal2 ) sl@0: { sl@0: retSize = buf.st_size; sl@0: printf("Size before: %d", retSize); sl@0: retVal = truncate("c: est.txt", retSize/2 ); sl@0: } sl@0: else sl@0: { sl@0: printf("Failed"); sl@0: } sl@0: retVal2 = stat( "c: est.txt", &buf; ); sl@0: if ( !retVal2 ) sl@0: { sl@0: retSize2 = buf.st_size; sl@0: if( retSize2 == (retSize/2 ) ) sl@0: { sl@0: printf("Size after: %d", retSize2); sl@0: printf("Truncate passed"); sl@0: return 0; sl@0: } sl@0: else sl@0: { sl@0: printf("Failed"); sl@0: return -1; sl@0: } sl@0: } sl@0: else sl@0: { sl@0: printf("Failed"); sl@0: return -1; sl@0: } sl@0: } sl@0: sl@0: Output sl@0: Size before: 50 sl@0: Size after: 25 sl@0: Ttruncate Passed sl@0: @endcode sl@0: sl@0: @code sl@0: //example for ftruncate sl@0: #include sl@0: #include sl@0: int test_ftruncate() sl@0: { sl@0: //assuming that the file exists and has some //data in it sl@0: int fp = open("c: est.txt", O_RDWR); sl@0: int retVal, retVal2, retSize, retSize2; sl@0: struct stat buf; sl@0: if(fp != -1) sl@0: { sl@0: retVal2 = fstat( fp, &buf; ); sl@0: if ( !retVal2 ) sl@0: { sl@0: retSize = buf.st_size; sl@0: printf("Size before: %d", retSize); sl@0: retVal = ftruncate( fp, retSize/2 ); sl@0: close(fp); sl@0: } sl@0: else sl@0: { sl@0: printf("Failed"); sl@0: } sl@0: fp = open("c: est.txt", O_RDONLY); sl@0: if((fp != -1) && (!retVal)) sl@0: { sl@0: retVal2 = fstat( fp, &buf; ); sl@0: if ( !retVal2 ) sl@0: { sl@0: retSize2 = buf.st_size; sl@0: if( retSize2 == (retSize/2 ) ) sl@0: { sl@0: printf("Size after: %d", retSize2); sl@0: printf("Ftruncate Passed"); sl@0: } sl@0: else sl@0: { sl@0: printf("Failed"); sl@0: } sl@0: } sl@0: else sl@0: { sl@0: printf("Failed"); sl@0: } sl@0: } sl@0: } sl@0: sl@0: Output sl@0: Size before: 100 sl@0: Size after: 50 sl@0: Ftruncate Passed sl@0: sl@0: @endcode sl@0: @see open() sl@0: sl@0: sl@0: Bugs: sl@0: sl@0: These calls should be generalized to allow ranges sl@0: of bytes in a file to be discarded. Use of truncate to extend a file is not portable. sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn int setecho(int fd, uint8_t echoval) sl@0: @param fd sl@0: @param echoval sl@0: sl@0: Turns On/Off the echo for the input characters. sl@0: If echoval is 0, the echo is turned off and nothing gets echoed on the console. sl@0: If echoval is 1, the echo is turned on. sl@0: If echoval is anything else, the echo is turned off and the given printable character sl@0: will be echoed instead the actual input character. sl@0: sl@0: Notes: sl@0: The given fd should be that of a console. sl@0: If the stdio redirection server is used to redirect the stdin/stdout of a process and sl@0: if the given fd maps to one of those, then the stdin will only be affected by this call. sl@0: Write operations on this fd will not be affected. sl@0: The earlier behavior is retained if setecho() fails. sl@0: sl@0: @return Upon successfull completion it returns 0, otherwise -1, setting the errno. sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def va_list sl@0: sl@0: The type va_list is defined for variables used to traverse the list. sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def vfscanf sl@0: sl@0: To be used for vfscanf(..) sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def __SNBF sl@0: sl@0: unbuffered sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def __SRD sl@0: sl@0: OK to read sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def __SLBF sl@0: sl@0: line buffered sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def __SWR sl@0: sl@0: OK to write sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def __SRW sl@0: sl@0: open for reading & writing sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def __SEOF sl@0: sl@0: found EOF sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def __SERR sl@0: sl@0: found error sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def __SMBF sl@0: sl@0: _buf is from malloc sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def __SAPP sl@0: sl@0: fdopen()ed in append mode sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def __SSTR sl@0: sl@0: this is an sprintf or snprintf string sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def __SOPT sl@0: sl@0: do fseek() optimization sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def __SNPT sl@0: sl@0: do not do fseek() optimization sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def __SOFF sl@0: sl@0: set iff _offset is in fact correct sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def __SMOD sl@0: sl@0: true; fgetln modified _p text sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def __SALC sl@0: sl@0: allocate string space dynamically sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def __SIGN sl@0: sl@0: ignore this file in _fwalk sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def _IOFBF sl@0: sl@0: setvbuf should set fully buffered sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def _IOLBF sl@0: sl@0: setvbuf should set line buffered sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def _IONBF sl@0: sl@0: setvbuf should set unbuffered sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def BUFSIZ sl@0: sl@0: size of buffer used by setbuf sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def EOF sl@0: sl@0: End of file sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def FOPEN_MAX sl@0: sl@0: must be less than OPEN_MAX sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def FILENAME_MAX sl@0: sl@0: must be less than PATH_MAX sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def SEEK_END sl@0: sl@0: set file offset to EOF plus offset sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def SEEK_CUR sl@0: sl@0: set file offset to current plus offset sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def SEEK_SET sl@0: sl@0: set file offset to offset sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def TMP_MAX sl@0: sl@0: temporary max value sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def L_tmpnam sl@0: sl@0: must be == PATH_MAX sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def stdin sl@0: sl@0: standard input variable sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def stdout sl@0: sl@0: standard output variable sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def stderr sl@0: sl@0: standard error variable sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def L_cuserid sl@0: sl@0: size for cuserid(3) sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def L_ctermid sl@0: sl@0: size for ctermid(3) sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: sl@0: /** @def __isthreaded sl@0: sl@0: defined to isthreaded() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def feof(p) sl@0: sl@0: Functions defined in ANSI C standard. sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def ferror(p) sl@0: sl@0: Functions defined in ANSI C standard. sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def clearerr(p) sl@0: sl@0: Functions defined in ANSI C standard. sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def fileno(p) sl@0: sl@0: Functions defined in ANSI C standard. sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def getc(fp) sl@0: sl@0: Functions defined in ANSI C standard. sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def getchar() sl@0: sl@0: Defined to getc(stdin) sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @def putchar(x) sl@0: sl@0: defined to putc(x,stdout) sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @struct __sbuf sl@0: sl@0: stdio buffers sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @var __sbuf::_base sl@0: Pointer to the buffer sl@0: */ sl@0: sl@0: /** @var __sbuf::_size sl@0: size of the buffer sl@0: */ sl@0: sl@0: /** @struct __sFILE sl@0: sl@0: stdio state file variables. sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @typedef typedef __off_t fpos_t sl@0: sl@0: Represents file position sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @typedef typedef __off_t fpos64_t sl@0: sl@0: Represents large file position sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @typedef typedef __size_t size_t sl@0: sl@0: A type to define sizes of strings and memory blocks. sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @typedef typedef __va_list va_list sl@0: sl@0: A void pointer which can be interpreted as an argument list. sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: sl@0: /** @fn tmpdirname(void) sl@0: sl@0: @return Upon successful completion tmpdirname() will return the path of the private directory of that process. sl@0: sl@0: Note:String that the function will return is not to be modified. sl@0: sl@0: Examples: sl@0: sl@0: @code sl@0: sl@0: /* Illustrates how to use tmpdirname() API */ sl@0: #include sl@0: int main() sl@0: { sl@0: char *ptr; sl@0: ptr=tmpdirname(); sl@0: printf("%s\n",ptr); sl@0: return 0; sl@0: } sl@0: @endcode sl@0: sl@0: @publishedAll sl@0: @released sl@0: */ sl@0: sl@0: /** @fn set_fmode(char mode) sl@0: @param mode sl@0: @return set_fmode() returns 0 on success, otherwise returns -1 with an errno set to EINVAL. sl@0: sl@0: set_fmode(), get_fmode() are used to provide text-mode support. sl@0: sl@0: 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: sl@0: 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: 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: has been opened and before it is closed, the buffer needs to be flushed explicitly. sl@0: sl@0: 2>. If the user mixes the two file modes, there might be unexpected behaviour. sl@0: For example, a file is opened in text mode, written with 20 bytes and closed. sl@0: 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: the read data will not be complete. sl@0: sl@0: Examples: sl@0: @code sl@0: /* sl@0: * Detailed description : To set the mode of a file to either text/binary explicitly sl@0: */ sl@0: #include sl@0: int main() sl@0: { sl@0: int ret; sl@0: ret = set_fmode('t'); sl@0: if(ret != 0 ) sl@0: { sl@0: printf("Failed to set text mode\n") ; sl@0: return -1 ; sl@0: } sl@0: printf("Successfully able to set text mode\n") ; sl@0: if (get_fmode() != 't') sl@0: { sl@0: printf("Failed to Retrieve file-mode\n") ; sl@0: return -1 ; sl@0: } sl@0: printf("Successfully able to Retrieve file-mode\n") ; sl@0: getchar(); sl@0: return 0 ; sl@0: } sl@0: sl@0: @endcode sl@0: sl@0: @see get_fmode() sl@0: @see fopen() sl@0: @see fclose() sl@0: @see setvbuf() sl@0: @see ftell() sl@0: @see fseek() sl@0: @see fread() sl@0: @see fwrite() sl@0: @see fputs() sl@0: @see fputc() sl@0: @see fgets() sl@0: @see fgetc() sl@0: @see fprintf() sl@0: @see fscanf() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn get_fmode( ) sl@0: @return get_fmode() returns the current file open mode as either 't' or 'b'. 't' is returned if text-mode is set sl@0: explicitly using set_fmode(), otherwise 'b' binary-mode is returned which is default in symbian. sl@0: sl@0: Examples: sl@0: @code sl@0: /* sl@0: * Detailed description : To Retrieve the current mode of a file sl@0: */ sl@0: #include sl@0: int main() sl@0: { sl@0: int ret; sl@0: ret = set_fmode('t'); sl@0: if(ret != 0 ) sl@0: { sl@0: printf("Failed to set text mode\n") ; sl@0: return -1 ; sl@0: } sl@0: printf("Successfully able to set text mode\n") ; sl@0: if (get_fmode() != 't') sl@0: { sl@0: printf("Failed to Retrieve file-mode\n") ; sl@0: return -1 ; sl@0: } sl@0: printf("Successfully able to Retrieve file-mode\n") ; sl@0: getchar(); sl@0: return 0 ; sl@0: } sl@0: sl@0: @endcode sl@0: sl@0: Examples: sl@0: @code sl@0: /* sl@0: * Detailed description : General example to illustrate set_fmode(), get_fmode() sl@0: */ sl@0: #include sl@0: int main() sl@0: { sl@0: char *data = "helloworld\nfine"; sl@0: char *p = NULL; sl@0: int ret = 0; sl@0: FILE *fw = NULL, *fr = NULL; sl@0: sl@0: ret = set_fmode('t'); // To set text-mode using set_fmode() sl@0: if(ret != 0 ) sl@0: { sl@0: printf("Failed to set text mode") ; sl@0: return -1 ; sl@0: } sl@0: if (get_fmode() != 't') sl@0: { sl@0: printf("Failed to Retrieve file-mode") ; sl@0: return -1 ; sl@0: } sl@0: sl@0: fw = fopen("c:\\temp_tc.txt", "w"); sl@0: int count = fwrite(data, 1, strlen(data), fw); sl@0: if(count != strlen(data)) sl@0: { sl@0: printf("fwrite() failed\n"); sl@0: goto end; sl@0: } sl@0: fclose(fw); sl@0: fw = fopen("c:\\temp_tc_out.txt", "w"); sl@0: fr = fopen("c:\\temp_tc.txt", "r"); sl@0: p = (char *)malloc(count+1); // extra one is for holding '\0' sl@0: if( !p ) sl@0: { sl@0: printf("malloc() failed\n"); sl@0: goto end; sl@0: } sl@0: char *retn = fgets(p, count, fr); sl@0: //ret = fread(p, 1, 11, fr); sl@0: if(strlen(p) != 11) sl@0: { sl@0: printf("1st read failed\n"); sl@0: goto end; sl@0: } sl@0: int pos = ftell(fr); // 12 -> offset sl@0: printf("pos After 1st read: %d\n", pos); sl@0: fseek(fr,pos,SEEK_SET); sl@0: ret = fread(p+11,1,4,fr); sl@0: if( ret != 4) sl@0: { sl@0: printf("Failed to read using fread()\n"); sl@0: goto end; sl@0: } sl@0: p[count] = '\0'; sl@0: pos = ftell(fr); // 16 -> offset sl@0: printf("pos After 2nd read: %d\n", pos); sl@0: getchar(); sl@0: count = fwrite(p, 1, strlen(p), fw); sl@0: if(count != strlen(p)) sl@0: { sl@0: printf(" Failed to write onto another file\n"); sl@0: getchar(); sl@0: } sl@0: else sl@0: { sl@0: printf("Passed to write onto another file\n"); sl@0: getchar(); sl@0: } sl@0: end: sl@0: if(p) sl@0: { sl@0: free(p); sl@0: p = NULL; sl@0: } sl@0: if(fr) sl@0: fclose(fr); sl@0: if(fw) sl@0: fclose(fw); sl@0: return 0; sl@0: } sl@0: @endcode sl@0: sl@0: @code sl@0: sl@0: Output: sl@0: pos After 1st read: 12 sl@0: pos After 2nd read: 20 sl@0: Passed to write onto another file sl@0: sl@0: @endcode sl@0: sl@0: @see set_fmode() sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */