GETFILES(3)

📦 version 2022.10.16, in opensuse-leap 16.0

💅 GETFILES(3) — schily's library functions, bestie edition 🎀

okay so this is a page from Schily´s LIBRARY FUNCTIONS (yes, with the fancy acute accent, we respect the branding ✨) and it's all about getfiles() and its two glow-up siblings. buckle up, it's actually kind of a vibe.

✨ NAME ✨

getfiles() — literally just gets the next non flag-type argument. that's it. that's the whole job. 💅

🦋 SYNOPSIS 🦋

#include <schily/getargs.h>

int getfiles(pac, pav, fmt)
     int *pac;       /* pointer to arg count */
     char *(*pav)[]; /* pointer to address of arg vector */
     char *fmt;      /* format string */

int getlfiles(pac, pav, props, fmt)
     int *pac;       /* pointer to arg count */
     char *(*pav)[]; /* pointer to address of arg vector */
     struct ga_props *props; /* control properties */
     char *fmt;      /* format string */

int getvfiles(pac, pav, props, vfmt)
     int *pac;       /* pointer to arg count */
     char *(*pav)[]; /* pointer to address of arg vector */
     struct ga_props *props; /* control properties */
     struct ga_flags *vfmt;  /* array of formats and args */

like, look at all those pointers. it's giving pointer-to-pointer-to-array-of-char-pointers. main character energy fr fr 🫶

🌸 DESCRIPTION 🌸

so getfiles() is part of the advanced option parsing interface — it runs with the getargs() and getallrgs() family (yes, getallrgs, that's not a typo, that's the real name, don't come for me 😭). what it does is skip options until a file type argument shows up. it's like a bouncer at the club, but for argv. 🎀

getfiles() returns with a value of +1 (NOTAFLAG) or +2 (FLAGDELIM) whenever a non-flag type argument is encountered. flag-type (option) arguments, along with their values, get straight-up ignored. the filename lives at *pav[0]. and here's the important bit, bestie — the caller must increment *pav and decrement *pac before calling getfiles() again. don't forget, or you'll be stuck in a loop staring at the same filename forever 💀

getlfiles() is similar to getfiles() but it implements an additional ga_props parameter that must be initialized with getarginit() before it is passed. no skipping that step, it's not a suggestion, it's the law ✨

getvfiles() is similar to getlfiles() but uses a structure ga_flags instead of a format string and a variable arg list with pointers. here's the array of structures ga_flags:

struct ga_flags {
   const char  *ga_format; /* Comma separated list for one flag */
   void        *ga_arg;    /* Ptr. to variable to fill for flag */
   getpargfun  ga_funcp;   /* Ptr. for function to call (&/~)   */
};

and this array is terminated by an element with ga_format == NULL. for a ga_format that does not expect a function pointer, ga_funcp is NULL. so don't go leaving garbage in there, the NULL sentinel is iconic and load-bearing 👑

🔥 RETURNS 🔥

okay this is the part where you actually pay attention, bestie.

  • FLAGDELIM 2 — the command line argument "--" stopped flag processing. slay, the double dash did its thing.
  • NOTAFLAG 1 — the argument *pav does not appear to be a flag. so it's a file. periodt.
  • NOARGS 0 — all arguments have been successfully examined. we're done here 💅
  • BADFLAG -1 — a bad flag (option) argument was supplied to the program. the argument *pav contains the offending command line argument. 🙈
  • BADFMT -2 — a bad format descriptor string has been detected. this means an error in the calling program, not a user input data error. so like... it's you. it's your bug. no cap.

⭐ general rules for the return code ⭐

  • > 0 — a file type argument was found 🎉
  • 0 — all arguments have been parsed
  • < 0 — an error occurred or not a file type argument

and listen — flag and file arg processing should be terminated after getting a return code <= 0. like, wrap it up, the party's over, go home 🧚

🌈 SEE ALSO 🌈

the whole friend group, honestly. go read all of them 💜

🍓 NOTES 🍓

initially, *pav must point to the first argument (not the program name) and *pac must not count the program name. and before calling getfiles() again, decrement *pac and increment *pav — otherwise the same name will be pointed to by *pav. bestie. i'm begging you. remember this one. 😭

💀 BUGS 💀

none currently known ✨ (iconic behaviour, honestly)

mail bugs and suggestions to schilytools@mlists.in-berlin.de or open a ticket at https://codeberg.org/schilytools/schilytools/issues.

the mailing list archive may be found at:

https://mlists.in-berlin.de/mailman/listinfo/schilytools-mlists.in-berlin.de

👑 AUTHOR 👑

Joerg Schilling and the schilytools project authors. legends, truly 🫶

quick vibe check reminder: every *pac and *pav in here is load-bearing, so don't get cute with them in your actual code. mwah 💋

okay that's the whole page, ily, go parse some arguments responsibly!! 🌸

— brought to you by the Joerg Schilling era, dated 2022/09/09, from GETFILES(3) in Schily´s library functions. catch you on the next man page, bestie 💖🎀🦋

📦 where this page comes from