Wednesday, November 18, 2026
HomeC Programmingls, dir and tree Examples

ls, dir and tree Examples


Customary C has no perform for itemizing a listing. The C library can open, learn and write information, but it surely has no idea of a folder; stdio.h can not let you know what a listing accommodates. To checklist one you want the working system’s API: POSIX opendir() and readdir() on Linux and macOS, or FindFirstFileW() and FindNextFileW() on Home windows.

This information begins with the shortest working code for every system. It then builds one small transportable layer on high of each and makes use of it for 3 actual instruments: a dir/ls-style itemizing, a tree view that prints a listing’s construction, and a finder that exhibits which information are filling a disk. Alongside the best way it covers the errors that make listing code fail in follow: calling stat() on the fallacious path, following symbolic hyperlinks into an infinite loop, recursing into . and .., and overflowing a fixed-size path buffer. Each program was compiled and examined with GCC and Clang on Ubuntu and with MSVC on Home windows.

Methods to Checklist Recordsdata in a Listing in C

On Linux and macOS, open the listing with opendir(), name readdir() till it returns NULL, and shut it with closedir(). These capabilities are declared in <dirent.h> and outlined by POSIX:

/* The shortest appropriate method to checklist a listing on Linux or macOS. */
#outline _POSIX_C_SOURCE 200809L
#embody <dirent.h>
#embody <stdio.h>

int essential(int argc, char **argv)
{
    const char *path = argc > 1 ? argv[1] : ".";
    DIR *dir = opendir(path);
    if (dir == NULL) {
        perror(path);
        return 1;
    }
    struct dirent *entry;
    whereas ((entry = readdir(dir)) != NULL)
        printf("%sn", entry->d_name);       /* contains "." and "..", in no specific order */
    closedir(dir);
    return 0;
}

Output:

café.txt
src
.
empty.txt
.secret
notes.txt
..
docs

On Home windows, name FindFirstFileW() with a search sample similar to .*, then FindNextFileW() till it fails, and shut the deal with with FindClose():

/* The shortest appropriate method to checklist a listing on Home windows. */
#outline WIN32_LEAN_AND_MEAN
#embody <home windows.h>
#embody <stdio.h>

int essential(void)
{
    WIN32_FIND_DATAW information;
    HANDLE discover = FindFirstFileW(L".*", &information);    /* the sample, not the listing */
    if (discover == INVALID_HANDLE_VALUE) {
        fprintf(stderr, "FindFirstFileW failed: error %lun", (unsigned lengthy)GetLastError());
        return 1;
    }
    do {
        wprintf(L"%lsn", information.cFileName);          /* contains "." and ".." */
    } whereas (FindNextFileW(discover, &information));
    FindClose(discover);
    return 0;
}

Each variations present three issues that shock individuals the primary time:

  • The entries . and .. are included. They’re the listing itself and its mother or father. Skip them earlier than doing anything, or a recursive stroll descends into them perpetually.
  • The order shouldn’t be sorted. readdir() returns entries in no matter order the file system shops them; café.txt got here first above solely by likelihood. Kind the names your self if order issues.
  • You get names, not paths. readdir() returns notes.txt, not fixture/notes.txt. Something that wants the file itself, similar to its dimension, should mix the 2.

POSIX and Home windows listing APIs in contrast

Activity Linux and macOS (POSIX) Home windows
Open a listing opendir(path) FindFirstFileW(L"path*", &information), which additionally returns the primary entry
Subsequent entry readdir(dir) returns a struct dirent * FindNextFileW(deal with, &information)
Shut closedir(dir) FindClose(deal with)
Entry title entry->d_name information.cFileName (UTF-16)
Dimension, time, kind fstatat() or stat() on the entry Already in WIN32_FIND_DATAW: nFileSizeHigh/Low, ftLastWriteTime, dwFileAttributes
Hidden information Conference: the title begins with . The FILE_ATTRIBUTE_HIDDEN attribute
Stroll a complete tree nftw(), or recursion over readdir() Recursion over FindFirstFileW()
Header <dirent.h>, <sys/stat.h> <home windows.h>

C++17 applications can use std::filesystem::directory_iterator and recursive_directory_iterator, which wrap these identical calls behind one interface. In C, you write that wrapper your self, which is what the remainder of this text does.

A Moveable Listing Layer

The applications under mustn’t care which system they run on, so one header describes a listing entry in the identical phrases in all places, and two supply information implement it:

#ifndef FS_H
#outline FS_H

