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
Go to the documentation of this file.
1/*
2 * Copyright 2026 OpenUAS
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18#ifndef USHER_PATH_UTILS_H
19#define USHER_PATH_UTILS_H
20
21/**
22 * @file path_utils.h
23 * @brief Small path and writable-directory helpers shared by USHER backends.
24 * @details Paths are intentionally resolved only for a leading `~`: USHER configuration
25 * is not a shell and must not expand arbitrary variables or execute shell syntax.
26 */
27
28#include <errno.h>
29#include <fcntl.h>
30#include <limits.h>
31#include <stdbool.h>
32#include <stdio.h>
33#include <stdlib.h>
34#include <string.h>
35#include <sys/stat.h>
36#include <unistd.h>
37
38#ifndef PATH_MAX
39 #define PATH_MAX 4096
40#endif
41
42/** @brief Change to the directory containing the running USHER executable.
43 * @return 0 on success, otherwise -1 with errno set.
44 * @details Project resources and sibling workers use relative paths, so anchor
45 * them to the installed executable rather than the caller's working directory. */
46static inline int usher_enter_executable_directory(void)
47{
48 char executable[PATH_MAX];
49 ssize_t length = readlink("/proc/self/exe", executable, sizeof(executable) - 1);
50 if (length <= 0 || (size_t)length >= sizeof(executable) - 1) {
51 return -1;
52 }
53 executable[length] = '\0';
54 char *separator = strrchr(executable, '/');
55 if (separator == NULL) {
56 errno = ENOENT;
57 return -1;
58 }
59 if (separator == executable) {
60 separator[1] = '\0';
61 } else {
62 *separator = '\0';
63 }
64 return chdir(executable);
65}
66
67/** @brief Expand a leading home-directory shorthand without allocating memory.
68 * @param path Configured path, possibly beginning with `~` or `~/`.
69 * @param buffer Caller-owned expansion storage.
70 * @param buffer_size Capacity of @p buffer.
71 * @return @p buffer for a successful expansion, @p path when no expansion is needed,
72 * or NULL when @p path is NULL.
73 * @details Returning the original pointer avoids copying the common literal-path case. */
74static inline const char *usher_resolve_path(const char *path, char *buffer, size_t buffer_size)
75{
76 if (path == NULL) {
77 return NULL;
78 }
79 if (path[0] == '~' && (path[1] == '/' || path[1] == '\0')) {
80 const char *home = getenv("HOME");
81 if (home != NULL && home[0] != '\0') {
82 int length = snprintf(buffer, buffer_size, "%s%s", home, path + 1);
83 if (length > 0 && (size_t)length < buffer_size) {
84 return buffer;
85 }
86 }
87 }
88 return path;
89}
90
91/** @brief Create missing directory components and verify the final directory is writable.
92 * @param path Directory path, with optional leading home shorthand.
93 * @return 0 for a writable directory, otherwise -1.
94 * @details Components are created one at a time to avoid invoking a shell. Existing
95 * parents are harmless, while final stat/access checks distinguish a file or read-only
96 * path from a usable capture destination. */
97static inline int usher_ensure_directory(const char *path)
98{
99 if (path == NULL || path[0] == '\0') {
100 return -1;
101 }
102 char resolved[PATH_MAX];
103 const char *target = usher_resolve_path(path, resolved, sizeof(resolved));
104 if (target == NULL) {
105 return -1;
106 }
107
108 char temp[PATH_MAX];
109 size_t length = 0;
110 while (target[length] != '\0' && length < sizeof(temp) - 1) {
111 temp[length] = target[length];
112 length++;
113 }
114 if (target[length] != '\0') {
115 return -1;
116 }
117 temp[length] = '\0';
118
119 for (size_t index = 1; index <= length; index++) {
120 if (temp[index] == '/' || temp[index] == '\0') {
121 char character = temp[index];
122 temp[index] = '\0';
123 if (temp[0] != '\0' && mkdir(temp, 0755) != 0 && errno != EEXIST) {
124 // Parent directory attempt - ignore if it already exists
125 }
126 temp[index] = character;
127 }
128 }
129
130 struct stat status;
131 if (stat(target, &status) != 0 || !S_ISDIR(status.st_mode) || access(target, W_OK) != 0) {
132 return -1;
133 }
134 return 0;
135}
136
137/** @brief Redirect an intended public photo into its same-filesystem private staging directory.
138 * @param[in,out] filename Bounded public path, replaced with a sibling .pending path on success.
139 * @param capacity Writable capacity of @p filename, including its terminator.
140 * @return 0 on success, otherwise -1 with errno set; no existing photo is overwritten.
141 * @details The public parent must exist. Staging must be owned by this user with mode 0700.
142 * A failed call may change the path buffer, but never creates a photo. */
143static inline int usher_prepare_photo(char *filename, size_t capacity)
144{
145 if (!filename || !capacity) { errno = EINVAL; return -1; }
146 const size_t length = strnlen(filename, capacity);
147 const char *separator = length < capacity ? strrchr(filename, '/') : NULL;
148 const char staging[] = ".pending/";
149 const size_t extra = sizeof(staging) - 1;
150 if (!separator || !separator[1] || length >= PATH_MAX - extra || length + extra >= capacity) {
151 errno = ENAMETOOLONG; return -1;
152 }
153 struct stat status;
154 if (lstat(filename, &status) == 0 || errno != ENOENT) { errno = EEXIST; return -1; }
155 const size_t parent_length = (size_t)(separator - filename);
156 char directory[PATH_MAX];
157 const int count = snprintf(directory, sizeof(directory), "%.*s/.pending", (int)parent_length, filename);
158 if (count < 0 || (size_t)count >= sizeof(directory)) { errno = ENAMETOOLONG; return -1; }
159 if ((mkdir(directory, 0700) != 0 && errno != EEXIST) || lstat(directory, &status) != 0) return -1;
160 if (!S_ISDIR(status.st_mode) || status.st_uid != geteuid() || (status.st_mode & 077)) { errno = EACCES; return -1; }
161 for (size_t index = length + 1; index > parent_length + 1; --index)
162 filename[index - 1 + extra] = filename[index - 1];
163 for (size_t index = 0; index < extra; ++index) filename[parent_length + 1 + index] = staging[index];
164 if (lstat(filename, &status) == 0 || errno != ENOENT) { errno = EEXIST; return -1; }
165 return 0;
166}
167
168/** @brief Publish completed immutable bytes atomically without copying or replacing an existing file.
169 * @param source Exclusively owned, nonempty regular file with no other hardlinks.
170 * @param destination Public path on the same filesystem.
171 * @return 0 for durable publication and private removal; 1 if published but directory sync or
172 * private removal failed; -1 if not published, with errno describing the failure.
173 * @details Call only after every metadata write. Readers may open the final name immediately.
174 * A positive result must never trigger a capture retry or another write to either alias.
175 * Crash recovery may retain a private alias; callers must not modify published originals. */
176static inline int usher_publish_photo(const char *source, const char *destination)
177{
178 if (!source || !destination || !source[0] || !destination[0]) { errno = EINVAL; return -1; }
179 char parent[PATH_MAX];
180 const char *basename = strrchr(destination, '/');
181 const size_t length = basename ? (size_t)(basename - destination) : 0;
182 if (length >= sizeof(parent)) { errno = ENAMETOOLONG; return -1; }
183 if (basename) {
184 for (size_t index = 0; index < length; ++index) parent[index] = destination[index];
185 parent[length ? length : 1] = '\0';
186 if (!length) parent[0] = '/';
187 ++basename;
188 } else {
189 parent[0] = '.'; parent[1] = '\0'; basename = destination;
190 }
191 if (!basename[0]) { errno = EINVAL; return -1; }
192 int directory = open(parent, O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC);
193 if (directory < 0) return -1;
194 int input = open(source, O_RDONLY | O_NOFOLLOW | O_NONBLOCK | O_CLOEXEC);
195 struct stat status;
196 int result = -1;
197 if (input >= 0 && fstat(input, &status) == 0) {
198 if (!S_ISREG(status.st_mode) || status.st_size <= 0 || status.st_nlink != 1) errno = EINVAL;
199 else if (fsync(input) == 0 && linkat(AT_FDCWD, source, directory, basename, 0) == 0) {
200 result = 1;
201 if (fsync(directory) == 0 && unlink(source) == 0) result = 0;
202 }
203 }
204 const int saved_errno = errno;
205 if (input >= 0) close(input);
206 close(directory);
207 errno = saved_errno;
208 return result;
209}
210
211/** @brief Publish a staged photo and return its immutable public path.
212 * @param[in,out] filename Path produced by usher_prepare_photo; public path on nonnegative return.
213 * @param capacity Writable capacity of @p filename, including its terminator.
214 * @return usher_publish_photo status; on failure the private path remains unchanged.
215 * @details Only the immediate .pending parent is removed. No metadata may change after success. */
216static inline int usher_complete_photo(char *filename, size_t capacity)
217{
218 if (!filename || !capacity) { errno = EINVAL; return -1; }
219 const size_t length = strnlen(filename, capacity);
220 const char *basename = length < capacity ? strrchr(filename, '/') : NULL;
221 const char staging[] = "/.pending";
222 const size_t extra = sizeof(staging) - 1;
223 if (!basename || (size_t)(basename - filename) < extra || length >= PATH_MAX
224 || strncmp(basename - extra, staging, extra)) { errno = EINVAL; return -1; }
225 char destination[PATH_MAX] = {0};
226 const size_t parent_length = (size_t)(basename - filename) - extra;
227 for (size_t index = 0; index < parent_length; ++index) destination[index] = filename[index];
228 for (size_t index = parent_length; index <= length - extra; ++index) destination[index] = filename[index + extra];
229 const int result = usher_publish_photo(filename, destination);
230 if (result >= 0) for (size_t index = 0; index <= length - extra; ++index) filename[index] = destination[index];
231 return result;
232}
233
234#endif // USHER_PATH_UTILS_H
static unsigned capacity[COVERAGE_CAMERAS]
void(* close)(struct usbfs_handle *)
Definition chdkbridge.c:57
int(* open)(const struct usbfs_device *, struct usbfs_handle *)
Definition chdkbridge.c:56
static int usher_complete_photo(char *filename, size_t capacity)
Publish a staged photo and return its immutable public path.
Definition path_utils.h:216
static int usher_prepare_photo(char *filename, size_t capacity)
Redirect an intended public photo into its same-filesystem private staging directory.
Definition path_utils.h:143
static int usher_enter_executable_directory(void)
Change to the directory containing the running USHER executable.
Definition path_utils.h:46
static const char * usher_resolve_path(const char *path, char *buffer, size_t buffer_size)
Expand a leading home-directory shorthand without allocating memory.
Definition path_utils.h:74
#define PATH_MAX
Definition path_utils.h:39
static int usher_publish_photo(const char *source, const char *destination)
Publish completed immutable bytes atomically without copying or replacing an existing file.
Definition path_utils.h:176
static int usher_ensure_directory(const char *path)
Create missing directory components and verify the final directory is writable.
Definition path_utils.h:97
static size_t count
Definition pose_log.c:79
struct usher_control_result result
Definition usher.c:377