gd_close(3)

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

NAME

14       gd_close, gd_discard — close a Dirfile and free associated memory
15
16

SYNOPSIS

18       #include <getdata.h>
19
20       int gd_close(DIRFILE *dirfile);
21
22       int gd_discard(DIRFILE *dirfile);
23
24

DESCRIPTION

26       The  gd_close()  and  gd_discard()  attempt  to  close the open Dirfile
27       dirfile and free all memory associated with it.
28
29       The gd_close() function first flushes all pending metadata  updates  to
30       disk.   This  step  is  skipped  by gd_discard(), which simply discards
31       metadata changes.  For dirfiles opened read-only, these  two  functions
32       are equivalent.
33
34       Next,  all  pending  data  is  flushed  to disk and all open data files
35       closed.  In order to ensure that modified data  files  associated  with
36       RAW fields are properly terminated, changes to RAW data files are still
37       flushed to disk by gd_discard().
38
39       Finally, if the above didn't encounter an error, these  functions  free
40       memory associated with the DIRFILE object.
41
42       If dirfile is NULL, nothing happens, and the call succeeds.
43
44       One  of  these  functions  should be called on all pointers returned by
45       gd_cbopen(3), gd_open(3), and gd_invalid_dirfile(3), even if  the  call
46       to  those  function  failed.   After gd_close() or gd_discard() returns
47       successfully, the pointer dirfile should be considered invalid.
48
49       Metadata is written to disk using  the  current  Standards  Version  as
50       stored in the dirfile object.  See gd_dirfile_standards(3) to change or
51       report the current Standards Version.  If the dirfile metadata conforms
52       to no known Standards Version, Standards non-compliant metadata will be
53       written.
54
55

RETURN VALUE

57       gd_close() and gd_discard() return zero on success.  On error, they  do
58       not  de-allocate  dirfile  and  instead  return a negative-valued error
59       code.  Possible error codes are:
60
61       GD_E_ALLOC
62               The library was unable to allocate memory.
63
64       GD_E_LINE_TOO_LONG
65               While attempting to flush modified metadata to  disk,  a  field
66               specification  line  exceeded  the  maximum allowed length.  On
67               most platforms, the maximum length is at least 2**31 bytes,  so
68               this typically indicates something pathological happening.
69
70       GD_E_IO An  I/O  error  occurred while trying to write modified data or
71               metadata to disk.  In this case, another call to gd_close()  or
72               gd_discard() may be attempted.
73
74       The  error  code  is  also  stored in the DIRFILE object and may be re‐
75       trieved after this function returns by calling gd_error(3).  A descrip‐
76       tive   error   string   for  the  error  may  be  obtained  by  calling
77       gd_error_string(3).
78
79

HISTORY

81       The function dirfile_close() appeared in GetData-0.3.0.
82
83       The function dirfile_discard() appeared in GetData-0.6.0.
84
85       In  GetData-0.7.0  these  functions  were  renamed  to  gd_close()  and
86       gd_discard().
87
88       In  GetData-0.10.0,  the error return from these functions changed from
89       -1 to a negative-valued error code.
90
91

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

HISTORY

SEE ALSO