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

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

If unsuccessful, the ftello() function returns (off_t)-1 and sets errno to one of the following values:
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 _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

Parent topic: Library functions