gd_alter_frameoffset(3)

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

NAME

14       gd_alter_frameoffset — modify the starting frame of fields in a Dirfile
15
16

SYNOPSIS

18       #include <getdata.h>
19
20       int gd_alter_frameoffset(DIRFILE *dirfile, off_t offset, int
21              fragment_index, int recode);
22
23

DESCRIPTION

25       The gd_alter_frameoffset() function sets the frame offset of the format
26       specification  fragment  given  by  fragment_index  to  offset  in  the
27       dirfile(5) database specified by dirfile.  The frame offset of a  frag‐
28       ment  indicate  the  frame number of the first sample of data stored in
29       binary files associated with RAW fields defined in the specified  frag‐
30       ment.   The  frame offset of a fragment containing no RAW fields is ig‐
31       nored.  The frame offset may not be negative.
32
33       The dirfile argument must point to a valid  DIRFILE  object  previously
34       created by a call to gd_open(3).
35
36       In  addition to being simply a valid fragment index, fragment_index may
37       also be the special value GD_ALL_FRAGMENTS, which  indicates  that  the
38       frame offset of all fragments in the database should be changed.
39
40       If the recode argument is non-zero, this call will shift the binary da‐
41       ta of affected RAW fields to account for the change  in  frame  offset.
42       If  the new frame offset is larger than the old frame offset, this will
43       result in permanent deletion of data from the  database.   If  the  new
44       frame offset is smaller than the old frame offset, the binary file will
45       be padded at the front with zeroes.  The I/O pointer  of  all  affected
46       RAW fields is reset to the beginning-of-frame.
47
48       If recode is zero, affected binary files are left untouched.
49
50

RETURN VALUE

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

NOTES

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

HISTORY

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

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

HISTORY

SEE ALSO