| // SPDX-License-Identifier: MPL-2.0 OR LGPL-3.0-or-later | |
| /* | |
| * libpathrs: safe path resolution on Linux | |
| * Copyright (C) 2019-2025 SUSE LLC | |
| * Copyright (C) 2026 Aleksa Sarai <cyphar@cyphar.com> | |
| * | |
| * == MPL-2.0 == | |
| * | |
| * This Source Code Form is subject to the terms of the Mozilla Public | |
| * License, v. 2.0. If a copy of the MPL was not distributed with this | |
| * file, You can obtain one at https://mozilla.org/MPL/2.0/. | |
| * | |
| * Alternatively, this Source Code Form may also (at your option) be used | |
| * under the terms of the GNU Lesser General Public License Version 3, as | |
| * described below: | |
| * | |
| * == LGPL-3.0-or-later == | |
| * | |
| * This program is free software: you can redistribute it and/or modify it | |
| * under the terms of the GNU Lesser General Public License as published by | |
| * the Free Software Foundation, either version 3 of the License, or (at | |
| * your option) any later version. | |
| * | |
| * This program is distributed in the hope that it will be useful, but | |
| * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY | |
| * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
| * for more details. | |
| * | |
| * You should have received a copy of the GNU Lesser General Public License | |
| * along with this program. If not, see <https://www.gnu.org/licenses/>. | |
| */ | |
| #ifdef __CBINDGEN_ALIGNED | |
| #undef __CBINDGEN_ALIGNED | |
| #endif | |
| #define __CBINDGEN_ALIGNED(n) __attribute__((aligned(n))) | |
| #ifndef LIBPATHRS_H | |
| #define LIBPATHRS_H | |
| /* | |
| * WARNING: This file was auto-generated by rust-cbindgen. Don't modify it. | |
| * Instead, re-generate it with: | |
| * % cbindgen -c cbindgen.toml -o include/pathrs.h | |
| */ | |
| #include <stdarg.h> | |
| #include <stdbool.h> | |
| #include <stddef.h> | |
| #include <stdint.h> | |
| #include <stdlib.h> | |
| #include <sys/types.h> | |
| /* | |
| * Returns whether the given numerical value is a libpathrs error (which can be | |
| * passed to pathrs_errorinfo()). Users are recommended to use this instead of | |
| * a bare `<0` comparison because some functions may return a negative number | |
| * even in a success condition. | |
| */ | |
| #define IS_PATHRS_ERR(ret) ((ret) < __PATHRS_MAX_ERR_VALUE) | |
| /* | |
| * Used to construct pathrs_proc_base_t values for a PID (or TID). Passing | |
| * PATHRS_PROC_PID(pid) to pathrs_proc_*() as pathrs_proc_base_t will cause | |
| * libpathrs to use /proc/$pid as the base of the operation. | |
| * | |
| * This is essentially functionally equivalent to prefixing "$pid/" to the | |
| * subpath argument and using PATHRS_PROC_ROOT. | |
| * | |
| * Note that this operation is inherently racy -- the process referenced by this | |
| * PID may have died and the PID recycled with a different process. In | |
| * principle, this means that it is only really safe to use this with: | |
| * | |
| * - PID 1 (the init process), as that PID cannot ever get recycled. | |
| * - Your current PID (though you should just use PATHRS_PROC_SELF). | |
| * - Your current TID (though you should just use PATHRS_PROC_THREAD_SELF), | |
| * or _possibly_ other TIDs in your thread-group if you are absolutely sure | |
| * they have not been reaped (typically with pthread_join(3), though there | |
| * are other ways). | |
| * - PIDs of child processes (as long as you are sure that no other part of | |
| * your program incorrectly catches or ignores SIGCHLD, and that you do it | |
| * *before* you call wait(2) or any equivalent method that could reap | |
| * zombies). | |
| * | |
| * Outside of those specific uses, users should probably avoid using this. | |
| */ | |
| #define PATHRS_PROC_PID(n) (__PATHRS_PROC_TYPE_PID | (n)) | |
| /* | |
| * A sentinel value to tell `pathrs_proc_*` methods to use the default procfs | |
| * root handle (which may be globally cached). | |
| */ | |
| #define PATHRS_PROC_DEFAULT_ROOTFD -9 /* (-EBADF) */ | |
| /** | |
| * Bits in `pathrs_proc_base_t` that indicate the type of the base value. | |
| * | |
| * NOTE: This is used internally by libpathrs. You should avoid using this | |
| * macro if possible. | |
| */ | |
| #define __PATHRS_PROC_TYPE_MASK 18446744069414584320ull | |
| /** | |
| * Bits in `pathrs_proc_base_t` that must be set for `/proc/$pid` values. Don't | |
| * use this directly, instead use `PATHRS_PROC_PID(n)` to convert a PID to an | |
| * appropriate `pathrs_proc_base_t` value. | |
| * | |
| * NOTE: This is used internally by libpathrs. You should avoid using this | |
| * macro if possible. | |
| */ | |
| #define __PATHRS_PROC_TYPE_PID 9223372036854775808ull | |
| /** | |
| * Construct a completely unmasked procfs handle. | |
| * | |
| * This is equivalent to [`ProcfsHandleBuilder::unmasked`], and is meant as | |
| * a flag argument to [`ProcfsOpenFlags`] (the `flags` field in `struct | |
| * pathrs_procfs_open_how`) for use with pathrs_procfs_open(). | |
| */ | |
| #define PATHRS_PROCFS_NEW_UNMASKED 1 | |
| /** | |
| * Indicate what base directory should be used when doing operations with | |
| * `pathrs_proc_*`. In addition to the values defined here, the following | |
| * macros can be used for other values: | |
| * | |
| * * `PATHRS_PROC_PID(pid)` refers to the `/proc/<pid>` directory for the | |
| * process with PID (or TID) `pid`. | |
| * | |
| * Note that this operation is inherently racy and should probably avoided | |
| * for most uses -- see the block comment above `PATHRS_PROC_PID(n)` for | |
| * more details. | |
| * | |
| * Unknown values will result in an error being returned. | |
| */ | |
| enum pathrs_proc_base_t { | |
| /** | |
| * Use /proc. Note that this mode may be more expensive because we have | |
| * to take steps to try to avoid leaking unmasked procfs handles, so you | |
| * should use PATHRS_PROC_SELF if you can. | |
| */ | |
| PATHRS_PROC_ROOT = 18446744067006164835ull, | |
| /** | |
| * Use /proc/self. For most programs, this is the standard choice. | |
| */ | |
| PATHRS_PROC_SELF = 18446744065272536607ull, | |
| /** | |
| * Use /proc/thread-self. In multi-threaded programs where one thread has a | |
| * different CLONE_FS, it is possible for /proc/self to point the wrong | |
| * thread and so /proc/thread-self may be necessary. | |
| * | |
| * NOTE: Using /proc/thread-self may require care if used from languages | |
| * where your code can change threads without warning and old threads can | |
| * be killed (such as Go -- where you want to use runtime.LockOSThread). | |
| */ | |
| PATHRS_PROC_THREAD_SELF = 18446744066171166239ull, | |
| }; | |
| typedef uint64_t pathrs_proc_base_t; | |
| typedef struct { | |
| uint64_t flags; | |
| } pathrs_procfs_open_how; | |
| /** | |
| * Attempts to represent a Rust Error type in C. This structure must be freed | |
| * using pathrs_errorinfo_free(). | |
| */ | |
| typedef struct __CBINDGEN_ALIGNED(8) { | |
| /** | |
| * Raw errno(3) value of the underlying error (or 0 if the source of the | |
| * error was not due to a syscall error). | |
| */ | |
| uint64_t saved_errno; | |
| /** | |
| * Textual description of the error. | |
| */ | |
| const char *description; | |
| } pathrs_error_t; | |
| /** | |
| * Represents the version information of the runtime libpathrs library. | |
| */ | |
| typedef struct { | |
| /** | |
| * Pointer to static version string containing the crate version. | |
| */ | |
| const char * version_string; | |
| } pathrs_version_info_t; | |
| /** | |
| * The smallest return value which cannot be a libpathrs error ID. | |
| * | |
| * While all libpathrs error IDs are negative numbers, some functions may | |
| * return a negative number in a success scenario. This macro defines the high | |
| * range end of the numbers that can be used as an error ID. Don't use this | |
| * value directly, instead use `IS_PATHRS_ERR(ret)` to check if a returned | |
| * value is an error or not. | |
| * | |
| * NOTE: This is used internally by libpathrs. You should avoid using this | |
| * macro if possible. | |
| */ | |
| #define __PATHRS_MAX_ERR_VALUE -4096 | |
| /** | |
| * Open a root handle. | |
| * | |
| * The provided path must be an existing directory. | |
| * | |
| * Note that root handles are not special -- this function is effectively | |
| * equivalent to | |
| * | |
| * ```c | |
| * fd = open(path, O_PATH|O_DIRECTORY); | |
| * ``` | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns a file descriptor that can be used as a | |
| * root handle in subsequent pathrs_inroot_* operations. The file descriptor | |
| * will have the `O_CLOEXEC` flag automatically applied. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_open_root(const char *path); | |
| /** | |
| * "Upgrade" an O_PATH file descriptor to a usable fd, suitable for reading and | |
| * writing. This does not consume the original file descriptor. (This can be | |
| * used with non-O_PATH file descriptors as well.) | |
| * | |
| * It should be noted that the use of O_CREAT *is not* supported (and will | |
| * result in an error). Handles only refer to *existing* files. Instead you | |
| * need to use pathrs_inroot_creat(). | |
| * | |
| * In addition, O_NOCTTY is automatically set when opening the path. If you | |
| * want to use the path as a controlling terminal, you will have to do | |
| * ioctl(fd, TIOCSCTTY, 0) yourself. | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns a file descriptor. The file descriptor | |
| * will have the `O_CLOEXEC` flag automatically applied. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_reopen(int fd, uint64_t flags); | |
| /** | |
| * Resolve the given path within the rootfs referenced by root_fd. The path | |
| * *must already exist*, otherwise an error will occur. | |
| * | |
| * All symlinks (including trailing symlinks) are followed, but they are | |
| * resolved within the rootfs. If you wish to open a handle to the symlink | |
| * itself, use pathrs_inroot_resolve_nofollow(). | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns an O_PATH file descriptor referencing the | |
| * resolved path. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_inroot_resolve(int root_fd, const char *path); | |
| /** | |
| * pathrs_inroot_resolve_nofollow() is effectively an O_NOFOLLOW version of | |
| * pathrs_inroot_resolve(). Their behaviour is identical, except that | |
| * *trailing* symlinks will not be followed. If the final component is a | |
| * trailing symlink, an O_PATH|O_NOFOLLOW handle to the symlink itself is | |
| * returned. | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns an O_PATH file descriptor referencing the | |
| * resolved path. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_inroot_resolve_nofollow(int root_fd, const char *path); | |
| /** | |
| * pathrs_inroot_open() is effectively shorthand for pathrs_inroot_resolve() | |
| * followed by pathrs_reopen(). If you only need to open a path and don't care | |
| * about re-opening it later, this can be slightly more efficient than the | |
| * alternative for the openat2-based resolver as it doesn't require allocating | |
| * an extra file descriptor. For languages where C FFI is expensive (such as | |
| * Go), using this also saves a function call. | |
| * | |
| * If flags contains O_NOFOLLOW, the behaviour is like that of | |
| * pathrs_inroot_resolve_nofollow() followed by pathrs_reopen(). | |
| * | |
| * In addition, O_NOCTTY is automatically set when opening the path. If you | |
| * want to use the path as a controlling terminal, you will have to do | |
| * ioctl(fd, TIOCSCTTY, 0) yourself. | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns a file descriptor. The file descriptor | |
| * will have the `O_CLOEXEC` flag automatically applied. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_inroot_open(int root_fd, const char *path, uint64_t flags); | |
| /** | |
| * Get the target of a symlink within the rootfs referenced by root_fd. | |
| * | |
| * NOTE: The returned path is not modified to be "safe" outside of the | |
| * root. You should not use this path for doing further path lookups -- use | |
| * pathrs_inroot_resolve() instead. | |
| * | |
| * This method is just shorthand for: | |
| * | |
| * ```c | |
| * int linkfd = pathrs_inroot_resolve_nofollow(rootfd, path); | |
| * if (IS_PATHRS_ERR(linkfd)) { | |
| * liberr = fd; // for use with pathrs_errorinfo() | |
| * goto err; | |
| * } | |
| * copied = readlinkat(linkfd, "", linkbuf, linkbuf_size); | |
| * close(linkfd); | |
| * ``` | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function copies the symlink contents to `linkbuf` (up to | |
| * `linkbuf_size` bytes) and returns the full size of the symlink path buffer. | |
| * This function will not copy the trailing NUL byte, and the return size does | |
| * not include the NUL byte. A `NULL` `linkbuf` or invalid `linkbuf_size` are | |
| * treated as zero-size buffers. | |
| * | |
| * NOTE: Unlike readlinkat(2), in the case where linkbuf is too small to | |
| * contain the symlink contents, pathrs_inroot_readlink() will return *the | |
| * number of bytes it would have copied if the buffer was large enough*. This | |
| * matches the behaviour of pathrs_proc_readlink(). | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_inroot_readlink(int root_fd, | |
| const char *path, | |
| char *linkbuf, | |
| size_t linkbuf_size); | |
| /** | |
| * Rename a path within the rootfs referenced by root_fd. The flags argument is | |
| * identical to the renameat2(2) flags that are supported on the system. | |
| * | |
| * # Future-proofing | |
| * | |
| * This function takes two `root_fd` arguments in order for future extensions | |
| * to be able to use them, but callers must specify the same *value* for both | |
| * arguments. (NOTE: This is not referring to the same underlying file, the | |
| * actual file descriptor number must be identical.) | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns 0. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_inroot_rename(int old_root_fd, | |
| const char *old_path, | |
| int new_root_fd, | |
| const char *new_path, | |
| uint64_t flags); | |
| /** | |
| * Remove the empty directory at path within the rootfs referenced by root_fd. | |
| * | |
| * The semantics are effectively equivalent to unlinkat(..., AT_REMOVEDIR). | |
| * This function will return an error if the path doesn't exist, was not a | |
| * directory, or was a non-empty directory. | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns 0. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_inroot_rmdir(int root_fd, const char *path); | |
| /** | |
| * Remove the file (a non-directory inode) at path within the rootfs referenced | |
| * by root_fd. | |
| * | |
| * The semantics are effectively equivalent to unlinkat(..., 0). This function | |
| * will return an error if the path doesn't exist or was a directory. | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns 0. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_inroot_unlink(int root_fd, const char *path); | |
| /** | |
| * Recursively delete the path and any children it contains if it is a | |
| * directory. The semantics are equivalent to `rm -r`. | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns 0. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_inroot_remove_all(int root_fd, const char *path); | |
| /** | |
| * Create a new regular file within the rootfs referenced by root_fd. This is | |
| * effectively an O_CREAT operation, and so (unlike pathrs_inroot_resolve()), | |
| * this function can be used on non-existent paths. | |
| * | |
| * If you want to ensure the creation is a new file, use O_EXCL. | |
| * | |
| * If you want to create a file without opening a handle to it, you can do | |
| * pathrs_inroot_mknod(root_fd, path, S_IFREG|mode, 0) instead. | |
| * | |
| * As with pathrs_reopen(), O_NOCTTY is automatically set when opening the | |
| * path. If you want to use the path as a controlling terminal, you will have | |
| * to do ioctl(fd, TIOCSCTTY, 0) yourself. | |
| * | |
| * NOTE: Unlike O_CREAT, pathrs_inroot_creat() will return an error if the | |
| * final component is a dangling symlink. O_CREAT will create such files, and | |
| * while openat2 does support this it would be difficult to implement this in | |
| * the emulated resolver. | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns a file descriptor to the requested file. | |
| * The open flags are based on the provided flags. The file descriptor will | |
| * have the `O_CLOEXEC` flag automatically applied. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_inroot_creat(int root_fd, | |
| const char *path, | |
| uint64_t flags, | |
| unsigned int mode); | |
| /** | |
| * Create a new directory within the rootfs referenced by root_fd. | |
| * | |
| * This is shorthand for pathrs_inroot_mknod(root_fd, path, S_IFDIR|mode, 0). | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns 0. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_inroot_mkdir(int root_fd, const char *path, unsigned int mode); | |
| /** | |
| * Create a new directory (and any of its path components if they don't exist) | |
| * within the rootfs referenced by root_fd. | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns an O_DIRECTORY file descriptor to the | |
| * newly created directory. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_inroot_mkdir_all(int root_fd, const char *path, unsigned int mode); | |
| /** | |
| * Create a inode within the rootfs referenced by root_fd. The type of inode to | |
| * be created is configured using the S_IFMT bits in mode (a-la mknod(2)). | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns 0. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_inroot_mknod(int root_fd, | |
| const char *path, | |
| unsigned int mode, | |
| dev_t dev); | |
| /** | |
| * Create a symlink within the rootfs referenced by root_fd. Note that the | |
| * symlink target string is not modified when creating the symlink. | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns 0. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_inroot_symlink(const char *target, | |
| int root_fd, | |
| const char *linkpath); | |
| /** | |
| * Create a hardlink within the rootfs referenced by root_fd. Both the hardlink | |
| * path and target are resolved within the rootfs. | |
| * | |
| * # Future-proofing | |
| * | |
| * This function takes two `root_fd` arguments in order for future extensions | |
| * to be able to use them, but callers must specify the same *value* for both | |
| * arguments. (NOTE: This is not referring to the same underlying file, the | |
| * actual file descriptor number must be identical.) | |
| * | |
| * The `flags` argument is included for future extensions and must be 0. | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns 0. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_inroot_hardlink(int old_root_fd, | |
| const char *old_path, | |
| int new_root_fd, | |
| const char *new_path, | |
| uint64_t flags); | |
| /** | |
| * Create a new (custom) procfs root handle. | |
| * | |
| * This is effectively a C wrapper around [`ProcfsHandleBuilder`], allowing you | |
| * to create a custom procfs root handle that can be used with other | |
| * `pathrs_proc_*at` methods. | |
| * | |
| * While most users should just use `PATHRS_PROC_DEFAULT_ROOTFD` (or the | |
| * non-`at` variants of `pathrs_proc_*`), creating an unmasked procfs root | |
| * handle (using `PATHRS_PROCFS_NEW_UNMASKED`) can be useful for programs that | |
| * need to operate on a lot of global procfs files. (Note that accessing global | |
| * procfs files does not *require* creating a custom procfs handle -- | |
| * `pathrs_proc_*` will automatically create a global-friendly handle | |
| * internally when necessary but will close it immediately after operating on | |
| * it.) | |
| * | |
| * # Extensible Structs | |
| * | |
| * The [`ProcfsOpenHow`] (`struct pathrs_procfs_open_how`) argument is | |
| * designed to be extensible, modelled after the extensible structs scheme used | |
| * by Linux (for syscalls such as [clone3(2)], [openat2(2)] and other such | |
| * syscalls). Normally one would use symbol versioning to achieve this, but | |
| * unfortunately Rust's symbol versioning support is incredibly primitive (one | |
| * might even say "non-existent") and so this system is more robust, even if | |
| * the calling convention is a little strange for userspace libraries. | |
| * | |
| * In addition to a pointer argument, the caller must also provide the size of | |
| * the structure it is passing. By providing this information, it is possible | |
| * for `pathrs_procfs_open()` to provide both forwards- and | |
| * backwards-compatibility, with size acting as an implicit version number. | |
| * (Because new extension fields will always be appended, the structure size | |
| * will always increase.) | |
| * | |
| * If we let `usize` be the structure specified by the caller, and `lsize` be | |
| * the size of the structure internal to libpathrs, then there are three cases | |
| * to consider: | |
| * | |
| * * If `usize == lsize`, then there is no version mismatch and the structure | |
| * provided by the caller can be used verbatim. | |
| * * If `usize < lsize`, then there are some extension fields which libpathrs | |
| * supports that the caller does not. Because a zero value in any added | |
| * extension field signifies a no-op, libpathrs treats all of the extension | |
| * fields not provided by the caller as having zero values. This provides | |
| * backwards-compatibility. | |
| * * If `usize > lsize`, then there are some extension fields which the caller | |
| * is aware of but this version of libpathrs does not support. Because any | |
| * extension field must have its zero values signify a no-op, libpathrs can | |
| * safely ignore the unsupported extension fields if they are all-zero. If | |
| * any unsupported extension fields are nonzero, then an `E2BIG` error is | |
| * returned. This provides forwards-compatibility. | |
| * | |
| * Because the definition of `struct pathrs_procfs_open_how` may open in the | |
| * future | |
| * | |
| * Because the definition of `struct pathrs_procfs_open_how` may change in the | |
| * future (with new fields being added when headers are updated), callers | |
| * should zero-fill the structure to ensure that recompiling the program with | |
| * new headers will not result in spurious errors at run time. The simplest | |
| * way is to use a designated initialiser: | |
| * | |
| * ```c | |
| * struct pathrs_procfs_open_how how = { | |
| * .flags = PATHRS_PROCFS_NEW_UNMASKED, | |
| * }; | |
| * ``` | |
| * | |
| * or explicitly using `memset(3)` or similar: | |
| * | |
| * ```c | |
| * struct pathrs_procfs_open_how how; | |
| * memset(&how, 0, sizeof(how)); | |
| * how.flags = PATHRS_PROCFS_NEW_UNMASKED; | |
| * ``` | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns *either* a file descriptor *or* | |
| * `PATHRS_PROC_DEFAULT_ROOTFD` (this is a negative number, equal to `-EBADF`). | |
| * The file descriptor will have the `O_CLOEXEC` flag automatically applied. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| * | |
| * [clone3(2)]: https://www.man7.org/linux/man-pages/man2/clone3.2.html | |
| * [openat2(2)]: https://www.man7.org/linux/man-pages/man2/openat2.2.html | |
| */ | |
| int pathrs_procfs_open(const pathrs_procfs_open_how *args, size_t size); | |
| /** | |
| * `pathrs_proc_open` but with a caller-provided file descriptor for `/proc`. | |
| * | |
| * Internally, `pathrs_proc_open` will attempt to use a cached copy of a very | |
| * restricted `/proc` handle (a detached mount object with `subset=pid` and | |
| * `hidepid=4`). If a user requests a global `/proc` file, a temporary handle | |
| * capable of accessing global files is created and destroyed after the | |
| * operation completes. | |
| * | |
| * For most users, this is more than sufficient. However, if a user needs to | |
| * operate on many global `/proc` files, the cost of creating handles can get | |
| * quite expensive. `pathrs_proc_openat` allows a user to manually manage the | |
| * global-friendly `/proc` handle. Note that passing a `subset=pid` file | |
| * descriptor to `pathrs_proc_openat` will *not* stop the automatic creation of | |
| * a global-friendly handle internally if necessary. | |
| * | |
| * In order to get the behaviour of `pathrs_proc_open`, you can pass the | |
| * special value `PATHRS_PROC_DEFAULT_ROOTFD` (`-EBADF`) as the `proc_rootfd` | |
| * argument. | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns a file descriptor. The file descriptor | |
| * will have the `O_CLOEXEC` flag automatically applied. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_proc_openat(int proc_rootfd, | |
| pathrs_proc_base_t base, | |
| const char *path, | |
| uint64_t flags); | |
| /** | |
| * Safely open a path inside a `/proc` handle. | |
| * | |
| * Any bind-mounts or other over-mounts will (depending on what kernel features | |
| * are available) be detected and an error will be returned. Non-trailing | |
| * symlinks are followed but care is taken to ensure the symlinks are | |
| * legitimate. | |
| * | |
| * Unless you intend to open a magic-link, `O_NOFOLLOW` should be set in flags. | |
| * Lookups with `O_NOFOLLOW` are guaranteed to never be tricked by bind-mounts | |
| * (on new enough Linux kernels). | |
| * | |
| * If you wish to resolve a magic-link, you need to unset `O_NOFOLLOW`. | |
| * Unfortunately (if libpathrs is using the regular host `/proc` mount), this | |
| * lookup mode cannot protect you against an attacker that can modify the mount | |
| * table during this operation. | |
| * | |
| * NOTE: Instead of using paths like `/proc/thread-self/fd`, `base` is used to | |
| * indicate what "base path" inside procfs is used. For example, to re-open a | |
| * file descriptor: | |
| * | |
| * ```c | |
| * fd = pathrs_proc_open(PATHRS_PROC_THREAD_SELF, "fd/101", O_RDWR); | |
| * if (IS_PATHRS_ERR(fd)) { | |
| * liberr = fd; // for use with pathrs_errorinfo() | |
| * goto err; | |
| * } | |
| * ``` | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns a file descriptor. The file descriptor | |
| * will have the `O_CLOEXEC` flag automatically applied. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_proc_open(pathrs_proc_base_t base, const char *path, uint64_t flags); | |
| /** | |
| * `pathrs_proc_readlink` but with a caller-provided file descriptor for | |
| * `/proc`. | |
| * | |
| * See the documentation of pathrs_proc_openat() for when this API might be | |
| * useful. | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function copies the symlink contents to `linkbuf` (up to | |
| * `linkbuf_size` bytes) and returns the full size of the symlink path buffer. | |
| * This function will not copy the trailing NUL byte, and the return size does | |
| * not include the NUL byte. A `NULL` `linkbuf` or invalid `linkbuf_size` are | |
| * treated as zero-size buffers. | |
| * | |
| * NOTE: Unlike readlinkat(2), in the case where linkbuf is too small to | |
| * contain the symlink contents, pathrs_proc_readlink() will return *the number | |
| * of bytes it would have copied if the buffer was large enough*. This matches | |
| * the behaviour of pathrs_inroot_readlink(). | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_proc_readlinkat(int proc_rootfd, | |
| pathrs_proc_base_t base, | |
| const char *path, | |
| char *linkbuf, | |
| size_t linkbuf_size); | |
| /** | |
| * Safely read the contents of a symlink inside `/proc`. | |
| * | |
| * As with `pathrs_proc_open`, any bind-mounts or other over-mounts will | |
| * (depending on what kernel features are available) be detected and an error | |
| * will be returned. Non-trailing symlinks are followed but care is taken to | |
| * ensure the symlinks are legitimate. | |
| * | |
| * This function is effectively shorthand for | |
| * | |
| * ```c | |
| * fd = pathrs_proc_open(base, path, O_PATH|O_NOFOLLOW); | |
| * if (IS_PATHRS_ERR(fd)) { | |
| * liberr = fd; // for use with pathrs_errorinfo() | |
| * goto err; | |
| * } | |
| * copied = readlinkat(fd, "", linkbuf, linkbuf_size); | |
| * close(fd); | |
| * ``` | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function copies the symlink contents to `linkbuf` (up to | |
| * `linkbuf_size` bytes) and returns the full size of the symlink path buffer. | |
| * This function will not copy the trailing NUL byte, and the return size does | |
| * not include the NUL byte. A `NULL` `linkbuf` or invalid `linkbuf_size` are | |
| * treated as zero-size buffers. | |
| * | |
| * NOTE: Unlike readlinkat(2), in the case where linkbuf is too small to | |
| * contain the symlink contents, pathrs_proc_readlink() will return *the number | |
| * of bytes it would have copied if the buffer was large enough*. This matches | |
| * the behaviour of pathrs_inroot_readlink(). | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_proc_readlink(pathrs_proc_base_t base, | |
| const char *path, | |
| char *linkbuf, | |
| size_t linkbuf_size); | |
| /** | |
| * Retrieve error information about an error id returned by a pathrs operation. | |
| * | |
| * Whenever an error occurs with libpathrs, a negative number describing that | |
| * error (the error id) is returned. pathrs_errorinfo() is used to retrieve | |
| * that information: | |
| * | |
| * ```c | |
| * fd = pathrs_inroot_resolve(root, "/foo/bar"); | |
| * if (IS_PATHRS_ERR(fd)) { | |
| * // fd is an error id | |
| * pathrs_error_t *error = pathrs_errorinfo(fd); | |
| * // ... print the error information ... | |
| * pathrs_errorinfo_free(error); | |
| * } | |
| * ``` | |
| * | |
| * Once pathrs_errorinfo() is called for a particular error id, that error id | |
| * is no longer valid and should not be used for subsequent pathrs_errorinfo() | |
| * calls. | |
| * | |
| * Error ids are only unique from one another until pathrs_errorinfo() is | |
| * called, at which point the id can be reused for subsequent errors. The | |
| * precise format of error ids is completely opaque and they should never be | |
| * compared directly or used for anything other than with pathrs_errorinfo(). | |
| * | |
| * Error ids are not thread-specific and thus pathrs_errorinfo() can be called | |
| * on a different thread to the thread where the operation failed (this is of | |
| * particular note to green-thread language bindings like Go, where this is | |
| * important). | |
| * | |
| * # Return Value | |
| * | |
| * If there was a saved error with the provided id, a pathrs_error_t is | |
| * returned describing the error. Use pathrs_errorinfo_free() to free the | |
| * associated memory once you are done with the error. | |
| */ | |
| pathrs_error_t *pathrs_errorinfo(int err_id); | |
| /** | |
| * Free the pathrs_error_t object returned by pathrs_errorinfo(). | |
| */ | |
| void pathrs_errorinfo_free(pathrs_error_t *ptr); | |
| /** | |
| * Return the version information of the libpathrs library at runtime. | |
| * | |
| * This API is designed to be extensible. The caller must pass a pointer to a | |
| * contiguous buffer `dst` that is large enough to store `dst_size` bytes. This | |
| * buffer is then filled with version information. If the library has less data | |
| * than the given buffer size, the trailing bytes are zero-filled. If the | |
| * library has more data than the given buffer size the data is truncated and | |
| * (if the truncated data contained non-zero values), the return value | |
| * indicates what buffer size is needed to contain all version data. | |
| * | |
| * # Return Value | |
| * | |
| * On success, this function returns `0` or (if the version data was truncated) | |
| * a positive integer that is the size of the buffer needed to store all data. | |
| * | |
| * If an error occurs, this function will return a negative error code. To | |
| * retrieve information about the error (such as a string describing the error, | |
| * the system errno(7) value associated with the error, etc), use | |
| * pathrs_errorinfo(). | |
| */ | |
| int pathrs_version(pathrs_version_info_t *dst, size_t dst_size); | |
| #endif /* LIBPATHRS_H */ | |
| #ifdef __CBINDGEN_ALIGNED | |
| #undef __CBINDGEN_ALIGNED | |
| #endif |