.\" gd_alter_protection.3.  The gd_alter_protection man page.
.\"
.\" Copyright (C) 2008, 2010, 2012 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_alter_protection 3 "1 January 2012" "Version 0.8.0" "GETDATA"
.SH NAME
gd_alter_protection \(em modify the protection level of a dirfile fragment
.SH SYNOPSIS
.B #include <getdata.h>
.HP
.nh
.ad l
.BI "int gd_alter_protection(DIRFILE *" dirfile ", int"
.IB protection_level ", int " fragment_index );
.hy
.ad n
.SH DESCRIPTION
The
.BR gd_alter_protection ()
function sets the advisory protection level of the format specification fragment
given by
.I fragment_index
to
.I protection_level
in the dirfile(5) database specified by
.IR dirfile .

The
.I protection_level
argument should be one of the following:
.TP
.BR GD_PROTECT_NONE
Indicating that the fragment should not be protected at all.
.TP
.B GD_PROTECT_FORMAT
Indicating that the fragment's metadata should be protected.
.TP
.B GD_PROTECT_DATA
Indicating that the fragment's binary data should be protected.
.TP
.B GD_PROTECT_ALL
Indicating that both the fragment's metadata and its binary data should be
protected.  This symbol is equivalent to the bitwise or of
.B GD_PROTECT_FORMAT
and
.BR GD_PROTECT_DATA .
.PP
In addition to being simply a valid fragment index,
.I fragment_index
may also be the special value
.BR GD_ALL_FRAGMENTS ,
which indicates that the protection level of all fragments in the database
should be changed.

.SH RETURN VALUE
Upon successful completion,
.BR gd_alter_protection ()
returns zero.  On error, it returns -1 and sets the dirfile error to 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_ARGUMENT
The supplied
.I protection_level
was invalid.
.TP
.B GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.TP
.B GD_E_BAD_INDEX
The supplied index was out of range.
.TP
.B GD_E_BAD_PROTECTION
The supplied protection level was invalid.
.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 NOTES
This is the only GetData function which ignores the (existing) protection
level of a format specification fragment.
.SH SEE ALSO
.BR gd_open (3),
.BR gd_error (3),
.BR gd_error_string (3),
.BR gd_protection (3),
.BR dirfile (5),
.BR dirfile-format (5)