FTELL(3) Library Functions Manual FTELL(3)

ftell ftello — return a file offset in a stream

#include <stdio.h>

long ftell(FILE *stream);
[CX] off_t ftello(FILE *stream);

[CX] The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of POSIX.1-2024 defers to the ISO C standard.

The ftell () function shall obtain the current value of the file-position indicator for the stream pointed to by .

The ftell () function shall not change the setting of errno if successful.

[CX] The ftello () function shall be equivalent to ftell (), except that the return value is of type and the ftello () function may change the setting of errno if successful.

Upon successful completion, ftell () [CX] and ftello () shall return the current value of the file-position indicator for the stream measured in bytes from the beginning of the file, [CX] except in the case of streams opened with open_wmemstream(3) for which the position shall be measured in wide characters.

Otherwise, ftell () and ftello () shall return -1, and set errno to indicate the error.

The ftell () [CX] and ftello () functions shall fail if:

[CX] The file descriptor underlying stream is not an open file descriptor.
[CX] For ftell (), the current file offset cannot be represented correctly in an object of type long .
[CX] For ftello (), the current file offset cannot be represented correctly in an object of type off_t .
[CX] The file descriptor underlying stream is associated with a pipe, FIFO, or socket.

None.

None.

For all streams other than those opened by open_wmemstream(3), ftell () and fseek(3) operate on byte offsets. The behavior with open_wmemstream(3) streams is intentionally different— ftell(3) and fseek(3) operate on wide character offsets. This is because those streams are unique in that the backing storage is not a multibyte representation but a wide character array, and it is useful to be able to use the output of ftell () to index into that array.

None.

V2_chap02(3), fgetpos(3), fopen(3), fseek(3), lseek(3), open_memstream(3)

XBD <stdio.h>

First released in Issue 1. Derived from Issue 1 of the SVID.

Large File Summit extensions are added.

Extensions beyond the ISO C standard are marked.

The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:

  • The ftello () function is added.
  • The [EOVERFLOW] error conditions are added.

An additional [ESPIPE] error condition is added for sockets.

POSIX.1-2008, Technical Corrigendum 1, XSH/TC1-2008/0204 [105], XSH/TC1-2008/0205 [421], XSH/TC1-2008/0206 [122], XSH/TC1-2008/0207 [122], and XSH/TC1-2008/0208 [14] are applied.

Austin Group Defect 1027 is applied, specifying that for streams opened with open_wmemstream(3) the position is measured in wide characters, not bytes.

June 14, 2024 posix.fail