ra8_fs_fat_exfat_dir.c

Go to the documentation of this file.

 
#include <stddef.h>
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_fs.h"
#include "ra8_fs_fat_internal.h"
 
/* =============================================================================
 * Path resolution
 * =============================================================================
 */

RA8_INTERNAL
static ra8_err_t internal_exfat_enter(const ra8_fs_mount_t* m,
                                      const exfat_dir_t*    cur,
                                      const char*           comp,
                                      uint32_t              len,
                                      exfat_dir_t*          out)
{
  /* Two bounds, in two domains, and both are needed. The BYTE bound sizes the
   * buffer, because @p comp is UTF-8 here and a 64-unit name is up to three
   * times that many bytes. The UNIT bound below is the one the FORMAT imposes,
   * so it is checked after conversion -- 65 ASCII characters and 65 accented
   * ones are equally one over, and only the unit count says so (#606). */
  if (len >= (uint32_t)k_exfat_name_u8_cap) {
    return k_ra8_err_invalid_arg;
  }
  char namebuf[k_exfat_name_u8_cap] = {};
  for (uint32_t i = 0U; i < len; i++) {
    namebuf[i] = comp[i];
  }
  namebuf[len] = '\0';
  /* Validate the component converts within the exFAT unit cap and is well-formed
   * UTF-8 before searching -- the byte bound above cannot see a name short in
   * bytes yet over the 64-UNIT cap (#606). */
  uint16_t        units[k_exfat_name_cap] = {};
  uint32_t        nunits                  = 0U;
  const ra8_err_t ce                      = priv_exfat_name_to_units(m, namebuf, units, &nunits);
  if (ce == k_ra8_err_no_mem) {
    return k_ra8_err_invalid_arg; /* over the name cap: an argument error */
  }
  if (ce != k_ra8_ok) {
    return ce;
  }
  /* ::priv_exfat_find_set rather than ::priv_exfat_find, because a directory
   * that fills up has to REWRITE its own File-entry set to grow (#677), and only
   * find_set reports where that set lives. `pos[0]` is the File entry; carrying
   * it in the descendant is what lets ::priv_exfat_grow_dir patch the right
   * metadata without a second walk of the parent. */
  exfat_setpos_t  pos[k_exfat_set_max_entries] = {};
  uint32_t        count                        = 0U;
  uint8_t         file_e[k_exfat_entry_bytes]  = {};
  uint8_t         strm[k_exfat_entry_bytes]    = {};
  const ra8_err_t e = priv_exfat_find_set(m,
                                          cur,
                                          namebuf,
                                          pos,
                                          (uint32_t)k_exfat_set_max_entries,
                                          &count,
                                          file_e,
                                          strm);
  if (e != k_ra8_ok) {
    return e;
  }
  if ((file_e[k_exfat_off_file_attr] & (uint8_t)k_exfat_attr_directory) == 0U) {
    return k_ra8_err_invalid_arg; /* a file cannot be an intermediate component */
  }
  if (priv_rd32(&strm[k_exfat_strm_off_clus]) < (uint32_t)k_cluster_first_data) {
    return k_ra8_err_protocol_error; /* a directory always owns a cluster */
  }
  priv_exfat_dir_from_set(m, strm, out);
  out->self_cluster = pos[0].cluster;
  out->self_index   = pos[0].index;
  return k_ra8_ok;
}
 
