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

# gd\_invalid\_dirfile(3)

obtain an pointer to an invalid DIRFILE object

## NAME

gd\_invalid\_dirfile — obtain an pointer to an invalid DIRFILE object

## SYNOPSIS

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

**DIRFILE\* gd\_invalid\_dirfile(void);**

## DESCRIPTION

The **gd\_invalid\_dirfile**() returns a pointer to a newly allocated, invalid DIRFILE object.  Like any other DIRFILE object, the invalid DIRFILE object should be de-allocated by calling [**gd\_close**(3)](/gd_close/3.md) or [**gd\_discard**(3)](/gd_discard/3.md) when it is no longer needed.

The DIRFILE object returned may be passed to any other GetData function which requires one, but doing so will inevitably result in that function failing with the **GD\_BAD\_DIRFILE** error.

A similar effect can be achieved by making an invalid [**gd\_open**(3)](/gd_open/3.md) call, such as:

-

  **gd\_open(**""**,** 0**);**

which also returns a pointer to an invalid DIRFILE object.  The difference is that an invalid DIRFILE created in this way has a non-zero error code (obtainable with [**gd\_error**(3)](/gd_error/3.md)), while the dirfile error of the invalid DIRFILE returned by [**gd\_invalid\_dirfile**(3)](/gd_invalid_dirfile/3.md) is zero (indicating success).

## RETURN VALUE

This function always returns a pointer to a newly allocated, invalid DIRFILE object, except when it is unable to allocate memory for the DIRFILE, in which case it returns NULL.

## HISTORY

The **gd\_invalid\_dirfile**() function appeared in GetData-0.7.0.

## SEE ALSO

[**gd\_close**(3)](/gd_close/3.md), [**gd\_discard**(3)](/gd_discard/3.md), [**gd\_error**(3)](/gd_error/3.md), [**gd\_open**(3)](/gd_open/3.md)