.\" 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_alter_protection.3.  The gd_alter_protection man page.
.\"
.\" Copyright (C) 2008, 2010, 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_alter_protection 3 "25 December 2016" "Version 0.10.0" "GETDATA"

.SH NAME
gd_alter_protection \(em modify the protection level of a Dirfile fragment

.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "int gd_alter_protection(DIRFILE *" dirfile ", int"
.IB protection_level ", int " fragment_index );
.EC

.SH DESCRIPTION
The
.FN gd_alter_protection
function sets the advisory protection level of the format specification fragment
given by
.ARG fragment_index
to
.ARG protection_level
in the dirfile(5) database specified by
.ARG dirfile .

The
.ARG protection_level
argument should be one of the following:
.DD GD_PROTECT_NONE
Indicating that the fragment should not be protected at all.
.DD GD_PROTECT_FORMAT
Indicating that the fragment's metadata should be protected.
.DD GD_PROTECT_DATA
Indicating that the fragment's binary data should be protected.
.DD 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,
.ARG 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,
.FN gd_alter_protection
returns zero.  On error, it returns a negative-valued error code.  Possible
error codes are:
.DD GD_E_ACCMODE
The specified dirfile was opened read-only.
.DD GD_E_ARGUMENT
The supplied
.ARG protection_level
was invalid.
.DD GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.DD GD_E_BAD_INDEX
The supplied index was out of range.
.DD GD_E_BAD_PROTECTION
The supplied protection level was invalid.
.PP
The error code is also stored in the
.B DIRFILE
object and may be retrieved after this function returns by calling
.F3 gd_error .
A descriptive error string for the error may be obtained by calling
.F3 gd_error_string .

.SH NOTES
This is the only GetData function which ignores the (existing) protection
level of a format specification fragment.

.SH HISTORY

The function
.FN dirfile_protect
appeared in GetData-0.5.0.

In GetData-0.7.0, this function was renamed to
.FN gd_alter_protection .

In GetData-0.10.0, the error return from this function changed from -1 to a
negative-valued error code.

.SH SEE ALSO
.F3 gd_error ,
.F3 gd_error_string ,
.F3 gd_protection ,
.F3 gd_open