/* A small transportable layer over listing itemizing: POSIX opendir/readdir/fstatat
   on Linux and macOS, FindFirstFileW/FindNextFileW on Home windows. Names are UTF-8
   on each platform, and "." and ".." are by no means returned. */

#embody <stdbool.h>
#embody <stddef.h>

typedef enum { FS_FILE, FS_DIR, FS_LINK, FS_OTHER } fs_kind;

#outline FS_NAME_MAX 1024     /* bytes of UTF-8, together with the terminating '' */
#outline FS_PATH_MAX 4096

typedef struct {
    char title[FS_NAME_MAX];
    fs_kind type;            /* a symbolic hyperlink is reported as a hyperlink, by no means adopted */
    lengthy lengthy dimension;          /* bytes; 0 for directories */
    lengthy lengthy mtime;         /* final modification, seconds since 1970-01-01 UTC */
    bool hidden;             /* title begins with '.', or (Home windows) the hidden attribute */
} fs_entry;

typedef struct fs_dir fs_dir;

/* Opens a listing for studying. On failure returns NULL and writes a
   purpose ("no such listing", "permission denied", ...) to err. */
fs_dir *fs_opendir(const char *path, char *err, size_t err_len);

/* Reads the following entry: returns 1 and fills *e, 0 on the finish, -1 on error. */
int fs_readdir(fs_dir *d, fs_entry *e);

void fs_closedir(fs_dir *d);

/* Reads a complete listing into a brand new array sorted with directories first,
   then by title (byte order). Returns false on error; free(*out) when carried out. */
bool fs_list(const char *path, fs_entry **out, size_t *rely, char *err, size_t err_len);

/* Builds "dir/title" into buf. Returns false, leaving buf unchanged, if the
   end result wouldn't match: a path isn't silently reduce brief. */
bool fs_join(char *buf, size_t cap, const char *dir, const char *title);

/* Free house on the quantity holding path, for the present person. */
bool fs_free_space(const char *path, unsigned lengthy lengthy *bytes);

/* Codecs a time as "YYYY-MM-DD HH:MM", in UTC or native time. */
void fs_format_time(lengthy lengthy t, bool utc, char *buf, size_t cap);

/* Creates a file of the given dimension and modification time, or a listing
   (dimension < 0), with a UTF-8 path. Utilized by the take a look at fixture and the demos. */
bool fs_make(const char *path, lengthy lengthy dimension, lengthy lengthy mtime);

/* Home windows: switches the console to UTF-8 so names similar to "café.txt" show
   appropriately. Does nothing on different methods, the place terminals already use UTF-8. */
void fs_console_utf8(void);

#endif

Every entry is a construction holding the title and the details a list wants: its type, dimension, modification time and whether or not it’s hidden. Two design selections matter:

  • Names are all the time UTF-8. Linux file names are already bytes, often UTF-8. Home windows names are UTF-16, so the Home windows code converts them. That retains strcmp, printf and the remainder of this system the identical on each methods.
  • Symbolic hyperlinks are reported, by no means adopted. A hyperlink is listed as FS_LINK, so a walker can’t be led in a circle.

The POSIX implementation

int fs_readdir(fs_dir *d, fs_entry *e)
{
    for (;;) 
}

The necessary name is fstatat(dirfd(d->dir), de->d_name, &st, AT_SYMLINK_NOFOLLOW). It seems the title up contained in the listing being learn, by way of the open listing’s file descriptor, so it really works no matter this system’s present listing is. AT_SYMLINK_NOFOLLOW makes it describe a symbolic hyperlink itself somewhat than what the hyperlink factors to. With out each, the code has the 2 commonest directory-listing bugs, proven within the frequent errors part.

readdir() additionally has a d_type area that always offers the entry kind with no stat() name. It isn’t a part of POSIX, and on some file methods it’s all the time DT_UNKNOWN, so code that depends on it alone breaks on these methods. Calling fstatat() is all the time appropriate and in addition offers the dimensions and time.

The Home windows implementation

int fs_readdir(fs_dir *d, fs_entry *e)
{
    for (;;)  wcscmp(f->cFileName, L"..") == 0)
            proceed;
        if (!to_utf8(f->cFileName, e->title, (int)sizeof e->title))
            proceed;
        DWORD a = f->dwFileAttributes;
        if ((a & FILE_ATTRIBUTE_REPARSE_POINT) && f->dwReserved0 == IO_REPARSE_TAG_SYMLINK)
            e->type = FS_LINK;
        else if (a & FILE_ATTRIBUTE_DIRECTORY)
            e->type = FS_DIR;
        else
            e->type = FS_FILE;
        e->dimension = e->type == FS_DIR ? 0 : (lengthy lengthy)(((ULONGLONG)f->nFileSizeHigh << 32) 
}

