gd_open_limit(3)

💖 gd_open_limit — bestie edition 💖

okay so this is gd_open_limit(3), from the GETDATA manual. it's the function that sets how many files a Dirfile is allowed to keep open at once. slay. let's get into it 🫶

✨ 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 ✨

so, gd_open_limit() does three-ish jobs and honestly it's giving multitasking queen 👑. you can use it to cap the number of RAW file descriptors that GetData holds open at the same time in the open dirfile(5) database you pass in as dirfile. you can also use it to report the current number of open files, or to report the current limit. pick your fighter.

when limiting is actually active, GetData will stay under the limit by automatically closing the least recently accessed RAW fields (basically as if gd_raw_close(3) got called), whenever it needs to. no cap, it really does this on its own ✨

the default value for the limit is zero, which means limiting is disabled. in that case GetData will never automatically close open RAW fields. to turn limiting on, call this function with a positive value for limit.

if limiting is on, the minimum limit is two. so if you pass in a limit of one, it's just gonna act like you passed 2 instead. it said no to your little joke 💅

when you set a limit, this function will immediately close enough RAW fields to stay below the limit you specified. instant. periodt.

the limit argument can alternately be one of these 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 ✨

okay so if limit is GD_OLIMIT_COUNT, then what you get back is the current number of file descriptors in use by this dirfile, or zero if limiting is disabled (i.e. the limit is zero). 🧚

for any other value of limit, if it works, this function returns the open field limit, after possibly modifying it. this limit is never negative. it'll 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. lowkey important ngl 🙈
• 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. every girl for herself 💅
• in some cases, usually when writing to a compressed RAW field, two file descriptors may be held open for a single field. iconic behavior honestly.

✨ 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)

and that's the whole page bestie 🎀 this was Version 0.11.0, dated 5 October 2017. go forth and limit your file descriptors responsibly, mwah 💖🌈