ef_expand_file(3)

💖 ef_expand_file(3) — Library Functions Manual 💖

okay bestie, listen up, because this page right here is the iconic one — it's ef_expand_file(3) from the Library Functions Manual, and it's about making your filenames do the absolute most. 🦋

---

✨ NAME ✨

ef_expand_file, del_ExpandFile, ef_last_error, ef_list_expansions, new_ExpandFile — these cuties expand filenames that contain ~user / $envvar and wildcard expressions. literally the glow-up your path strings have been waiting for 💅

---

✨ SYNOPSIS ✨

#include <libtecla.h>

ExpandFile *new_ExpandFile(void);

ExpandFile *del_ExpandFile(ExpandFile *ef);

FileExpansion *ef_expand_file(ExpandFile *ef,
                              const char *path,
                              int pathlen);

int ef_list_expansions(FileExpansion *result, FILE *fp,
                       int term_width);

const char *ef_last_error(ExpandFile *ef);

---

✨ DESCRIPTION ✨

okay so ef_expand_file() is part of the tecla library (peep the libtecla(3) man page for the full tea ☕). What it does is take a filename you hand it and go absolutely feral on it:

• it converts ~user/ and ~/ expressions at the start of the filename into the matching home directories 🏠
• it swaps $envvar out for the value of the matching environment variable
• and then, if there are any wildcards in there, it matches them against the filenames that actually exist on disk 🔥

Backslashes in the input filename are interpreted as escaping any special meaning of the characters that follow them. Only backslashes that are themselves preceded by backslashes are preserved in the expanded filename. (yes bestie, that's the whole rule, read it twice 🫶)

When wildcards are in play, the returned list of filenames only includes the names of existing files that actually match the wildcards. If there are no wildcards, you just get the original filename back after the tilde and dollar expressions have been expanded, and the result is not checked against existing files. This mimics the file-globbing behavior of the unix tcsh shell. periodt. 💀

🎀 The Wildcards and What They Mean 🎀

• * — matches any sequence of zero or more characters.
• ? — matches any single character.
• [chars] — matches any single character that appears in chars. If chars contains an expression of the form a-b, then any character between a and b, including a and b, matches. The - character looses its special meaning as a range specifier when it appears at the start of the sequence of characters. The ] character also looses its significance as the terminator of the range expression if it appears immediately after the opening [, at which point it is treated as one of the characters of the range. If you want both - and ] to be part of the range, the - should come first and the ] second. (so specific, so slay ✨)
• [^chars] — the same as [chars] except that it matches any single character that doesn't appear in chars.

🚨 WILD CARD VIBE CHECK 🚨 wildcards never match the initial dot in filenames that start with .. That initial . must be explicitly specified in the filename. This again mimics the globbing behavior of most unix shells, and its rationale is based in the fact that in unix, files with names that start with . are usually hidden configuration files, which are not listed by default by the ls command. iykyk 🙈

---

🌸 The Complete Example 🌸

here's a full lil baby program showing you how to use the file expansion function, no cap:

#include <stdio.h>
#include <libtecla.h>

int main(int argc, char *argv[])
{
  ExpandFile *ef;      /* The expansion resource object */
  char *filename;      /* The filename being expanded */
  FileExpansion *expn; /* The results of the expansion */
  int i;

  ef = new_ExpandFile();
  if(!ef)
    return 1;

  for(arg = *(argv++); arg; arg = *(argv++)) {
    if((expn = ef_expand_file(ef, arg, -1)) == NULL) {
      fprintf(stderr, "Error expanding %s (%s).\n", arg,
                       ef_last_error(ef));
    } else {
      printf("%s matches the following files:\n", arg);
      for(i=0; i<expn->nfile; i++)
        printf(" %s\n", expn->files[i]);
    }
  }

  ef = del_ExpandFile(ef);
  return 0;
}

Descriptions of the functions used above are as follows, bestie 👇

💜 ExpandFile *new_ExpandFile(void)