Home windows returns the dimensions, time and attributes with every title, so no second name is required. Two conversions do the work:

  • Names: WideCharToMultiByte(CP_UTF8, ...) converts the UTF-16 title to UTF-8. The older FindFirstFileA() returns names within the system’s ANSI code web page as a substitute, which can not signify each character, so names in different alphabets come again with ? rather than the characters that don’t match.
  • Console output: changing to UTF-8 is simply half the job. The Home windows console nonetheless decodes program output with its personal code web page, often an previous OEM one similar to 437, so fs_console_utf8() calls SetConsoleOutputCP(CP_UTF8) initially of every program. Mistake 7 under exhibits what occurs with out it.
  • Occasions: a FILETIME counts 100-nanosecond ticks since January 1, 1601. Subtracting 116,444,736,000,000,000 ticks and dividing by 10,000,000 offers seconds since 1970, the identical scale as POSIX st_mtime:
static lengthy lengthy from_filetime(FILETIME ft)
{
    ULARGE_INTEGER v;
    v.LowPart = ft.dwLowDateTime;
    v.HighPart = ft.dwHighDateTime;
    return (lengthy lengthy)((v.QuadPart - 116444736000000000ULL) / 10000000ULL);
}

The remainder of the layer, in fs_common.c, is shared. fs_list() reads a complete listing into an array and kinds it with directories first, then by title. fs_join() builds dir/title and refuses, somewhat than truncates, a path that doesn’t match. Ahead slashes work as path separators on Home windows too, so the identical code builds paths on each methods.

Itemizing a Listing: dirlist

dirlist is a small ls -l or dir. It exhibits every entry’s modification time, kind and dimension, sorted with directories first, and a abstract line:

/* dirlist: lists one listing, like "ls -l" on Linux or "dir" on Home windows.

   utilization: dirlist [-a] [-d | -f] [-u] [-s] [DIRECTORY]
     -a  embody hidden entries      -d  directories solely     -f  information solely
     -u  present occasions in UTC           -s  present free house on the quantity
   Exit standing: 0 on success, 2 if the listing can't be learn. */
#embody "fs.h"
#embody "stroll.h"

#embody <stdio.h>
#embody <stdlib.h>
#embody <string.h>

int essential(int argc, char **argv)
{
    fs_console_utf8();
    bool all = false, dirs_only = false, files_only = false, utc = false, show_free = false;
    const char *path = ".";
    for (int i = 1; i < argc; i++)  i != argc - 1)  -f] [-u] [-s] [DIRECTORY]n");
            return 2;
         else
            path = argv[i];
    

    fs_entry *checklist;
    size_t n;
    char err[128];
    if (!fs_list(path, &checklist, &n, err, sizeof err)) {
        fprintf(stderr, "dirlist: %s: %sn", path, err);
        return 2;
    }

    printf("Listing: %snn%-16s  %-5s  %13s  %sn", path, utc ? "Modified (UTC)" : "Modified", "Kind", "Dimension", "Title");
    size_t information = 0, dirs = 0, skipped = 0;
    lengthy lengthy bytes = 0;
    for (size_t i = 0; i < n; i++) {
        const fs_entry *e = &checklist[i];
        bool is_dir = e->type == FS_DIR;
        if ((e->hidden && !all) || (dirs_only && !is_dir) || (files_only && is_dir)) {
            skipped++;
            proceed;
        }
        char when[32], dimension[32];
        fs_format_time(e->mtime, utc, when, sizeof when);
        if (is_dir)
            dimension[0] = '';
        else
            with_commas(e->dimension, dimension, sizeof dimension);
        const char *kind = is_dir ? "<DIR>" : e->type == FS_LINK ? "<LNK>" : e->type == FS_OTHER ? "<OTH>" : "";
        printf("%-16s  %-5s  %13s  %sn", when, kind, dimension, e->title);
        if (is_dir)
            dirs++;
        else {
            information++;
            bytes += e->dimension;
        }
    }
    char whole[32];
    with_commas(bytes, whole, sizeof whole);
    printf("npercentzu directorpercents, %zu filepercents, %s bytes", dirs, dirs == 1 ? "y" : "ies", information, information == 1 ? "" : "s", whole);
    if (skipped)
        printf(" (%zu not proven)", skipped);
    putchar('n');
    if (show_free) {
        unsigned lengthy lengthy free_bytes;
        if (fs_free_space(path, &free_bytes)) {
            with_commas((lengthy lengthy)free_bytes, whole, sizeof whole);
            printf("%s bytes freen", whole);
        }
    }
    free(checklist);
    return 0;
}

