.\" header.tmac.  GetData manual macros.
.\"
.\" Copyright (C) 2016 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.

.\" Format a function name with optional trailer: func_name()trailer
.de FN \" func_name [trailer]
.nh
.BR \\$1 ()\\$2
.hy
..

.\" Format a reference to section 3 of the manual: name(3)trailer
.de F3 \" func_name [trailer]
.nh
.BR \\$1 (3)\\$2
.hy
..

.\" Format the header of a list of definitons
.de DD \" name alt...
.ie "\\$2"" \{ \
.TP 8
.PD
.B \\$1 \}
.el \{ \
.PP
.B \\$1
.PD 0
.DD \\$2 \\$3 \}
..

.\" Start a code block: Note: groff defines an undocumented .SC for
.\" Bell Labs man legacy reasons.
.de SC
.fam C
.na
.nh
..

.\" End a code block
.de EC
.hy
.ad
.fam
..

.\" Format a structure pointer member: struct->member\fRtrailer
.de SPM \" struct member trailer
.nh
.ie "\\$3"" .IB \\$1 ->\: \\$2
.el .IB \\$1 ->\: \\$2\fR\\$3
.hy
..

.\" Format a function argument
.de ARG \" name trailer
.nh
.ie "\\$2"" .I \\$1
.el .IR \\$1 \\$2
.hy
..

.\" Hyphenation exceptions
.hw sarray carray lincom linterp
.\" gd_invalid_dirfile.3.  The gd_invalid_dirfile man page.
.\"
.\" Copyright (C) 2010, 2016 D.V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
.TH gd_invalid_dirfile 3 "25 December 2016" "Version 0.10.0" "GETDATA"

.SH NAME
gd_invalid_dirfile \(em obtain an pointer to an invalid DIRFILE object

.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "DIRFILE* gd_invalid_dirfile(void);
.EC

.SH DESCRIPTION
The
.FN 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
.F3 gd_close
or
.F3 gd_discard
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
.B GD_BAD_DIRFILE
error.

A similar effect can be achieved by making an invalid
.F3 gd_open
call, such as:
.SC
.IP
.BR gd_open( """""" ,\~ 0 );
.EC
.PP
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
.F3 gd_error ),
while the dirfile error of the invalid DIRFILE returned by
.F3 gd_invalid_dirfile
is zero (indicating success).

.SH 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.

.SH HISTORY
The
.FN gd_invalid_dirfile
function appeared in GetData-0.7.0.

.SH SEE ALSO
.F3 gd_close ,
.F3 gd_discard ,
.F3 gd_error ,
.F3 gd_open