gd_alter_encoding(3)

1
2
3
4
5
6
7
8
9gd_alter_encoding(3)                GETDATA               gd_alter_encoding(3)
10
11
12

NAME

14       gd_alter_encoding — modify the binary encoding of data in a Dirfile
15
16

SYNOPSIS

18       #include <getdata.h>
19
20       int gd_alter_encoding(DIRFILE *dirfile, unsigned int encoding, int
21              fragment_index, int recode);
22
23

DESCRIPTION

25       The gd_alter_encoding() function sets the binary encoding of the format
26       specification  fragment  given by fragment_index to the encoding speci‐
27       fied by encoding in the dirfile(5) database specified by dirfile.   The
28       binary  encoding  of a fragment indicate the encoding of data stored in
29       binary files associated with RAW fields defined in the specified  frag‐
30       ment.   The  binary  encoding of a fragment containing no RAW fields is
31       ignored.
32
33       The encoding argument should be one of the following symbols:
34
35              GD_UNENCODED, GD_BZIP2_ENCODED, GD_FLAC_ENCODED,
36              GD_GZIP_ENCODED, GD_LZMA_ENCODED, GD_SLIM_ENCODED,
37              GD_SIE_ENCODED, GD_TEXT_ENCODED.
38
39       See gd_open(3) and dirfile-encoding(5) for the meanings of  these  sym‐
40       bols and details on the supported encoding schemes.
41
42       In  addition to being simply a valid fragment index, fragment_index may
43       also be the special value GD_ALL_FRAGMENTS, which  indicates  that  the
44       encoding of all fragments in the database should be changed.
45
46       If  the  recode  argument is non-zero, this call will recode the binary
47       data of affected RAW fields to account for the change in binary  encod‐
48       ing.   If  the  encoding of the fragment is encoding insensitive, or if
49       the data type is only one byte in size, no change  is  made.   The  I/O
50       pointer of all affected RAW fields is reset to the beginning-of-frame.
51
52       If recode is zero, affected binary files are left untouched.
53
54

RETURN VALUE

56       Upon  successful  completion, gd_alter_encoding() returns zero.  On er‐
57       ror, it returns a negative-valued error  code.   Possible  error  codes
58       are:
59
60       GD_E_ACCMODE
61               The specified dirfile was opened read-only.
62
63       GD_E_ALLOC
64               The library was unable to allocate memory.
65
66       GD_E_BAD_DIRFILE
67               The supplied dirfile was invalid.
68
69       GD_E_BAD_INDEX
70               The supplied index was out of range.
71
72       GD_E_IO An I/O error occurred while attempting to recode a binary file.
73
74       GD_E_PROTECTED
75               The  metadata  of  the  given format specification fragment was
76               protected from change, or the binary data of the  fragment  was
77               protected from change and binary file recoding was requested.
78
79       GD_E_UNCLEAN_DB
80               An error occurred while moving the recoded file into place.  As
81               a result, the database may be in an  unclean  state.   See  the
82               NOTES  section  below for recovery instructions.  In this case,
83               the dirfile will be flagged  as  invalid,  to  prevent  further
84               database corruption.  It should be immediately closed.
85
86       GD_E_UNKNOWN_ENCODING
87               The encoding scheme of the fragment is unknown.
88
89       GD_E_UNSUPPORTED
90               The  encoding  scheme  of  the fragment does not support binary
91               file recoding.
92
93       The error code is also stored in the DIRFILE  object  and  may  be  re‐
94       trieved after this function returns by calling gd_error(3).  A descrip‐
95       tive  error  string  for  the  error  may  be   obtained   by   calling
96       gd_error_string(3).
97
98

NOTES

100       A  binary  file  recoding occurs out-of-place.  As a result, sufficient
101       space must be present on the filesystem for the binary files of all RAW
102       fields in the fragment both before and after translation.  If all frag‐
103       ments are updated by specifying GD_ALL_FRAGMENTS, the  recoding  occurs
104       one fragment at a time.
105
106       An  error  code  of  GD_E_UNCLEAN_DB  indicates a system error occurred
107       while moving the re-encoded binary data into place or when deleting the
108       old  data.   If  this  happens,  the database may be left in an unclean
109       state.  The caller should check the filesystem  directly  to  ascertain
110       the state of the dirfile data before continuing.  For recovery instruc‐
111       tions,  see  the  file   /usr/share/doc/getdata/unclean_database_recov‐
112       ery.txt.
113
114

HISTORY

116       The function dirfile_alter_encoding() appeared in GetData-0.5.0.
117
118       In GetData-0.7.0, this function was renamed to gd_alter_encoding().
119
120       in  GetData-0.10.0, the error return from this function changed from -1
121       to a negative-valued error code.
122
123

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

HISTORY

SEE ALSO