The examples on this article checklist a small take a look at folder that make_fixture creates with fastened sizes and dates, so the output is identical on each machine. The -u choice prints occasions in UTC for a similar purpose; with out it, dirlist makes use of native time.

Output:

Listing: fixture

Modified (UTC)    Kind            Dimension  Title
2023-11-14 22:13  <DIR>                 docs
2023-11-14 22:13  <DIR>                 src
2024-06-01 12:00                     7  café.txt
2023-11-14 22:13                     0  empty.txt
2024-06-01 12:00                    10  notes.txt

2 directories, 3 information, 17 bytes (1 not proven)

The hidden file .secret is counted however not proven. -a contains it:

Output:

Listing: fixture

Modified (UTC)    Kind            Dimension  Title
2023-11-14 22:13  <DIR>                 docs
2023-11-14 22:13  <DIR>                 src
2023-11-14 22:13                    42  .secret
2024-06-01 12:00                     7  café.txt
2023-11-14 22:13                     0  empty.txt
2024-06-01 12:00                    10  notes.txt

2 directories, 4 information, 59 bytes

-d exhibits solely directories and -f solely information:

Output:

Listing: fixture/docs

Modified (UTC)    Kind            Dimension  Title
2023-11-14 22:13                 1,234  information.md

0 directories, 1 file, 1,234 bytes (1 not proven)

The identical itemizing from the Home windows construct, run on Home windows 11 with -a -u -s (-s provides the free house on the drive, which naturally differs from machine to machine):

Listing: dirlist-fixture

Modified (UTC)    Kind            Dimension  Title
2023-11-14 22:13  <DIR>                 docs
2023-11-14 22:13  <DIR>                 src
2023-11-14 22:13                    42  .secret
2024-06-01 12:00                     7  café.txt
2023-11-14 22:13                     0  empty.txt
2024-06-01 12:00                    10  notes.txt

2 directories, 4 information, 59 bytes
24,406,134,784 bytes free

The entries, sizes and occasions match the Linux output line for line, together with the UTF-8 title, although the 2 methods learn them by way of utterly completely different APIs.

Just a few particulars in dirlist.c are value copying into your individual code:

  • Listing sizes are left clean. On Linux stat() experiences a listing’s personal dimension, often 4,096 bytes for the checklist of names, not the dimensions of its contents. Printing it confuses readers, so the layer experiences 0 and the itemizing exhibits nothing.
  • Sizes have hundreds separators from a small perform, with_commas(), somewhat than the ' flag of printf, which is a POSIX extension and is dependent upon the locale.
  • The exit standing is 2 when the listing can’t be learn, with the rationale (“no such listing”, “permission denied”) on customary error, so scripts can inform failure aside from an empty listing.

Printing the Listing Construction as a Tree

The tree command exhibits a folder and the whole lot under it, indented by depth. This one reads the entire tree into reminiscence first, which makes it straightforward to kind every stage and so as to add up the dimensions of each listing earlier than printing it:

static bool read_dir(char *path, size_t len, int depth_left, bool with_hidden, node *dir)
{
    fs_entry *checklist;
    size_t n;
    char err[128];
    if (!fs_list(path, &checklist, &n, err, sizeof err)) {
        if (strcmp(err, "out of reminiscence") == 0)
            return false;
        dir->error = strstr(err, "no such") ? "no such listing"
                   : strstr(err, "not a listing") ? "not a listing"
                   : strstr(err, "permission") ? "permission denied" : "can't be learn";
        return true;
    }
    dir->kids = calloc(n ? n : 1, sizeof *dir->kids);
    if (dir->kids == NULL) {
        free(checklist);
        return false;
    }
    bool okay = true;
    for (size_t i = 0; i < n && okay; i++) {
        if (checklist[i].hidden && !with_hidden)
            proceed;
        node *c = &dir->kids[dir->count];
        c->title = copy(checklist[i].title);
        if (c->title == NULL) {
            okay = false;
            break;
        }
        dir->rely++;
        c->type = checklist[i].type;
        c->hidden = checklist[i].hidden;
        c->dimension = checklist[i].dimension;
        c->mtime = checklist[i].mtime;
        if (c->type == FS_DIR && depth_left != 0) {
            if (!fs_join(path, FS_PATH_MAX, path, c->title)) {
                c->error = "path too lengthy";
                proceed;
            }
            okay = read_dir(path, strlen(path), depth_left - 1, with_hidden, c);
            path[len] = '';            /* again to this listing's path */
        }
        dir->dimension += c->dimension;
    }
    free(checklist);
    return okay;
}

