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) or gd_discard(3) 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) 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  dirfile  error  (obtainable  with
       gd_error(3)),   while   the   dirfile   error   of   the   invalid   DIRFILE  returned  by
       gd_invalid_dirfile(3) 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.

SEE ALSO

       gd_close(3), gd_discard(3), gd_error(3), gd_open(3)