.\" gd_hide.3.  The gd_hidden man page.
.\"
.\" Copyright (C) 2012, 2013 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_hide 3 "10 December 2013" "Version 0.9.0" "GETDATA"
.SH NAME
gd_hide, gd_unhide \(em hide or unhide a dirfile database entry
.SH SYNOPSIS
.B #include <getdata.h>
.HP
.nh
.ad l
.BI "int gd_hide(const DIRFILE *" dirfile ", const char"
.BI * entry_name );
.HP
.BI "int gd_unhide(const DIRFILE *" dirfile ", const char"
.BI * entry_name );
.hy
.ad n
.SH DESCRIPTION
The
.BR gd_hide ()
function hides the field or alias called
.IR entry_name
in the dirfile(5) database specified by
.I dirfile
and indicates whether the field or alias called is hidden or not.  Similarly,
the
.BR gd_unhide ()
function unhides the specified entry.  An entry can also be hidden or unhidden
using
.BR gd_alter_entry (3).

A hidden entry does not appear in the field lists returned by the functions
.BR gd_field_list (3),
.BR gd_field_list_by_type (3),
.BR gd_vectors (3),
.BR gd_constants (3),
and
.BR gd_strings (3).
These omissions are also reflected in the counts returned by the corresponding
field counting functions
.RB ( gd_nfields (3),
&c.).  A hidden field is otherwise no different than an unhidden field.
.SH RETURN VALUE
Upon successful completion,
.BR gd_hide ()
and
.BR gd_unhide ()
return zero.  On error they returns -1 and sets the dirfile error a non-zero
error value.  Possible error values are:
.TP 8
.B GD_E_ACCMODE
The specified dirfile was opened read-only.
.TP
.B GD_E_BAD_CODE
The field specified by
.I field_code
was not found in the database.
.TP
.B GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.TP
.B GD_E_PROTECTED
The metadata of the affected format specification fragments was protected from
change.
.PP
The dirfile error may be retrieved by calling
.BR gd_error (3).
A descriptive error string for the last error encountered can be obtained from
a call to
.BR gd_error_string (3).

.SH SEE ALSO
.BR gd_alter_entry (3),
.BR gd_field_list (3),
.BR gd_hidden (3),
.BR gd_nfields (3),
.BR gd_open (3),
.BR dirfile (5)