GETFILES(3)

💅 GETFILES(3) — getfiles() gets the next non flag-type argument

okay so this is from Schily´s LIBRARY FUNCTIONS and it's genuinely one of those little functions that makes life so much easier, bestie. let's get into it 💖

---

✨ NAME ✨

getfiles() — gets next non flag-type argument. that's it, that's the whole vibe 🎀

---

🌸 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 */

---

🦋 DESCRIPTION 🦋

okay so getfiles() is part of the advanced option parsing interface, and it's literally in the same friend group as the getargs() and getallrgs() family. what it does is lowkey iconic: getfiles() skips options until a file type argument is encountered — like it's scrolling past all the flags in the group chat until it finds the actual message 💅

getfiles() returns, with a value of +1 (NOTAFLAG) or +2 (FLAGDELIM), whenever a non-flag type argument is encountered. and the flag-type (option) arguments? along with their values? completely ignored, not even a read receipt. the filename is at *pav[0]. 🫶

⚠️ heads up bestie: the caller must increment *pav and decrement *pac before calling getfiles() again. do not skip this step, i'm begging 😭

getlfiles() is similar to getfiles() but it implements an additional ga_props parameter that must be initialized with getarginit() before it is passed. no cap, initialize it first ✨

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 (&/~)   */
};

it is terminated by an element with ga_format == NULL. and for a ga_format that does not expect a function pointer, ga_funcp is NULL. mmmhmm, that's the whole structure, she's giving minimal and efficient 💜

---

🔥 RETURNS 🔥

• FLAGDELIM 2 — the command line argument "--" stopped flag processing. the flag era is over, periodt.
• NOTAFLAG 1 — the argument *pav does not appear to be a flag. not a flag, not the vibe, moving on ✨
• NOARGS 0 — all arguments have been successfully examined. you ate that 👑
• 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… not the user's fault, it's yours, sorry bestie 😭

⭐ 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.

🚨 flag and file arg processing should be terminated after getting a return code <= 0. like, stop, the party's over, go home 🙈

---

🌈 SEE ALSO 🌈

getallargs(3), getargerror(3), getargs(3) — go read those too, they're the rest of the friend group 🫶

---

🍓 NOTES 🍓

initially, *pav must point to the first argument (not the program name) and *pac must not count the program name. before calling getfiles() again, decrement *pac and increment *pav, or the same name will be pointed to by *pav. and we do NOT want that, it's giving déjà vu 🌀

---

🧚 BUGS 🧚

None currently known. 💅 flawless, 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. absolute main character energy ⭐

---

and that's a wrap, bestie 🎀 this page was written by Joerg Schilling on 2022/09/09 and it's page GETFILES(3) of the manual — go forth and parse those args, you've got this 💖✨