This function creates the resources used by the ef_expand_file() function. In particular, it maintains the memory that is used to record the array of matching filenames that is returned by ef_expand_file(). This array is expanded as needed, so there is no built in limit to the number of files that can be matched. she grows, she adapts, she's flexible 💅

💜 ExpandFile *del_ExpandFile(ExpandFile *ef)

This function deletes the resources that were returned by a previous call to new_ExpandFile(). It always returns NULL (ie a deleted object). It does nothing if the ef argument is NULL. no drama, no leaks, just a clean exit 🎀

💜 A container of the following type is returned by ef_expand_file()

typedef struct {
  int exists;   /* True if the files in files[] exist */
  int nfile;    /* The number of files in files[] */
  char **files; /* An array of 'nfile' filenames. */
} FileExpansion;

💜 FileExpansion *ef_expand_file(ExpandFile *ef, const char *path, int pathlen)

The ef_expand_file() function performs filename expansion, as documented at the start of this section. Its first argument is a resource object returned by new_ExpandFile(). A pointer to the start of the filename to be matched is passed via the path argument. This must be a normal NUL terminated string, but unless a length of -1 is passed in pathlen, only the first pathlen characters will be used in the filename expansion. If the length is specified as -1, the whole of the string will be expanded. 🫶

The function returns a pointer to a container whose contents are the results of the expansion. If there were no wildcards in the filename, the nfile member will be 1, and the exists member should be queried if it is important to know if the expanded file currently exists or not. If there were wildcards, then the contained files[] array will contain the names of the nfile existing files that matched the wildcarded filename, and the exists member will have the value 1.

😭 IMPORTANT BESTIE MOMENT: the returned container belongs to the specified ef object, and its contents will change on each call. So if you need to retain the results of more than one call to ef_expand_file(), you should either make a private copy of the returned results, or create multiple file-expansion resource objects via multiple calls to new_ExpandFile(). do not get caught slipping on this one 🙈

On error, NULL is returned, and an explanation of the error can be determined by calling ef_last_error(ef).

💜 const char *ef_last_error(ExpandFile *ef)

This function returns the message which describes the error that occurred on the last call to ef_expand_file(), for the given (ExpandFile *ef) resource object. she's the friend who tells you exactly what went wrong 💀

💜 int ef_list_expansions(FileExpansion *result, FILE *fp, int terminal_width)

The ef_list_expansions() function provides a convenient way to list the filename expansions returned by ef_expand_file(). Like the unix ls command, it arranges the filenames into equal width columns, each column having the width of the largest file. The number of columns used is thus determined by the length of the longest filename, and the specified terminal width.

🚨 Beware that filenames that are longer than the specified terminal width are printed without being truncated, so output longer than the specified terminal width can occur. she does not shrink herself for anybody 💅

The list is written to the stdio stream specified by the fp argument.

---

✨ THREAD SAFETY ✨

In multi-threaded programs, you should use the libtecla_r.a version of the library. This uses POSIX reentrant functions where available (hence the _r suffix), and disables features that rely on non-reentrant system functions. Currently there are no features disabled in this module. ✨

Using the libtecla_r.a version of the library, it is safe to use the facilities of this module in multiple threads, provided that each thread uses a separately allocated ExpandFile object. In other words, if two threads want to do file expansion, they should each call new_ExpandFile() to allocate their own file-expansion objects. share the vibes, not the object 🫶

---

✨ FILES ✨

• libtecla.a — the tecla library
• libtecla.h — the tecla header file.

---

✨ SEE ALSO ✨

libtecla(3), gl_get_line(3), cpl_complete_word(3), pca_lookup_file(3)

---

✨ AUTHOR ✨

Martin Shepherd (mcs@astro.caltech.edu) — thank you for your service king 👑

---

okay that's the whole page bestie, you're officially a filename-expansion main character now 👑💖 and just so we're clear, this was ef_expand_file(3) from the Library Functions Manual, so if anyone asks where you learned all this, you point them right here. slay, bye 🦋✨