.\" 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_flags.3.  The gd_flags man page.
.\"
.\" Copyright (C) 2012, 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_flags 3 "25 December 2016" "Version 0.10.0" "GETDATA"

.SH NAME
gd_flags \(em alter GetData operational flags

.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "unsigned long gd_flags(DIRFILE *" dirfile ", unsigned long " set ,
.BI "unsigned long " reset );
.EC

.SH DESCRIPTION
The
.FN gd_flags
function modifies the operational flags of the dirfile(5) database specified by
.ARG dirfile ,
and returns the new value of the flags register.

The flags which may be queried or modified with this interface are a subset of
the open flags (see
.F3 gd_cbopen ).
These are:
.DD GD_PRETTY_PRINT
When dirfile metadata are flushed to disk (either explicitly via
.BR gd_metaflush "(3), " gd_rewrite_fragment (3),
or 
.F3 gd_flush
or implicitly by closing the dirfile), an attempt will be made to create a
nicer looking format specification (from a human-readable standpoint).  What
this explicitly means is not part of the API, and any particular behaviour
should not be relied on.  If the dirfile has been opened read-only, this flag is
ignored.
.DD GD_VERBOSE
Specifies that whenever an error is triggered by the library when working
on this dirfile, the corresponding error string, which can be retrieved by
calling 
.F3 gd_error_string ,
should be written on the caller's standard error stream
.RB ( stderr (3))
by GetData.  The error string may be prefixed by a string specified by the
caller; see
.F3 gd_verbose_prefix .
Without this flag, GetData writes nothing to standard error.  (GetData never
writes to standard output.)
.PP
Flags which appear only in
.ARG set
will be turned on (enabled); flags which appear only in
.ARG reset
will be turned off (disabled); flags which appear in both
.ARG set
and
.ARG reset
will be toggled.  Flags which appear in neither of these are left unchanged.
Accordingly, to simply query the current flags, both
.ARG set
and
.ARG reset
should be zero, and to explicitly specify all the flags, ignoring their old
values, the new flags register should be given in
.ARG set ,
and it's bitwise complement in
.ARG reset .

.SH RETURN VALUE
The
.FN gd_flags
function returns a bitwise or'd collection those of the above flags which are
enabled after performing the modifications specified (if any).  This function
does not fail.

.SH HISTORY
The
.FN gd_flags
function appeared in GetData-0.8.0.

.SH SEE ALSO
.F3 gd_open ,
.F3 gd_verbose_prefix ,
dirfile(5)