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

# gd\_error(3)

report a GetData library error

## NAME

gd\_error, gd\_error\_string — report a GetData library error

## SYNOPSIS

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

**int gd\_error(const DIRFILE \****dirfile***);**

**char \*gd\_error\_string(const DIRFILE \****dirfile***, char \****buffer***, size\_t** *buflen***);**

## DESCRIPTION

The **gd\_error**() function determines the success or failure of the most recent GetData library function call that operated on *dirfile*. If the last call succeeded, **gd\_error**() will return **GD\_E\_OK** (which equals zero).  If the last call failed, **gd\_error**() returns a negative-valued error code indicating the cause of the failure. Possible codes vary from function to function.  See corresponding manual page of the function that failed for a list of possible codes.

The **gd\_error\_string**() function behaves similarly, but composes a string describing the error.  If  *buffer* is not NULL, the string is written to this memory location.  At most *buflen* characters will be written including the terminating NUL byte.  If *buffer* is not large enough to hold the entire string, the string will be truncated, but the truncated string will still be NUL-terminated.

If *buffer* is NULL, **gd\_error\_string**() will allocate a string of sufficient length on the heap.  In this case, *buflen* is ignored.  By default, [**malloc**(3)](/malloc/3.md) is used to allocate this buffer, but an alternate memory manager may be specified by calling [**gd\_alloc\_funcs**(3)](/gd_alloc_funcs/3.md) before calling this function.  The caller is responsible for deallocating this string when it is no longer needed.

The functions [**gd\_alloc\_funcs**(3)](/gd_alloc_funcs/3.md), [**gd\_error\_count**(3)](/gd_error_count/3.md), [**gd\_flags**(3)](/gd_flags/3.md), [**gd\_free\_entry\_strings**(3)](/gd_free_entry_strings/3.md), [**gd\_mplex\_lookback**(3)](/gd_mplex_lookback/3.md), and [**gd\_parser\_callback**(3)](/gd_parser_callback/3.md) are ignored by these functions, since they always succeed.  Previous **gd\_error()** and **gd\_error\_string()** calls are also ignored.

## RETURN VALUE

The **gd\_error**() function always returns the integer error code of the last library call on the supplied DIRFILE object.

If *buffer* is non-NULL, **gd\_error\_string**() returns  *buffer*, unless *buflen* is less than one, in which case it returns NULL.  If *buffer* is NULL, this function returns a newly allocated string of sufficient length which should be deallocated by the caller, or NULL, if memory allocation failed.

## HISTORY

The **get\_error\_string**() function appeared in GetData-0.3.0.

The **get\_error**() function appeared in GetData-0.4.0.  Before this, the error code was directly accessible via the *dirfile***-\>***error* member in the **DIRFILE** structure.

In GetData-0.7.0, these functions were renamed to **gd\_error**() and **gd\_error\_string**(). This is also the first release in which **gd\_error\_string**() would allocate a buffer for the error string if passed NULL.

## SEE ALSO

[**gd\_error\_count**(3)](/gd_error_count/3.md)