.\" gd_encoding.3.  The gd_encoding man page.
.\"
.\" Copyright (C) 2008, 2009, 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_encoding 3 "21 April 2012" "Version 0.8.0" "GETDATA"
.SH NAME
gd_encoding \(em report the binary encoding of data in a dirfile
.SH SYNOPSIS
.B #include <getdata.h>
.HP
.nh
.ad l
.BI "unsigned long gd_encoding(DIRFILE *" dirfile ", int " fragment_index );
.hy
.ad n
.SH DESCRIPTION
The
.BR gd_encoding ()
function queries a dirfile(5) database specified by
.I dirfile
and returns the binary encoding for the fragment indexed by
.IR fragment_index .
The binary encoding of a fragment indicate the encoding of data stored in binary
files associated with
.B RAW
fields defined in the specified fragment.  The encoding of a fragment
containing no
.B RAW
fields is ignored.

.SH RETURN VALUE
Upon successful completion,
.BR gd_encoding ()
returns the binary encoding of the specified fragment, which will one of the
following symbols:
.IP
.nh
.ad l
.BR GD_UNENCODED ,
.BR GD_BZIP2_ENCODED ,
.BR GD_GZIP_ENCODED ,
.BR GD_LZMA_ENCODED ,
.BR GD_SIE_ENCODED ,
.BR GD_SLIM_ENCODED ,
.BR GD_TEXT_ENCODED ,
.BR GD_ZZIP_ENCODED ,
.BR GD_ZZSLIM_ENCODED ,
.BR GD_ENC_UNSUPPORTED .
.ad n
.hy
.PP
If the encoding scheme specified in the dirfile
metadata is unknown to GetData,
.B GD_ENC_UNSUPPORTED
will be returned.  See
.BR gd_cbopen (3)
and dirfile-encoding(5) for the meanings of the other symbols and details on the
supported encoding schemes.
.PP
On error, it returns zero and sets the dirfile error to a non-zero error value. 
Possible error values are:
.TP 8
.B GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.TP
.B GD_E_BAD_INDEX
The supplied index was out of range.
.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_encoding (3),
.BR gd_cbopen (3),
.BR gd_error (3),
.BR gd_error_string (3),
.BR gd_getdata (3),
.BR dirfile (5),
.BR dirfile-format (5)