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.

SEE ALSO

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