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

NAME

14       gd_open_limit — set a Dirfile's allowed number of open files
15
16

SYNOPSIS

18       #include <getdata.h>
19
20       long gd_open_limit(DIRFILE *dirfile, long limit);
21
22

DESCRIPTION

24       The  gd_open_limit()  function  can  be used to limit the number of RAW
25       file descriptors which GetData simultaneously holds open  in  the  open
26       dirfile(5)  database  specified  by dirfile.  This function can also be
27       used to report the current number of open files, or the current  limit.
28       When limiting is active, to stay below the limit, GetData will automat‐
29       ically  close  the  least  recently  accessed   RAW   fields   (as   if
30       gd_raw_close(3) were called), when needed.
31
32       The  default  value  for the limit is zero, indicating that limiting is
33       disabled.  In this case, GetData will never  automatically  close  open
34       RAW fields.  To enable limiting call this function with a positive val‐
35       ue for limit.  If limited, the minimum limit is two; if  this  function
36       is  passed a limit of one, it will behave as if the value 2 were passed
37       instead.
38
39       When setting a limit, this function will immediately close  enough  RAW
40       fields to remain below the specified limit.
41
42       The argument limit may alternately be one of the following special val‐
43       ues:
44
45       GD_OLIMIT_NONE (=0)
46               Disable limiting, if it was previously active.
47
48       GD_OLIMIT_CURRENT
49               Do nothing other than report the current limit.  This is equiv‐
50               alent  to calling this function with limit equal to the current
51               limit.
52
53       GD_OLIMIT_COUNT
54               Instead of returning the current limit, return the current num‐
55               ber  filed  descriptors for this dirfile.  The current limit is
56               not changed.
57
58

RETURN VALUE

60       If limit is GD_OLIMIT_COUNT, then the current number of  file  descrip‐
61       tors  in  use  by this dirfile is returned, or zero if limiting is dis‐
62       abled (i.e. the limit is zero).
63
64       For other values of limit, if successful,  this  function  returns  the
65       open  field  limit,  after  possibly modifying it.  This limit is never
66       negative.  It will be zero if limiting is disabled.
67
68       If limit is one of the special values  GD_OLIMIT_COUNT,  GD_OLIMIT_CUR‐
69       RENT, or GD_OLIMIT_NONE (=0), then this function always succeeds.  Oth‐
70       erwise, on error, gd_open_limit() returns a negative-valued error code.
71       Possible error codes are:
72
73       GD_E_ALLOC
74               The library was unable to allocate memory.
75
76       GD_E_BAD_DIRFILE
77               The supplied dirfile was invalid.
78
79       GD_E_IO An  I/O  error  occurred while trying to write modified data to
80               disk as a result in a reduction of the open field limit.
81
82       The error code is also stored in the DIRFILE  object  and  may  be  re‐
83       trieved after this function returns by calling gd_error(3).  A descrip‐
84       tive  error  string  for  the  error  may  be   obtained   by   calling
85       gd_error_string(3).
86
87
88

NOTES

90       The file descriptors tracked by this functionality are only those asso‐
91       ciated with RAW fields which are held open across function calls.  Dur‐
92       ing  the  course  of any library call, GetData may temporarily exceed a
93       file descriptor limit set with this function without triggering an  au‐
94       tomatic close.  Some headroom is always a good idea.
95
96       Furthermore,  this  limit  is specific to the specified dirfile.  It is
97       not a global limit for the whole GetData library.   If  a  process  has
98       multiple  DIRFILEs open, each of them has its own limit (or is unlimit‐
99       ed), even though they all draw from the same limited pool of  file  de‐
100       scriptors.
101
102       In some cases, usually when writing to a compressed RAW field, two file
103       descriptors may be held open for a single field.
104
105

HISTORY

107       The gd_open_limit() function appeared in GetData-0.11.0.
108
109

SEE ALSO

111       gd_error(3),    gd_error_string(3),    gd_open(3),     gd_raw_close(3),
112       getrlimit(3), ulimit(3), dirfile(5)
113
114
115
116Version 0.11.0                  5 October 2017                gd_open_limit(3)
Impressum