dirfile_uninclude(3)

1dirfile_uninclude(3)                GETDATA               dirfile_uninclude(3)
2
3
4

NAME

6       dirfile_uninclude — remove a format file fragment from a dirfile
7

SYNOPSIS

9       #include <getdata.h>
10
11       int *dirfile_uninclude(DIRFILE *dirfile, int fragment_index, int del);
12

DESCRIPTION

14       The  dirfile_uninclude()  removes  the  format file fragment indexed by
15       fragment_index from the specified dirfile, as well as any fragments the
16       specified  fragment  INCLUDEs.  Fields defined in the removed fragments
17       will be removed from the dirfile.
18
19       Before removing the specified fragment, all pending writes are  flushed
20       to RAW fields defined the the removed fragments.  If del is zero, meta‐
21       data changes will also be written to the removed fragments.  If del  is
22       non-zero,  the format file fragments will be deleted from disk, if pos‐
23       sible.  Regardless of the value of del, binary  data  files  associated
24       with  RAW  fields defined in the removed fragments will not be deleted.
25       To delete these binary files, use dirfile_delete(3) before calling this
26       function.
27
28       The  primary  format  file (the fragment indexed by zero) cannot be re‐
29       moved from the dirfile.
30

RETURN VALUE

32       On success, dirfile_uninclude() returns zero.  On error, -1 is returned
33       and the dirfile error is set to a non-zero error value.  Possible error
34       values are:
35
36       GD_E_ACCMODE
37               The supplied dirfile was opened in read-only mode.
38
39       GD_E_ALLOC
40               The library was unable to allocate memory.
41
42       GD_E_BAD_DIRFILE
43               The supplied dirfile was invalid.
44
45       GD_E_BAD_INDEX
46               The supplied fragment index was out of range, or an attempt was
47               made to remove the primary format file.
48
49       GD_E_OPEN_INCLUDE
50               A  temporary  file  could not be opened into which to write the
51               metadata of a modified, removed fragment.
52
53       GD_E_PROTECTED
54               The metadata of the fragment which included the  removed  frag‐
55               ment was protected from change.
56
57       GD_E_RAW_IO
58               An  error  occurred  while  trying  to flush or close a removed
59               field.
60
61       The dirfile error may be retrieved by calling get_error(3).  A descrip‐
62       tive error string for the last error encountered can be obtained from a
63       call to get_error_string(3).  When finished with it, the DIRFILE object
64       may  be  deallocated  with a call to dirfile_close(3), even if the open
65       failed.
66

NOTES

68       This function re-arranges the remaining format file fragments  in  some
69       unspecified  way,  except for the primary fragment, which is guaranteed
70       to remain at index zero.  Callers which cache format file fragment  in‐
71       dices must re-initialise their cache after calling this function.
72
73       Unlike dirfile_delete(3), fields which depend on fields removed by this
74       function are not automatically updated, nor is any check made to ensure
75       that  this  function  does  not leave fields with missing input fields.
76       Because of this, a fragment inclusion may  be  easily  moved  from  one
77       fragment  to  another  with  a  combination  of dirfile_uninclude() and
78       dirfile_include(3).   However,  if  such  checks  are   required,   use
79       dirfile_delete(3) to delete the fields defined in the removed fragments
80       first.
81

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

SEE ALSO