fgetpos() — Get file position

Standards

Standards / Extensions C or C++ Dependencies
ISO C
XPG4
XPG4.2
C99
Single UNIX Specification, Version 3 Language Environment®
 both  

Format

#include <stdio.h>

int fgetpos(FILE * __restrict__stream, fpos_t * __restrict__pos);

#define _OPEN_SYS_UNLOCKED_EXT 1
#include <stdio.h>

int fgetpos_unlocked(FILE * __restrict__stream, fpos_t * __restrict__pos);

General description

The fgetpos() function stores the current value of the file pointer associated with stream into the object pointed to by pos. The value pointed to by pos can be used later in a call to fsetpos() to reposition the stream pointed to by stream.

Both the fgetpos() and fsetpos() function save state information for wide-oriented files. The value stored in pos is unspecified, and it is usable only by fsetpos().

The position returned by the fgetpos() function is affected by the ungetc() and ungetwc() functions. Each call to these functions causes the file position indicator to be backed up from the position where the ungetc() or ungetwc() function was issued. For details on how the ungetc() function affects the fgetpos() function behavior, see ungetc() — Push character onto input stream. For details on how the ungetwc() function affects the fgetpos() function behavior for a wide-oriented stream, see ungetwc() — Push a wide character onto a stream.

Multivolume data sets performance: Using the fgetpos() and fsetpos() functions generally results in better repositioning performance compared to the ftell() and fseek() functions when working with multivolume data sets.

Large file support for MVS™ data sets, VSAM data sets, and z/OS® UNIX files: The fgetpos() function implicitly supports operating on large files. Defining the _LARGE_FILES feature test macro is not required to use this function on large files.

Usage notes

  1. The _EDC_COMPAT environment variable can be set at open time such that the fgetpos() function will ignore any pushed-back characters. For further details on _EDC_COMPAT, see the environment variables topic in z/OS XL C/C++ Programming Guide.
  2. The fgetpos_unlocked() function is functionally equivalent to the fgetpos() function with the exception that it is not threadsafe. The fgetpos() 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() functions.

Returned value

If successful, the fgetpos() function returns 0.

If unsuccessful, the fgetpos() function returns nonzero and sets errno to nonzero.

Special behavior for XPG4.2: The fgetpos() function returns -1 and sets errno to ESPIPE if the underlying file type for the stream is a PIPE or a socket.

Example

CELEBF17 
/* CELEBF17

   This example opens the file myfile.dat for reading.
   The current file pointer position is stored into the variable pos.

 */
#include <stdio.h>

int main(void)
{
   FILE *stream;
   int retcode;
   fpos_t pos;

   stream = fopen("myfile.dat", "rb");

   /* The value returned by fgetpos can be used by fsetpos()
      to set the file pointer if 'retcode' is 0            */

   if ((retcode = fgetpos(stream, &pos)) == 0)
      printf("Current position of file pointer found\n");
   fclose(stream);
}

Related information