---
name: "gd_tell"
section: "3"
platform: "linux"
package: "libgetdata-doc"
version: "0.11.0-15"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/gd_tell"
---

# gd\_tell(3)

report the position of a Dirfile field I/O pointer

## NAME

gd\_tell — report the position of a Dirfile field I/O pointer

## SYNOPSIS

**#include \<getdata.h\>**

**off\_t gd\_tell(DIRFILE \****dirfile***, const char \****field\_code***);**

## DESCRIPTION

The **gd\_tell**() function reports the current position of the I/O pointer of the field *field\_code* in the [dirfile(5)](/dirfile/5.md) database specified by *dirfile*.

Only **RAW** fields (and the implicit *INDEX* field) have field pointers associated with them.  Calling **gd\_tell**() on a derived field will report the position of the I/O pointer of the derived field only if all of it's inputs are positioned the same.  Otherwise, an error results.

## RETURN VALUE

Upon successful completion, **gd\_tell**() returns a non-negative integer indicating the I/O position of the specified field in samples.  On error, it returns a negative-valued error code.  Possible error codes are:\
  .TP 8 **GD\_E\_ALLOC** The library was unable to allocate memory.\
  .TP 8 **GD\_E\_BAD\_CODE** The field specified by *field\_code*, or one of the fields it uses for input, was not found in the database.\
  .TP 8 **GD\_E\_BAD\_DIRFILE** The supplied dirfile was invalid.\
  .TP 8 **GD\_E\_DIMENSION** The specified field or one of its inputs wasn't of vector type.\
  .TP 8 **GD\_E\_DOMAIN** The I/O position of a derived field wasn't well defined because its input fields simultaneously read from different places in the same **RAW** field.\
  .TP 8 **GD\_E\_INTERNAL\_ERROR** An internal error occurred in the library while trying to perform the task. This indicates a bug in the library.  Please report the incident to the maintainer.\
  .TP 8 **GD\_E\_IO** An error occurred while trying to open or read from a file on disk containing a raw field.\
  .TP 8 **GD\_E\_RECURSE\_LEVEL** Too many levels of recursion were encountered while trying to resolve *field\_code*. This usually indicates a circular dependency in field specification in the dirfile.\
  .TP 8 **GD\_E\_UNKNOWN\_ENCODING** The encoding scheme of a RAW field could not be determined.  This may also indicate that the binary file associated with the RAW field could not be found.\
  .TP 8 **GD\_E\_UNSUPPORTED** Reading from dirfiles with the encoding scheme of the specified dirfile is not supported by the library.  See [dirfile-encoding(5)](/dirfile-encoding/5.md) for details on dirfile encoding schemes.

The error code is also stored in the **DIRFILE** object and may be retrieved after this function returns by calling [**gd\_error**(3)](/gd_error/3.md). A descriptive error string for the error may be obtained by calling [**gd\_error\_string**(3)](/gd_error_string/3.md).

## HISTORY

The **gd\_tell**() function appeared in GetData-0.8.0.

In GetData-0.10.0, the error return from this function changed from -1 to a negative-valued error code.

## SEE ALSO

[**gd\_getdata**(3)](/gd_getdata/3.md), [**gd\_open**(3)](/gd_open/3.md), [**gd\_putdata**(3)](/gd_putdata/3.md), [**gd\_seek**(3)](/gd_seek/3.md).