read_dir() is recursive: for every subdirectory it appends the title to the trail, calls itself, after which cuts the trail again to the place it was. The entire stroll makes use of a single path buffer as a substitute of allocating a brand new string at each stage. As a result of the layer by no means follows symbolic hyperlinks and by no means returns . or .., the recursion all the time ends.

The printing is a second, easier recursion that passes down a prefix string of | and segments:

static void print_children(const node *dir, char *prefix, size_t plen, int ranges, bool sizes, struct totals *t)
{
    for (size_t i = 0; i < dir->rely; i++) {
        const node *c = &dir->kids[i];
        bool final = i + 1 == dir->rely;
        printf("%spercents", prefix, final ? "`-- " : "|-- ");
        if (sizes) {
            char s[32];
            with_commas(c->dimension, s, sizeof s);
            printf("[%9s]  ", s);
        }
        printf("%spercents", c->title, c->type == FS_DIR ? "/" : "");
        if (c->type == FS_LINK)
            printf("  (hyperlink, not adopted)");
        if (c->error)
            printf("  [%s]", c->error);
        putchar('n');

        if (c->type == FS_DIR) {
            t->dirs++;
            if (ranges != 1 && plen + 5 < FS_PATH_MAX)    ");
                print_children(c, prefix, plen + 4, ranges - 1, sizes, t);
                prefix[plen] = '';
            
        } else
            t->information++;
    }
}

Output:

fixture
|-- docs/
|   |-- photos/
|   |   `-- emblem.png
|   `-- information.md
|-- src/
|   |-- essential.c
|   `-- util.c
|-- café.txt
|-- empty.txt
`-- notes.txt

3 directories, 7 information

With -s, each entry exhibits its dimension, and each listing exhibits the whole of the whole lot inside it. docs is 6,234 bytes as a result of it holds information.md (1,234) and photos (5,000):

Output:

[    6,713]  fixture
|-- [    6,234]  docs/
|   |-- [    5,000]  photos/
|   |   `-- [    5,000]  emblem.png
|   `-- [    1,234]  information.md
|-- [      420]  src/
|   |-- [      300]  essential.c
|   `-- [      120]  util.c
|-- [       42]  .secret
|-- [        7]  café.txt
|-- [        0]  empty.txt
`-- [       10]  notes.txt

3 directories, 8 information

-L 1 limits the output to the primary stage. With -s as effectively, the entire tree continues to be learn, so the listing totals keep appropriate:

Output:

