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 simultaneously 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 specified 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 returned, 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 modifying 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 always 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 unlimited), 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)