/* `priv_exfat_resolve_parent()`: see header for the documented contract. */
ra8_err_t priv_exfat_resolve_parent(const ra8_fs_mount_t* m,
                                    const char*           path,
                                    exfat_dir_t*          out_parent,
                                    const char**          out_leaf)
{
  const char* p = path;
  while (*p == '/') {
    p++;
  }
  exfat_dir_t cur = {};
  priv_exfat_dir_root(m, &cur);
  for (uint32_t depth = 0U; depth < (uint32_t)k_exfat_path_depth; depth++) {
    const char* end  = p;
    uint32_t    nlen = 0U;
    while (*end != '\0') {
      if (*end == '/') {
        break;
      }
      end++;
      nlen++;
    }
    if (*end == '\0') {
      *out_parent = cur;
      *out_leaf   = p;
      return k_ra8_ok;
    }
    exfat_dir_t     next = {};
    const ra8_err_t e    = internal_exfat_enter(m, &cur, p, nlen, &next);
    if (e != k_ra8_ok) {
      return e;
    }
    cur = next;
    p   = end;
    while (*p == '/') {
      p++;
    }
  }
  return k_ra8_err_invalid_arg; /* deeper than k_exfat_path_depth */
}
 
/* `priv_exfat_resolve_dir()`: see header for the documented contract. */
ra8_err_t priv_exfat_resolve_dir(const ra8_fs_mount_t* m, const char* path, exfat_dir_t* out)
{
  const char* p = path;
  while (*p == '/') {
    p++;
  }
  if (*p == '\0') {
    priv_exfat_dir_root(m, out);
    return k_ra8_ok;
  }
  exfat_dir_t     parent = {};
  const char*     leaf   = nullptr;
  const ra8_err_t e      = priv_exfat_resolve_parent(m, path, &parent, &leaf);
  if (e != k_ra8_ok) {
    return e;
  }
  const uint32_t len = priv_strlen(leaf);
  if (len == 0U) {
    *out = parent; /* trailing slash: the parent IS the directory */
    return k_ra8_ok;
  }
  return internal_exfat_enter(m, &parent, leaf, len, out);
}
 
/* `priv_exfat_lookup()`: see header for the documented contract. */
ra8_err_t
priv_exfat_lookup(const ra8_fs_mount_t* m, const char* path, uint8_t* out_strm, uint8_t* out_attr)
{
  exfat_dir_t     parent = {};
  const char*     leaf   = nullptr;
  const ra8_err_t e      = priv_exfat_resolve_parent(m, path, &parent, &leaf);
  if (e != k_ra8_ok) {
    return e;
  }
  if (priv_strlen(leaf) == 0U) {
    return k_ra8_err_invalid_arg; /* the volume root is not an entry set */
  }
  return priv_exfat_find(m, &parent, leaf, out_strm, out_attr);
}
 
/* =============================================================================
 * mkdir
 * =============================================================================
 */
 
/* `priv_exfat_zero_cluster()`: see header for the documented contract. */
ra8_err_t priv_exfat_zero_cluster(const ra8_fs_mount_t* m, uint32_t clus)
{
  const uint64_t base = priv_cluster_to_lba(m, clus);
  for (uint32_t s = 0U; s < m->sectors_per_cluster; s++) {
    const ra8_err_t e = priv_write_sector(m, base + s, k_zero_sector);
    if (e != k_ra8_ok) {
      return e;
    }
  }
  return k_ra8_ok;
}
 