[    6,671]  fixture
|-- [    6,234]  docs/
|-- [      420]  src/
|-- [        7]  café.txt
|-- [        0]  empty.txt
`-- [       10]  notes.txt

2 directories, 3 information

Studying the tree into reminiscence prices reminiscence in proportion to the variety of entries. For a disk with hundreds of thousands of information, a streaming stroll that prints because it goes and retains solely the present path is the higher design; nftw() on POSIX works that manner.

Actual-World Instance: What Is Filling the Disk?

When a server’s disk fills up, the primary query is which information are largest. bigfiles walks the tree, collects each common file with its path, and kinds by dimension:

static bool gather(const node *n, char *rel, size_t len, struct checklist *out)
{
    for (size_t i = 0; i < n->rely; i++) {
        const node *c = &n->kids[i];
        char *path = rel;
        if (!fs_join(path, FS_PATH_MAX, len ? rel : "", c->title))
            proceed;
        if (c->type == FS_DIR) {
            if (!gather(c, path, strlen(path), out))
                return false;
        } else if (c->type == FS_FILE) {
            if (out->rely == out->cap) {
                size_t cap = out->cap ? out->cap * 2 : 64;
                struct discovered *greater = realloc(out->gadgets, cap * sizeof *greater);
                if (greater == NULL)
                    return false;
                out->gadgets = greater;
                out->cap = cap;
            }
            out->gadgets[out->count].dimension = c->dimension;
            strcpy(out->gadgets[out->count].path, path);
            out->rely++;
        }
        rel[len] = '';
    }
    return true;
}

Output:

7 information, 6,671 bytes in fixture

        5,000   74%  docs/photos/emblem.png
        1,234   18%  docs/information.md
          300    4%  src/essential.c

On an actual system you’d level it at a log or add listing, for instance bigfiles /var/log 20. Symbolic hyperlinks will not be adopted, so a hyperlink to a big file elsewhere shouldn’t be counted twice, and a hyperlink to / can not ship the stroll throughout the entire machine.

Frequent Errors When Itemizing Directories in C

1. Calling stat() on the naked title from readdir()

That is the commonest listing bug in C. readdir() returns notes.txt, and stat("notes.txt", ...) seems for that title within the present listing, not within the listing being listed. pitfalls/stat_wrong_path.c lists the take a look at folder each methods:

Output:

stat(title)               fstatat(dir, title)   title
fails: no such file      7 bytes              café.txt
fails: no such file      listing            docs
fails: no such file      0 bytes              empty.txt
fails: no such file      10 bytes             notes.txt
fails: no such file      listing            src
stat(title) failed for five of 5 entries; fstatat() for 0

Each stat() name fails, as a result of this system shouldn’t be working inside fixture. It’s worse when it doesn’t fail: if the present listing occurs to comprise a file with the identical title, stat() silently experiences that file’s dimension. Use fstatat(dirfd(dir), title, ...), because the layer does, or be part of the listing and the title right into a full path first.

stat() follows symbolic hyperlinks. A hyperlink that factors to its personal listing, or to any listing above it, then makes the tree infinitely deep. pitfalls/symlink_loop.c creates a folder with a hyperlink self -> . and walks it with stat():

Output:

lstat("loop/self"): a symbolic hyperlink, not adopted
stat("loop/self"):  a listing (the hyperlink was adopted)

A walker that follows hyperlinks:
  depth  1: loop/self
  depth  2: loop/self/self
  ...
  depth 39: ...f/self/self/self/self/self/self
  depth 40: ...f/self/self/self/self/self/self
  stopped at depth 41: Too many ranges of symbolic hyperlinks
40 directories visited, all of them the identical one
A symbolic hyperlink that factors again at its personal listing loop/self is a hyperlink to “.” Whether or not a stroll ends is dependent upon one flag. ON DISK loop/ self → . One listing, one hyperlink. stat(): FOLLOWS THE LINK loop loop/self loop/self/self loop/self/self/self … 40 ranges: ELOOP The identical listing, visited repeatedly. lstat() / AT_SYMLINK_NOFOLLOW loop self (hyperlink, not adopted) Reported as a hyperlink. The stroll ends.

Determine 1: Why recursive listing walkers should not observe symbolic hyperlinks. With stat() the hyperlink self -> . makes the tree look infinitely deep; with lstat() or fstatat(…, AT_SYMLINK_NOFOLLOW) it is only one entry. The depth of 40 is from the symlink_loop program’s output on Linux.

The stroll solely stopped as a result of Linux refuses to resolve a path that passes by way of greater than 40 symbolic hyperlinks (the ELOOP error), after visiting the identical listing 40 occasions. With out that restrict it could run till the trail now not slot in reminiscence. Use lstat() or fstatat(..., AT_SYMLINK_NOFOLLOW), which describe the hyperlink itself, and resolve explicitly whether or not to observe hyperlinks. Instruments that should observe them, similar to discover -L, keep in mind the system and inode variety of each listing they enter and skip any they’ve already visited.

3. Forgetting to skip . and ..

Each listing accommodates . (itself) and .. (its mother or father). A recursive stroll that doesn’t skip them descends into . repeatedly. When the verify was faraway from the layer as a take a look at, the unit assessments didn’t end inside 30 seconds: every stage accommodates each . and .., so the work doubles with each stage of depth. Skip each names earlier than doing anything with an entry.

4. Constructing paths in a fixed-size buffer

Path lengths will not be small. Linux permits paths of 4,096 bytes, and Home windows permits about 32,767 characters with long-path help enabled. Copying a listing and a reputation into char path[32] with strcpy and strcat writes previous the buffer as quickly as they’re longer:

/* Pitfall: constructing a path in a fixed-size buffer with strcpy and strcat.

   Listing names and file names don't have any small fastened size, so
   "listing" + "/" + "title" could be longer than any buffer chosen in
   advance. strcpy and strcat don't verify; fs_join does.

   utilization: pitfall_path_buffer checked     (refuses the lengthy path)
          pitfall_path_buffer unchecked   (writes previous the buffer: undefined habits) */
#embody "fs.h"

#embody <stdio.h>
#embody <string.h>

int essential(int argc, char **argv)
{
    const char *dir = "tasks/2024/client-reports";
    const char *title = "quarterly-summary-final-v2.xlsx";
    char path[32];

    if (argc > 1 && strcmp(argv[1], "unchecked") == 0) {
        strcpy(path, dir);                   /* 28 bytes + '': matches */
        strcat(path, "/");
        strcat(path, title);                  /* 61 bytes right into a 32-byte buffer */
        printf("constructed %sn", path);
        return 0;
    }

    if (fs_join(path, sizeof path, dir, title))
        printf("constructed %sn", path);
    else
        printf(""%s/%s" wants %zu bytes; the buffer has %zu, so it was refusedn",
               dir, title, strlen(dir) + 1 + strlen(title) + 1, sizeof path);
    return 0;
}

The checked model refuses the trail:

Output:

"tasks/2024/client-reports/quarterly-summary-final-v2.xlsx" wants 61 bytes; the buffer has 32, so it was refused

The unchecked model is undefined habits. AddressSanitizer stops it, and GCC even warns at compile time when optimizing:

AddressSanitizer: stack-buffer-overflow ... in strcat
warning: '__builtin___strcat_chk' forming offset [32, 60] is out of the bounds [0, 32] of object 'path' with kind 'char[32]' [-Warray-bounds=]

Paths come from the file system, which suggests from whoever created the information, so an unchecked path copy in a listing instrument is an exploitable bug, not only a crash. Examine the size earlier than copying, as fs_join() does, or use snprintf and verify its return worth.

5. Exhibiting the entry time as a substitute of the modification time

struct stat has 3 times: st_mtime (contents final modified), st_ctime (inode final modified; not creation time on Linux) and st_atime (final learn). A list that exhibits “date” nearly all the time means st_mtime, which is what ls -l and Home windows Explorer present. Entry occasions are additionally unreliable: most Linux methods mount file methods with relatime, which updates them at most as soon as a day.

6. Assuming readdir() returns names so as

The minimal lister above printed café.txt, src, ., empty.txt in that order: the order the file system saved them. The order differs between file methods and may change after information are added or deleted. Home windows usually returns names sorted on NTFS, which makes code that assumes an order work on one machine and fail on one other. Kind explicitly.

7. Printing UTF-8 names to a Home windows console with out switching it to UTF-8

Changing names to UTF-8 makes this system’s bytes appropriate, however the Home windows console decodes these bytes with its personal code web page. Earlier than the applications known as SetConsoleOutputCP(CP_UTF8), the Home windows take a look at run recorded the itemizing’s café.txt line as:

2024-06-01 12:00                     7  café.txt

These are the 2 UTF-8 bytes of é (C3 A9) drawn as two characters of code web page 437. The file title on disk was nice, and so have been the bytes this system wrote. The identical factor occurs one stage up: CMake’s execute_process() decoded program output with the console code web page too, till CMake 3.31 made UTF-8 its default (coverage CMP0176), so a take a look at that in contrast the output byte for byte failed. If a C program prints UTF-8 on Home windows, change the console to UTF-8 and inform each instrument that reads its output to anticipate UTF-8.

How the Code Is Examined

Listing code is straightforward to get nearly proper, so the assessments verify precise outcomes on a recognized folder.

  • A set take a look at folder. make_fixture creates 3 directories and eight information with fastened sizes and modification occasions, together with a hidden file and a file named café.txt, utilizing the layer’s personal UTF-8 path dealing with on each methods.
  • Byte-for-byte output. dirlist, tree, bigfiles and the pitfalls should print precisely the output proven right here. The identical anticipated information are used on Linux and Home windows, which checks that each implementations agree.
  • Unit assessments verify path becoming a member of on the precise buffer restrict, sorting, sizes, occasions, the UTF-8 title, error messages for a lacking listing and a file, an empty listing, listing totals and depth limits. On Linux and macOS in addition they verify {that a} symbolic hyperlink is reported as a hyperlink and {that a} stroll by way of a looping hyperlink finishes.
  • Deliberate errors. assessments/mutations.py places 13 errors into the library and confirms the assessments catch each:
Deliberate mistake How the assessments caught it
be part of permits one byte too many sanitizer: stack-buffer-overflow
be part of all the time provides a slash fs_join(buf, sizeof buf, "dir/", "a") && strcmp(buf, "dir/a") == 0 failed
information sorted earlier than directories strcmp(checklist[i].title, names[i]) == 0 failed
readdir returns “.” and “..” the assessments didn’t end in 30 s
stat on the naked title, not contained in the listing n == 6 failed
symbolic hyperlinks are adopted checklist[0].type == FS_LINK failed
listing dimension taken from stat checklist[i].dimension == sizes[i] failed
hidden take a look at inverted checklist[i].hidden == (i == 2) failed
stroll doesn’t restore the trail root.dimension == 6713 && root.rely == 6 failed
listing totals not added up root.dimension == 6713 && root.rely == 6 failed
hidden filter ignored root.dimension == 6671 && root.rely == 5 failed
depth restrict ignored root.rely == 6 && root.kids[0].rely == 0 && root.dimension == 59 failed
comma each three digits from the left strcmp(b, circumstances[i].s) == 0 failed

Key Takeaways

  • Customary C can not checklist a listing. Use opendir()/readdir()/closedir() on POSIX and FindFirstFileW()/FindNextFileW()/FindClose() on Home windows, and conceal the distinction behind one small interface.
  • readdir() returns naked names. Use fstatat(dirfd(dir), title, ...) or a joined path; stat(title) seems within the fallacious listing.
  • Skip . and .., and don’t observe symbolic hyperlinks in a recursive stroll, or the recursion might by no means finish.
  • By no means construct paths in fastened buffers with strcpy/strcat. Examine the size and refuse paths that don’t match.
  • Kind the entries your self. Listing order is dependent upon the file system.
  • On Home windows, use the vast (W) capabilities, convert names to UTF-8, and change the console to UTF-8 with SetConsoleOutputCP(CP_UTF8), or names outdoors the system code web page are misplaced or garbled.
  • Present st_mtime (or ftLastWriteTime) as a file’s date, not the entry time.

Conclusion

Itemizing a listing takes a dozen strains on both system. A list that’s appropriate with symbolic hyperlinks, Unicode names, deep bushes and lengthy paths takes extra care: the layer and the tree walker right here come to about 500 strains for each methods collectively, a lot of it error dealing with. As soon as that layer exists, instruments similar to dirlist, tree and bigfiles are brief, and the identical supply builds on Linux, macOS and Home windows.

The pure subsequent steps are filtering by title sample (fnmatch() on POSIX, the sample argument of FindFirstFileW() on Home windows) and watching a listing for modifications (inotify on Linux, ReadDirectoryChangesW() on Home windows). For extra C programming, see the C programming part.

Supply Code and Checks

directory-listing workflow status

All applications on this web page are within the information/directory-listing listing of the MYCPLUS C examples repository.

Construct, take a look at and run:

cmake -S . -B construct
cmake --build construct
ctest --test-dir construct --output-on-failure
./construct/tree -s .

What the construct checks.

  • Compilers: GCC and Clang below C11 and C17 with -Wall -Wextra -pedantic -Werror on Linux, the identical on macOS, and MSVC below /W4 /WX on Home windows. pitfalls/path_buffer.c is the one program allowed to construct with a warning, as a result of the overflow is the lesson.
  • Output: each program prints precisely what’s proven right here, from the identical anticipated information on each system.
  • Sanitizers and mutations: the assessments run clear below AddressSanitizer and UndefinedBehaviorSanitizer, the unchecked path copy is caught, and all 13 deliberate errors are caught.

What I Verified

The Ubuntu column was run for this text on Ubuntu 24.04 (x86-64, GCC 13.3, Clang 18, CMake 3.28, MinGW-w64 GCC 13, Valgrind). The Home windows column comes from the repository’s run_all.ps1 script.

Examine Ubuntu 24.04 Home windows 11
Builds with warnings as errors: GCC and Clang (C11 and C17) on Ubuntu, MSVC /W4 /WX (C11 and C17) on Home windows Handed MSVC /W4 /WX, C11 and C17: constructed
CTest: unit assessments and byte-for-byte outputs from the identical anticipated information 16 of 16 in all 4 configurations 14 of 14 in C11 and in C17 (the 2 POSIX-only pitfalls will not be constructed)
café.txt (UTF-8 title) and .secret (hidden) listed appropriately Sure Sure, on NTFS
AddressSanitizer and UndefinedBehaviorSanitizer, each take a look at 16 of 16, clear Not relevant
The unchecked strcat path is caught AddressSanitizer: stack-buffer-overflow Not relevant
Valgrind memcheck: assessments, dirlist, tree, bigfiles No errors, no leaks Not relevant
Home windows code cross-compiled with MinGW-w64, warnings as errors Handed Not relevant
13 deliberate errors injected into the library 13 of 13 caught Not run
Symbolic-link loop and stat() on the naked title Proven by the pitfall applications and checked by the assessments Not relevant (POSIX-only applications)

Not coated: macOS outdoors CI, community file methods, directories with hundreds of thousands of entries, and Home windows paths longer than 260 characters (long-path help was not enabled).

RELATED ARTICLES

LEAVE A REPLY

Please enter your comment!
Please enter your name here

Most Popular

Recent Comments