ftello() — Get current file position
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
Single UNIX Specification, Version 2
Single UNIX Specification, Version 3 Language Environment® |
both | OS/390® V2R10
|
Format
#define _XOPEN_SOURCE 500
#include <stdio.h>
off_t ftello(FILE *stream);
#define _OPEN_SYS_UNLOCKED_EXT 1
#include <stdio.h>
off_t ftello_unlocked(FILE *stream);
General description
The ftello() function obtains the current value of the file position indicator for the stream pointed to by stream.
Behavior for binary streams: ANSI states that the ftello() function returns relative byte offsets from the beginning of the file for binary files. Under z/OS® XL C/C++, this is true except for record-oriented files that have variable length records. For these types of files, the ftello() function returns an encoded offset.
If you want to use relative-byte offsets for these types of files, you can either open the file with the BYTESEEK fopen() function option or set the _EDC_BYTE_SEEK environment variable before opening.
Behavior for text streams: The ftello() function returns an encoded offset for text streams.
Behavior
for record I/O: For files opened for record I/O using the type=record
open
mode parameter, the ftello() function returns the relative record
offset of the current file position from the beginning of the file.
All offset values are given in terms of records.
Behavior
for blocked I/O: For files opened for blocked I/O using the type=blocked
open
mode parameter, the ftello() function returns the relative block offset
of the current file position from the beginning of the file. All offset
values are given in terms of blocks.
Multivolume data sets performance: Using the fgetpos() and fsetpos() functions generally results in better repositioning performance compared to the ftello() and fseeko() functions when working with multivolume data sets.
Large file support for MVS™ data sets, VSAM data sets, and z/OS UNIX files: For AMODE 31 C/C++ applications, the ftello() function accepts a signed 4-byte offset and therefore cannot be used to directly or relatively position to offsets beyond 2 GB - 1. To avoid repositioning limitations, AMODE 31 C/C++ applications should define the _LARGE_FILES feature test macro before any headers are included. For AMODE 64 C/C++ applications, there are no restrictions on using the ftello() function with large files. The AMODE 64 version automatically accepts a signed 8-byte offset.
Usage notes
- The ftello_unlocked() function is functionally equivalent to the ftello() function with the exception that it is not threadsafe. The ftello() function can safely be used in a multithreaded application if, and only if, it is called while the invoking thread owns the (FILE*) object, as is the case after a successful call to either the flockfile() or ftrylockfile() function.
Returned value
If successful, the ftello() function returns the calculated value.
- Error Code
- Description
- EBADF
- The file descriptor underlying stream is not an open file descriptor.
- EOVERFLOW
- The current file offset cannot be represented correctly in an object of type off_t.
- ESPIPE
- The file descriptor underlying stream is associated with a pipe or FIFO.
Example
/* This example opens the file myfile.dat for reading.
The current file pointer position is stored in the variable
pos.
*/
#define _XOPEN_SOURCE 500
#define _LARGE_FILES 1
#include <stdio.h>
int main(void)
{
FILE *stream;
off_t pos;
stream = fopen("/myfile.dat", "rb");
/* The value returned by ftello() can be used by fseeko()
to set the file pointer if 'pos' is not -1 */
if ((pos = ftello(stream)) != -1LL)
printf("Current position of file pointer found\n");
fclose(stream);
}
Related information
- For information about BYTESEEK or _EDC_BYTE_SEEK, see z/OS XL C/C++ Programming Guide.
- For information about calling the ftello() function after an ungetc() or ungetwc() function call, see ungetc() — Push character onto input stream and ungetwc() — Push a wide character onto a stream.
- For additional usage information about the ftello() function with respect to MVS data sets, VSAM data sets, or z/OS UNIX files, see z/OS XL C/C++ Programming Guide.
- stdio.h — Standard input and output
- fgetpos() — Get file position
- fopen() — Open a file
- fseek() — Change file position
- fsetpos() — Set file position
- ftell() — Get current file position
- ungetc() — Push character onto input stream
- ungetwc() — Push a wide character onto a stream