/* `priv_exfat_seal_cluster()`: see header for the documented contract. */
ra8_err_t priv_exfat_seal_cluster(const ra8_fs_mount_t* m, uint32_t clus)
{
  const uint8_t unused =
    (uint8_t)((uint8_t)k_exfat_entry_file & (uint8_t)~(uint8_t)k_exfat_inuse_bit);
  const uint64_t base = priv_cluster_to_lba(m, clus);
  for (uint32_t s = 0U; s < m->sectors_per_cluster; s++) {
    uint8_t* const sec = priv_sec_io();
    ra8_err_t      e   = priv_read_sector(m, base + s, sec);
    if (e != k_ra8_ok) {
      return e;
    }
    uint8_t dirty = 0U;
    for (uint32_t off = 0U; off < priv_bps(m); off += (uint32_t)k_exfat_entry_bytes) {
      if (sec[off] == (uint8_t)k_exfat_entry_eod) {
        sec[off] = unused;
        dirty    = 1U;
      }
    }
    if (dirty != 0U) {
      e = priv_write_sector(m, base + s, sec);
      if (e != k_ra8_ok) {
        return e;
      }
    }
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static uint32_t internal_exfat_build_dir_set(const ra8_fs_mount_t* m,
                                             uint8_t*              set,
                                             const uint16_t*       name,
                                             uint32_t              nlen,
                                             uint32_t              first)
{
  const uint32_t name_entries =
    (nlen + (uint32_t)k_exfat_name_per_entry - 1U) / (uint32_t)k_exfat_name_per_entry;
  const uint32_t sec_count = 1U + name_entries;
  const uint32_t total     = (1U + sec_count) * (uint32_t)k_exfat_entry_bytes;
  for (uint32_t i = 0U; i < total; i++) {
    set[i] = 0U;
  }
  set[0]                      = (uint8_t)k_exfat_entry_file;
  set[k_exfat_off_file_secnt] = (uint8_t)sec_count;
  priv_wr16(&set[k_exfat_off_file_attr], (uint16_t)k_exfat_attr_directory);
  /* Before the SetChecksum below, which covers these bytes (#601). */
  priv_exfat_file_stamp_create(set);
  const uint32_t cbytes        = priv_cluster_bytes(m);
  uint8_t*       strm          = &set[k_exfat_entry_bytes];
  strm[0]                      = (uint8_t)k_exfat_entry_stream;
  strm[k_exfat_strm_off_flags] = (uint8_t)k_exfat_secflag_alloc;
  strm[k_exfat_strm_off_nlen]  = (uint8_t)nlen;
  priv_wr16(&strm[k_exfat_off_strm_hash], priv_exfat_name_hash(name, nlen));
  priv_wr32(&strm[k_exfat_off_strm_valid], cbytes);
  priv_wr32(&strm[k_exfat_strm_off_clus], first);
  priv_wr32(&strm[k_exfat_strm_off_dlen], cbytes);
  for (uint32_t n = 0U; n < name_entries; n++) {
    uint8_t* ne = &set[(size_t)(2U + n) * (size_t)k_exfat_entry_bytes];
    ne[0]       = (uint8_t)k_exfat_entry_name;
    for (uint32_t c = 0U; c < (uint32_t)k_exfat_name_per_entry; c++) {
      const uint32_t pos = (n * (uint32_t)k_exfat_name_per_entry) + c;
      if (pos < nlen) {
        /* A whole UTF-16 unit, not the low byte of one -- the same correction
         * the file-side builder needed (#606). */
        priv_wr16(&ne[k_exfat_name_off + (c * 2U)], name[pos]);
      }
    }
  }
  priv_wr16(&set[k_exfat_off_file_csum], priv_exfat_set_checksum(set, total));
  return total;
}

RA8_INTERNAL
static ra8_err_t
internal_exfat_dir_alloc(const ra8_fs_mount_t* m, uint32_t* out_clus, uint64_t* out_bmp)
{
  uint32_t  bclus = 0U;
  uint32_t  blen  = 0U;
  ra8_err_t e     = priv_exfat_find_bitmap(m, &bclus, &blen);
  if (e != k_ra8_ok) {
    return e;
  }
  *out_bmp = priv_cluster_to_lba(m, bclus);
  e        = priv_exfat_bitmap_scan(m, *out_bmp, 1U, out_clus);
  if (e != k_ra8_ok) {
    return e;
  }
  e = priv_exfat_zero_cluster(m, *out_clus);
  if (e != k_ra8_ok) {
    return e;
  }
  e = priv_exfat_bitmap_mark(m, *out_bmp, *out_clus, 1U);
  if (e != k_ra8_ok) {
    return e;
  }
  /* Only now, with the bit actually set, is it true that the next free cluster
   * starts past this one (#607). */
  priv_alloc_hint_set(m, *out_clus + 1U);
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_exfat_mkdir_check(const ra8_fs_mount_t* m,
                                            const exfat_dir_t*    parent,
                                            const char*           leaf,
                                            uint32_t              nlen)
{
  if (nlen == 0U) {
    return k_ra8_err_invalid_arg; /* "/" or a trailing slash: the root itself */
  }
  if (nlen > (uint32_t)k_exfat_name_cap) {
    return k_ra8_err_invalid_arg;
  }
  uint8_t strm[k_exfat_entry_bytes] = {};
  uint8_t attr                      = 0U;
  /* mkdir REFUSES an existing name rather than replacing it, unlike
   * ra8_fs_write_file(), which is a create-or-replace verb (#603). A directory
   * and a file are both an entry set under that name, so both refuse here.
   *
   * The third verdict is the one that is easy to drop: a BACKEND FAILURE is not
   * "the name is absent". Testing only for k_ra8_ok would turn an unreadable
   * directory into a green light to create, and the volume would then hold two
   * entry sets for one name -- the #603 duplicate, reintroduced through the
   * error path instead of the happy one. */
  const ra8_err_t fe = priv_exfat_find(m, parent, leaf, strm, &attr);
  if (fe == k_ra8_ok) {
    return k_ra8_err_exists;
  }
  if (fe != k_ra8_err_not_found) {
    return fe;
  }
  return k_ra8_ok;
}
 
/* `priv_exfat_mkdir()`: see header for the documented contract. */
ra8_err_t priv_exfat_mkdir(const ra8_fs_mount_t* m, const char* path)
{
  exfat_dir_t parent = {};
  const char* leaf   = nullptr;
  ra8_err_t   e      = priv_exfat_resolve_parent(m, path, &parent, &leaf);
  if (e != k_ra8_ok) {
    return e;
  }
  /* The leaf becomes code units here, once, and every on-disk length below
   * counts those: the slot run, `NameLength`, and the name hash. Counting the
   * caller's BYTES instead is what made a directory whose name held one
   * multi-byte character unopenable by that name (#606). */
  uint16_t        units[k_exfat_name_cap] = {};
  uint32_t        nlen                    = 0U;
  const ra8_err_t ne                      = priv_exfat_name_to_units(m, leaf, units, &nlen);
  if (ne == k_ra8_err_no_mem) {
    return k_ra8_err_invalid_arg; /* over the name cap: an argument, not a full disk */
  }
  if (ne != k_ra8_ok) {
    return ne;
  }
  e = internal_exfat_mkdir_check(m, &parent, leaf, nlen);
  if (e != k_ra8_ok) {
    return e;
  }
  /* Reserve the parent's slot run BEFORE allocating, so a full parent directory
   * costs no bitmap churn and needs no rollback. */
  const uint32_t need =
    2U + ((nlen + (uint32_t)k_exfat_name_per_entry - 1U) / (uint32_t)k_exfat_name_per_entry);
  uint32_t dclus = 0U;
  uint32_t didx  = 0U;
  e              = priv_exfat_find_dir_space(m, &parent, need, &dclus, &didx);
  if (e != k_ra8_ok) {
    return e;
  }
  uint32_t newclus = 0U;
  uint64_t bmp_lba = 0U;
  e                = internal_exfat_dir_alloc(m, &newclus, &bmp_lba);
  if (e != k_ra8_ok) {
    return e;
  }
  uint8_t        set[k_exfat_max_set_bytes] = {};
  const uint32_t bytes = internal_exfat_build_dir_set(m, set, units, nlen, newclus);
  e                    = priv_exfat_write_dir_set(m, dclus, didx, set, bytes);
  if (e != k_ra8_ok) {
    (void)priv_exfat_bitmap_clear(m, bmp_lba, newclus, 1U); /* never leak the cluster */
    return e;
  }
  return k_ra8_ok;
}
 
/* =============================================================================
 * rmdir
 * =============================================================================
 */

RA8_INTERNAL
static ra8_err_t
internal_exfat_dir_is_empty(const ra8_fs_mount_t* m, const exfat_dir_t* dir, uint8_t* out_empty)
{
  exfat_cursor_t cur = {};
  priv_exfat_cursor_init(dir, &cur);
  while (cur.scanned < (uint32_t)k_exfat_scan_limit) {
    uint8_t         e[k_exfat_entry_bytes] = {};
    const ra8_err_t r                      = priv_exfat_next_entry(m, &cur, e);
    if (r == k_ra8_err_not_found) {
      *out_empty = 1U; /* the run ended without an occupant and without a 0x00 */
      return k_ra8_ok;
    }
    if (r != k_ra8_ok) {
      return r;
    }
    if (e[0] == (uint8_t)k_exfat_entry_eod) {
      *out_empty = 1U;
      return k_ra8_ok;
    }
    if ((e[0] & (uint8_t)k_exfat_inuse_bit) == 0U) {
      continue; /* a deleted remnant is not an occupant */
    }
    *out_empty = 0U;
    return k_ra8_ok;
  }
  *out_empty = 1U;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_exfat_rmdir_locate(const ra8_fs_mount_t* m,
                                             const char*           path,
                                             exfat_setpos_t*       pos,
                                             uint32_t*             out_count,
                                             uint8_t*              strm,
                                             exfat_dir_t*          out_dir)
{
  exfat_dir_t parent = {};
  const char* leaf   = nullptr;
  ra8_err_t   e      = priv_exfat_resolve_parent(m, path, &parent, &leaf);
  if (e != k_ra8_ok) {
    return e;
  }
  if (priv_strlen(leaf) == 0U) {
    return k_ra8_err_invalid_arg; /* "/" or a trailing slash: the root itself */
  }
  uint8_t file_e[k_exfat_entry_bytes] = {};
  e                                   = priv_exfat_find_set(m,
                                                            &parent,
                                                            leaf,
                                                            pos,
                                                            (uint32_t)k_exfat_set_max_entries,
                                                            out_count,
                                                            file_e,
                                                            strm);
  if (e != k_ra8_ok) {
    return e;
  }
  if ((file_e[k_exfat_off_file_attr] & (uint8_t)k_exfat_attr_directory) == 0U) {
    return k_ra8_err_invalid_arg; /* a file: ra8_fs_unlink() is the verb for it */
  }
  if (priv_rd32(&strm[k_exfat_strm_off_clus]) < (uint32_t)k_cluster_first_data) {
    return k_ra8_err_protocol_error; /* a directory always owns a cluster */
  }
  priv_exfat_dir_from_set(m, strm, out_dir);
  return k_ra8_ok;
}
 
/* `priv_exfat_rmdir()`: see header for the documented contract. */
ra8_err_t priv_exfat_rmdir(const ra8_fs_mount_t* m, const char* path)
{
  exfat_setpos_t pos[k_exfat_set_max_entries] = {};
  uint32_t       count                        = 0U;
  uint8_t        strm[k_exfat_entry_bytes]    = {};
  exfat_dir_t    victim                       = {};
  ra8_err_t      e = internal_exfat_rmdir_locate(m, path, pos, &count, strm, &victim);
  if (e != k_ra8_ok) {
    return e;
  }
  uint8_t empty = 0U;
  e             = internal_exfat_dir_is_empty(m, &victim, &empty);
  if (e != k_ra8_ok) {
    return e;
  }
  if (empty == 0U) {
    return k_ra8_err_not_empty;
  }
  /* Entries first, clusters second -- the same order ::priv_exfat_unlink uses.
   * A fault between the two leaves clusters marked used with nothing pointing
   * at them, which a host `fsck` reports and repairs; the reverse order would
   * leave a live entry set pointing at free space, which it cannot. */
  e = priv_exfat_drop_set(m, pos, count);
  if (e != k_ra8_ok) {
    return e;
  }
  return priv_exfat_free_clusters(m, strm);
}