% limb manual
% sa_lsat(3)
% limb 0.1.0
% 2023-07-24

# NAME

sa_lsat, sa_ls - append directory listing into an stralloc

# SYNOPSIS

    #include <fcntl.h> /* AT_FDCWD */
    #include <limb/djbunix.h>

```pre hl
int sa_lsat(stralloc *<em>sa</em>, int <em>fd</em>, const char *<em>name</em>, size_t *<em>maxlen</em>)
int sa_ls(stralloc *<em>sa</em>, const char *<em>name</em>, size_t *<em>maxlen</em>)
```

# DESCRIPTION

The `sa_lsat`() function appends the names of all files (except for `.` and `..`)
in directory `name` into the stralloc pointed by `sa` as NUL-terminated strings.

If `name` is a realtive path it is relative to the directory associated with the
file descriptor `fd`, which may by *AT_FDCWD* to use the current working
directory.

If not NULL, `maxlen` will be set to the length of the longest file name added.
(It will be 0 in case of empty directory.)

The `sa_ls`() macro is similar except when `name` is a relative path, in
which case it is relative to the current working directory.

# RETURN VALUE

On success, these functions return the number of names added into `sa`.
Otherwise, they return -1 and set `errno` to indicate the error.

# ERRORS

These functions may fail if :

: *ENOMEM*
:: Out of memory to add names into `sa`

They may also fail and set errno for any of the errors specified for the
functions [opendirat](3) and [readdir](3).