Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
path_utils.h File Reference

Small path and writable-directory helpers shared by USHER backends. More...

#include <errno.h>
#include <fcntl.h>
#include <limits.h>
#include <stdbool.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/stat.h>
#include <unistd.h>
Include dependency graph for path_utils.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define PATH_MAX   4096

Functions

static int usher_enter_executable_directory (void)
 Change to the directory containing the running USHER executable.
static const char * usher_resolve_path (const char *path, char *buffer, size_t buffer_size)
 Expand a leading home-directory shorthand without allocating memory.
static int usher_ensure_directory (const char *path)
 Create missing directory components and verify the final directory is writable.
static int usher_prepare_photo (char *filename, size_t capacity)
 Redirect an intended public photo into its same-filesystem private staging directory.
static int usher_publish_photo (const char *source, const char *destination)
 Publish completed immutable bytes atomically without copying or replacing an existing file.
static int usher_complete_photo (char *filename, size_t capacity)
 Publish a staged photo and return its immutable public path.

Detailed Description

Small path and writable-directory helpers shared by USHER backends.

Paths are intentionally resolved only for a leading ~: USHER configuration is not a shell and must not expand arbitrary variables or execute shell syntax.

Definition in file path_utils.h.

Macro Definition Documentation

◆ PATH_MAX

#define PATH_MAX   4096

Definition at line 39 of file path_utils.h.

Function Documentation

◆ usher_complete_photo()

int usher_complete_photo ( char * filename,
size_t capacity )
inlinestatic

Publish a staged photo and return its immutable public path.

Parameters
[in,out]filenamePath produced by usher_prepare_photo; public path on nonnegative return.
capacityWritable capacity of filename, including its terminator.
Returns
usher_publish_photo status; on failure the private path remains unchanged.

Only the immediate .pending parent is removed. No metadata may change after success.

Definition at line 216 of file path_utils.h.

◆ usher_ensure_directory()

int usher_ensure_directory ( const char * path)
inlinestatic

Create missing directory components and verify the final directory is writable.

Parameters
pathDirectory path, with optional leading home shorthand.
Returns
0 for a writable directory, otherwise -1.

Components are created one at a time to avoid invoking a shell. Existing parents are harmless, while final stat/access checks distinguish a file or read-only path from a usable capture destination.

Definition at line 97 of file path_utils.h.

◆ usher_enter_executable_directory()

int usher_enter_executable_directory ( void )
inlinestatic

Change to the directory containing the running USHER executable.

Returns
0 on success, otherwise -1 with errno set.

Project resources and sibling workers use relative paths, so anchor them to the installed executable rather than the caller's working directory.

Definition at line 46 of file path_utils.h.

◆ usher_prepare_photo()

int usher_prepare_photo ( char * filename,
size_t capacity )
inlinestatic

Redirect an intended public photo into its same-filesystem private staging directory.

Parameters
[in,out]filenameBounded public path, replaced with a sibling .pending path on success.
capacityWritable capacity of filename, including its terminator.
Returns
0 on success, otherwise -1 with errno set; no existing photo is overwritten.

The public parent must exist. Staging must be owned by this user with mode 0700. A failed call may change the path buffer, but never creates a photo.

Definition at line 143 of file path_utils.h.

◆ usher_publish_photo()

int usher_publish_photo ( const char * source,
const char * destination )
inlinestatic

Publish completed immutable bytes atomically without copying or replacing an existing file.

Parameters
sourceExclusively owned, nonempty regular file with no other hardlinks.
destinationPublic path on the same filesystem.
Returns
0 for durable publication and private removal; 1 if published but directory sync or private removal failed; -1 if not published, with errno describing the failure.

Call only after every metadata write. Readers may open the final name immediately. A positive result must never trigger a capture retry or another write to either alias. Crash recovery may retain a private alias; callers must not modify published originals.

Definition at line 176 of file path_utils.h.

◆ usher_resolve_path()

const char * usher_resolve_path ( const char * path,
char * buffer,
size_t buffer_size )
inlinestatic

Expand a leading home-directory shorthand without allocating memory.

Parameters
pathConfigured path, possibly beginning with ~ or ~/.
bufferCaller-owned expansion storage.
buffer_sizeCapacity of buffer.
Returns
buffer for a successful expansion, path when no expansion is needed, or NULL when path is NULL.

Returning the original pointer avoids copying the common literal-path case.

Definition at line 74 of file path_utils.h.