NAME

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

SYNOPSIS

       #include <getdata.h>

       long gd_open_limit(DIRFILE *dirfile, long limit);

DESCRIPTION

       The gd_open_limit() function can be used to limit the number of RAW file descriptors which GetData simul‐
       taneously  holds  open  in  the open dirfile(5) database specified by dirfile.  This function can also be
       used to report the current number of open files, or the current limit.  When limiting is active, to  stay
       below  the  limit,  GetData  will  automatically  close  the  least  recently  accessed RAW fields (as if
       gd_raw_close(3) were called), when needed.

       The default value for the limit is zero, indicating that limiting is disabled.   In  this  case,  GetData
       will  never  automatically  close open RAW fields.  To enable limiting call this function with a positive
       value for limit.  If limited, the minimum limit is two; if this function is passed a  limit  of  one,  it
       will behave as if the value 2 were passed instead.

       When  setting  a limit, this function will immediately close enough RAW fields to remain below the speci‐
       fied limit.

       The argument limit may alternately be one of the following special values:

       GD_OLIMIT_NONE (=0)
               Disable limiting, if it was previously active.

       GD_OLIMIT_CURRENT
               Do nothing other than report the current limit.  This is equivalent to calling this function with
               limit equal to the current limit.

       GD_OLIMIT_COUNT
               Instead of returning the current limit, return the current  number  filed  descriptors  for  this
               dirfile.  The current limit is not changed.

RETURN VALUE

       If  limit  is  GD_OLIMIT_COUNT, then the current number of file descriptors in use by this dirfile is re‐
       turned, or zero if limiting is disabled (i.e. the limit is zero).

       For other values of limit, if successful, this function returns the open field limit, after possibly mod‐
       ifying it.  This limit is never negative.  It will be zero if limiting is disabled.

       If limit is one of the special values GD_OLIMIT_COUNT, GD_OLIMIT_CURRENT, or  GD_OLIMIT_NONE  (=0),  then
       this  function  always  succeeds.   Otherwise,  on error, gd_open_limit() returns a negative-valued error
       code.  Possible error codes are:

       GD_E_ALLOC
               The library was unable to allocate memory.

       GD_E_BAD_DIRFILE
               The supplied dirfile was invalid.

       GD_E_IO An I/O error occurred while trying to write modified data to disk as a result in a  reduction  of
               the open field limit.

       The  error  code is also stored in the DIRFILE object and may be retrieved after this function returns by
       calling  gd_error(3).   A  descriptive  error  string  for  the  error  may  be   obtained   by   calling
       gd_error_string(3).

NOTES

       The  file  descriptors  tracked by this functionality are only those associated with RAW fields which are
       held open across function calls.  During the course of any library call, GetData may temporarily exceed a
       file descriptor limit set with this function without triggering an automatic close.  Some headroom is al‐
       ways a good idea.

       Furthermore, this limit is specific to the specified dirfile.  It is not a global  limit  for  the  whole
       GetData library.  If a process has multiple DIRFILEs open, each of them has its own limit (or is unlimit‐
       ed), even though they all draw from the same limited pool of file descriptors.

       In  some cases, usually when writing to a compressed RAW field, two file descriptors may be held open for
       a single field.

HISTORY

       The gd_open_limit() function appeared in GetData-0.11.0.

SEE ALSO

       gd_error(3), gd_error_string(3), gd_open(3), gd_raw_close(3), getrlimit(3), ulimit(3), dirfile(5)

Version 0.11.0                                   5 October 2017                                 gd_open_limit(3)