blob: 6b86e1590eabd206c3f50bc6c1007be388ee8d17 [file] [edit]
// 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