diff options
Diffstat (limited to '')
| -rw-r--r-- | libsyscalls.h | 1406 |
1 files changed, 1335 insertions, 71 deletions
diff --git a/libsyscalls.h b/libsyscalls.h index 066de20..caf4a4b 100644 --- a/libsyscalls.h +++ b/libsyscalls.h @@ -77,6 +77,19 @@ enum libsyscalls_arch { LIBSYSCALLS_ARCH_XTENSA }; +/** + * Data types + * + * Be aware that some values in this enumeration may have + * multiple names, especially structs and unions: up to + * one name per combination of operating system and + * architecture. Each value may have very different + * meaning per name. This may be done because the number + * of available values is limited. Also note that functions + * may return values that do not have a name at all, these + * are anonymous structs and unions whose definitions also + * depend on the operating system and architecture. + */ enum libsyscalls_datatype { /* Type renaming, these macros will be undefined later */ @@ -100,13 +113,14 @@ enum libsyscalls_datatype { X(LIBSYSCALLS_TYPE_DYNAMIC ## SUFFIX,, "(undetermined type)") D\ /* the system call should never returned to the calling process (return to tracer is usually expected) */\ X(LIBSYSCALLS_TYPE_NO_RETURN ## SUFFIX,, "no_return") D\ - /* either used as return type or to skip a register in the parameters + /* either used as return type, to skip a register in the parameters * (do not dismiss this, on some architectures a system call * may need padding with dummy arguments to align latter * register pairs; an application printing the system call * must choose between omitting, printing the argument, or * indicating that there is a dummy parameter (of course - * the latter two can be combined)) */\ + * the latter two can be combined)), or to add padding + * (or reserved space for future expansion) to a struct */\ X(LIBSYSCALLS_TYPE_VOID ## SUFFIX,, "void") #define LIBSYSCALLS_LIST_SPLIT_PRIMITIVES(X, SUFFIX, D, FIRST)\ @@ -263,166 +277,1183 @@ enum libsyscalls_datatype { #undef LIBSYSCALLS_TYPE_CHAR_ARRAY_UNKNOWN_FILL }; +/** + * Broad classification on system calls + */ enum libsyscalls_syscall_category { + /** + * The library knows about the system calls but + * has not yet implemented detailed information + * about the system call + */ LIBSYSCALLS_CAT_SUPPORT_PENDING, + + /** + * The system call has a name but is not implemented + * in the kernel, and thus does not have an ABI either + * + * Be aware that this information may be outdated + * and that `LIBSYSCALLS_CAT_SUPPORT_PENDING` might + * actually be more appropriate + * + * This value is not used for system calls that have + * be removed, those are still described as if still + * implemented by the kernel + */ LIBSYSCALLS_CAT_NOT_IMPLEMENTED, - LIBSYSCALLS_CAT_NETWORK_ENABLED_IPC, - LIBSYSCALLS_CAT_IPC, - LIBSYSCALLS_CAT_FILESYSTEM, - LIBSYSCALLS_CAT_FILE_DESCRIPTORS, - LIBSYSCALLS_CAT_PROCESSES, - LIBSYSCALLS_CAT_LOGGING, - LIBSYSCALLS_CAT_TIME, - LIBSYSCALLS_CAT_SIGNALS, - LIBSYSCALLS_CAT_MEMORY, - LIBSYSCALLS_CAT_SYSTEM, - LIBSYSCALLS_CAT_SCHEDULING + + LIBSYSCALLS_CAT_NETWORK_ENABLED_IPC, /**< See enum libsyscalls_network_enabled_ipc_syscall_subcategory */ + LIBSYSCALLS_CAT_IPC, /**< See enum libsyscalls_ipc_syscall_subcategory */ + LIBSYSCALLS_CAT_FILESYSTEM, /**< See enum libsyscalls_filesystem_syscall_subcategory */ + LIBSYSCALLS_CAT_FILE_DESCRIPTORS, /**< See enum libsyscalls_file_descriptors_syscall_subcategory */ + LIBSYSCALLS_CAT_PROCESSES, /**< See enum libsyscalls_processes_syscall_subcategory */ + LIBSYSCALLS_CAT_LOGGING, /**< See enum libsyscalls_logging_syscall_subcategory */ + LIBSYSCALLS_CAT_TIME, /**< See enum libsyscalls_time_syscall_subcategory */ + LIBSYSCALLS_CAT_SIGNALS, /**< See enum libsyscalls_singals_syscall_subcategory */ + LIBSYSCALLS_CAT_MEMORY, /**< See enum libsyscalls_memory_syscall_subcategory */ + LIBSYSCALLS_CAT_SYSTEM, /**< See enum libsyscalls_system_syscall_subcategory */ + LIBSYSCALLS_CAT_SCHEDULING /**< See enum libsyscalls_scheduling_syscall_subcategory */ }; -/* IPC that can but does not have to be over a network, - * "bind" system calls can create inodes in the file system */ +/** + * Interprocess communication system calls that may + * either communicate other the a network or locally + * on the machine + * + * Generally these do not affect the filesystem, the only exception + * is LIBSYSCALLS_NETWORK_ENABLED_IPC_SUBCAT_BIND may create index + * nodes and LIBSYSCALLS_NETWORK_ENABLED_IPC_SUBCAT_CONNECT may + * access the index nodes + * + * May system calls used for this class of communication + * objects used LIBSYSCALLS_CAT_FILE_DESCRIPTORS system calls + */ enum libsyscalls_network_enabled_ipc_syscall_subcategory { + /** + * System calls that create a non-persistent + * communication object (such as a file descriptor) + * for this category of interprocess communication; + * meaning a file descriptor or similar object + * that causes the shared resource to be deallocated + * once all instances of the object has been released + * + * socket(2) is an example of a system call in this + * category + */ + LIBSYSCALLS_NETWORK_ENABLED_IPC_SUBCAT_CREATE, + + /** + * System calls that accept incoming connections and + * create a new communication object, or rejects them + * + * accept(2) is an example of a system call in this + * category + */ LIBSYSCALLS_NETWORK_ENABLED_IPC_SUBCAT_ACCEPT, + + /** + * System calls that enable a communication object to + * use LIBSYSCALLS_NETWORK_ENABLED_IPC_SUBCAT_ACCEPT + * system calls + * + * listen(2) is an example of a system call in this + * category + */ LIBSYSCALLS_NETWORK_ENABLED_IPC_SUBCAT_LISTEN, + + /** + * System calls that assigns a communication object + * to an local address, this can be a filesystem path + * or a network address, or a local identifier; this + * system calls gives the communication an address, + * and may create an index node on the file system + * + * bind(2) is an example of a system call in this + * category + */ LIBSYSCALLS_NETWORK_ENABLED_IPC_SUBCAT_BIND, + + /** + * System calls that attaches a communication object + * to an local address, this can be a filesystem path + * or a network address, or a local identifier; this + * system calls tells the kernel which other communication + * object the object shall communicate with, it does + * not give explicitly the communication object an + * address, however the kernel may give it one if one + * has not already be assigned + * + * connect(2) is an example of a system call in this + * category + */ LIBSYSCALLS_NETWORK_ENABLED_IPC_SUBCAT_CONNECT, + + /** + * System calls that inspect details about a + * communication object + * + * getsockname(2), getpeername(2), and getsockopt(2) + * are examples of system calls in this category + */ LIBSYSCALLS_NETWORK_ENABLED_IPC_SUBCAT_STAT }; +/** + * Interprocess communication system calls that always + * local to the machine or a networked filesystem + */ enum libsyscalls_ipc_syscall_subcategory { + /** + * System calls that create a non-persistent + * communication object (such as a file descriptor) + * for this category of interprocess communication; + * meaning a file descriptor or similar object + * that causes the shared resource to be deallocated + * once all instances of the object has been released + * + * pipe(2) and socketpair(2) are examples of system + * calls in this category + */ + LIBSYSCALLS_IPC_SUBCAT_CREATE, + + /** + * System calls that lock, unlock or inspects a lock + * on a file, for locks that are strictly advisory + * + * Note this information can be out of date and the + * system call may deal with mandatory file locks, + * for example since Linux 5.5, flock(2) has mandatory + * on some network file systems; the library does not + * take into consideration which version of the kernel + * is used, but assumes the latest version (of course + * the library may be out of date in regard to this + * information even if it is build to the latest kernel) + */ LIBSYSCALLS_IPC_SUBCAT_ADVISORY_FILE_LOCK, + + /** + * System calls that lock, unlock or inspects a lock + * on a file, for locks that are strictly mandatory + * + * Note this information can be out of date and the + * system call may deal with advisory file locks; the + * library does not take into consideration which + * version of the kernel is used, but assumes the latest + * version (of course the library may be out of date in + * regard to this information even if it is build to the + * latest kernel) + */ LIBSYSCALLS_IPC_SUBCAT_MANDATORY_FILE_LOCK, - LIBSYSCALLS_IPC_SUBCAT_FILE_LOCK, /* may or may not be advisory (e.g. flock(2) since Linux 5.5) */ - LIBSYSCALLS_IPC_SUBCAT_CONTROL, /* includes creation, deletion, and stat */ + + /** + * System calls that lock, unlock or inspects a lock + * on a file, for locks that may be either advisory + * or mandatory + * + * flock(2) is an example of a system call in this + * category + */ + LIBSYSCALLS_IPC_SUBCAT_FILE_LOCK, + + /** + * System calls that create or deletes communication + * objects, or inspects or changes details about such + * objects + * + * Some system calls use LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_CREATE + * instead + * + * shmget(2), shmctl(2), mq_open(2), mq_unlink(2), + * mq_notify(2), and mq_getsetattr(2) are examples of + * system calls in this category + */ + LIBSYSCALLS_IPC_SUBCAT_CONTROL, + + /** + * System calls that attach to an existing IPC object + * + * shmat(2) is an example of a system call in this + * category + */ LIBSYSCALLS_IPC_SUBCAT_ATTACH, + + /** + * System calls that detach from an IPC object + * + * shmdt(2) is an example of a system call in this + * category + */ LIBSYSCALLS_IPC_SUBCAT_DETACH, + + /** + * Communication system calls that do not have a timeout + */ LIBSYSCALLS_IPC_SUBCAT_COMMUNICATE, + + /** + * Communication system calls that may have a relative + * or absolute timeout + */ + LIBSYSCALLS_IPC_SUBCAT_COMMUNICATE_WITH_TIMEOUT, + + /** + * Communication system calls that may have a relative timeout + */ LIBSYSCALLS_IPC_SUBCAT_COMMUNICATE_WITH_RELATIVE_TIMEOUT, + + /** + * Communication system calls that may have an absolute timeout + */ LIBSYSCALLS_IPC_SUBCAT_COMMUNICATE_WITH_ABSOLUTE_TIMEOUT }; -/* syscalls that can work on either paths or FDs ([1]) are located here */ +/** + * System calls that operate on the filesystem or can either + * operate on a filesystem or a file descriptor that does + * not involve the filesystem but is usually used with a + * filesystem; this category also include system calls that + * effect such systems but does not itself touch the filesystem + * but rather the process + * + * System calls in this category may have timeouts that may + * use relative or absolute time + */ enum libsyscalls_filesystem_syscall_subcategory { + /** + * System calls that retrieve the metadata of file + * + * stat(2) and fstatat(2) are examples of system calls + * in this category; fstat(2) however is not + */ LIBSYSCALLS_FILESYSTEM_SUBCAT_STAT, + + /** + * System calls that motifies the metadata of file + * + * chmod(2) and fchmodat(2) are examples of system calls + * in this category; fchmod(2) however is not + */ LIBSYSCALLS_FILESYSTEM_SUBCAT_MODIFY, - LIBSYSCALLS_FILESYSTEM_SUBCAT_SYNC, /* [1] some of these only work on file descriptors or memory maps */ + + /** + * System calls that commit changes to one or more files + * to the filesystem or mmap(2)ed anonymous memory + * + * sync(2), fsync(2), and msync(2) are examples of system + * calls in this category + */ + LIBSYSCALLS_FILESYSTEM_SUBCAT_SYNC, + + /** + * System calls the create named index nodes (links) + * on a filesystem + * + * Note that LIBSYSCALLS_NETWORK_ENABLED_IPC_SUBCAT_BIND + * system calls may also create links + * + * linkat(2), link(2), symlink(2), mknod(2), and mkdir(2) + * are examples of system calls in this category + */ LIBSYSCALLS_FILESYSTEM_SUBCAT_LINK, + + /** + * System calls the remove the path to an index node + * (removes a link) on a filesystem + * + * unlink(2) and rmdir(2) are examples of system calls + * in this category + */ LIBSYSCALLS_FILESYSTEM_SUBCAT_UNLINK, + + /** + * System calls that can operate both as + * LIBSYSCALLS_FILESYSTEM_SUBCAT_LINK and + * LIBSYSCALLS_FILESYSTEM_SUBCAT_UNLINK system calls, + * either one at a time or both at the same them + * + * rename(2) is an example of a system call in this + * category + */ LIBSYSCALLS_FILESYSTEM_SUBCAT_LINK_OR_UNLINK, - LIBSYSCALLS_FILESYSTEM_SUBCAT_UMASK, /* modifies the process, not the filesystem */ + + /** + * System calls that inspects or changes (or both + * at the same time) the process's or thread's + * umask, which affects the permissions that shall + * be eliminated when an index node or IPC object + * is created + * + * umask(2) is an example of a system call in this + * category + */ + LIBSYSCALLS_FILESYSTEM_SUBCAT_UMASK, + + /** + * System calles that in some way operate on + * mountpoints + * + * Note that some system calls in the category takes + * file descriptors as input or outputs + * + * mount(2), umount(2), and fsopen(2) are examples + * of system calls in this category + */ LIBSYSCALLS_FILESYSTEM_SUBCAT_MOUNTPOINT, + + /** + * System calls that retrieve the information about + * a mounted filesystem + * + * statfs(2) and the hypothetical fstatfsat(2) are + * examples of system calls in this category; + * fstatfs(2) however is not + */ LIBSYSCALLS_FILESYSTEM_SUBCAT_STATFS, + + /** + * System calls that make changes to a file + * content without requiring a file descriptor + * to it, however the system call may optionally + * accept a file descriptor + * + * Hypothetically an operating system could provide + * system calls that fall under this category and + * could be used to change the target path of an + * existing symbolic link + * + * truncate(2) and the hypothetical ftruncateat(2) + * are examples of system calls in this category; + * ftruncate(2) however is not + */ LIBSYSCALLS_FILESYSTEM_SUBCAT_WRITE, + + /** + * System calls that reads the contents of a file + * content without requiring a file descriptor + * to it, however the system call may optionally + * accept a file descriptor + * + * There currently are not such system calls, + * however, an operating system could not only + * provide such system call to read the contents + * of a file, but the read the file listing in + * a directory or the target path of a symbolic + * link + */ + LIBSYSCALLS_FILESYSTEM_SUBCAT_READ, + + /** + * System calls that retrieves the target path + * of a symbolic link without requiring a file + * descriptor to it, however the system call + * may optionally accept a file descriptor + * + * readlink(2) and the readlinkat(2) are examples + * of system calls in this category; the + * hypothetical freadlink(2) however is not + */ LIBSYSCALLS_FILESYSTEM_SUBCAT_READLINK, + + /** + * System calls that are used to monitoring + * changes and accesses to a file or filesystem + * + * This system calls may create file descriptors + * or use such file descriptors + * + * All inotify(7) and fanotify(7) system calls are + * examples of system calls in this category; + * mq_notify(2) however is not + */ LIBSYSCALLS_FILESYSTEM_SUBCAT_MONITOR, + + /** + * System calls that are used dealing with + * filesystem quotas + * + * This system calls may create file descriptors + * or use such file descriptors + * + * quotactl(2) is an example of system call in + * this category + */ LIBSYSCALLS_FILESYSTEM_SUBCAT_QUOTA }; -/* syscalls that work FDs but not paths are located here */ +/** + * System calls that operate on or create a file descriptor + * without fitting into a special category + * + * System calls in this category may have timeouts that may + * use relative or absolute time + */ enum libsyscalls_file_syscall_descriptors_subcategory { + /** + * System calls that retrieve metadata about a + * file through a file descriptor to it + * + * fstat(2) is an example of system call in + * this category + */ LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_STAT, + + /** + * System calls that modifies metadata about a + * file through a file descriptor to it + * + * fchmod(2) and fchown(2) are examples of + * system calls in this category + */ LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_MODIFY, - LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_DUP_OR_CLOSE, /* includes partial close (shutdown) */ + + /** + * System calls that duplicates or closes, + * possibly both at the same time, file descriptors, + * or closes the file descriptor in one or two + * directions + * + * dup(2), dup2(2), close(2), and shutdown(2) + * are examples of system calls in this category + */ + LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_DUP_OR_CLOSE, + + /** + * System calls that closes or unshares, + * possibly both at the same time, file descriptors, + * or closes the file descriptor in one or two + * directions + * + * close_range(2) is an example of a system call + * in this category + */ LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_CLOSE_OR_UNSHARE, - LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_READ, /* may have timeout */ - LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_READ_OR_PEEK, - LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_WRITE, /* may have timeout */ + + /** + * System calls that read from a file descriptor + * and changes the file offset while doing so + * + * For IPC objects that do not have a file offset + * (such as pipes and sockets) this means that + * read data is removed from the object + * + * read(2) is an example of a system call in this + * category + */ + LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_READ, + + /** + * System calls that read from a file descriptor + * without changing the file offset + * + * For IPC objects that do not have a file offset + * (such as pipes and sockets) this means that + * read data will remain in the object, and if + * the system calls is made again, the same data + * will be read + * + * pread(2) is an example of a system call in this + * category + */ + LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_PEEK, + + /** + * System calls that changes the file offset for + * a file descriptor without changing reading + * or writing + * + * lseek(2) is an example of a system call in this + * category + */ LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_SEEK, - LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_PEEK, /* may have timeout */ + + /** + * System calls that write to a file descriptor + * with or without changing the file offset + * + * write(2), pwrite(2), send(2), and sendto(2) + * are examples of system calls in this category + */ + LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_WRITE, + + /** + * System calls that read from a file descriptor + * with or without chaning the file offset + * + * recv(2) is an example of a system call in this + * category + */ + LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_READ_OR_PEEK, + + /** + * System calls that performs + * LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_READ actions + * on one file descriptor and + * LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_WRITE actions + * on another file descriptor, or possibly on the + * same file descriptor + */ LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_READ_AND_WRITE, + + /** + * System calls that performs + * LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_PEEK actions + * on one file descriptor and + * LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_WRITE actions + * on another file descriptor + * + * tee(2) is an example of a system call in this + * category + */ LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_PEEK_AND_WRITE, + + /** + * System calls that performs + * LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_READ_OR_PEEK + * actions on one file descriptor and + * LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_WRITE actions + * on another file descriptor + * + * splice(2) and sendfile(2) are examples of system + * calls in this category + */ LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_READ_OR_PEEK_AND_WRITE, + + /** + * System calls that performs + * LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_READ_OR_PEEK + * actions on a file descriptor while receiving + * metadata (this metadata does not need to fall + * under the category of LIBSYSCALLS_STAT_FILE_DESCRIPTORS, + * indeed it unlikely will) + * + * System calls under this category may receive + * new file descriptors + * + * recvfrom(2) and recvmsg(2) is an example of a + * system call in this category + */ LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_READ_OR_PEEK_AND_STAT, + + /** + * System calls that informs the kernel in what + * manner the process will use a file descriptor + * + * posix_fadvise(2) and readahead(2) are examples of + * system calls in this category + */ LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_ADVISE, + + /** + * System calls that retrieve metadata about a + * filesystem through a file descriptor + * + * fstatfs(2) is an example of system call in + * this category + */ LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_STATFS, - LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_CREATE, + + /** + * System calls that create a resource that is used + * for LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_POLL + * actions + * + * epoll_create(2) is an example of system call in + * this category + */ LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_CREATE_POLL, - LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_POLL /* can work as pause or relative sleep */ + + /** + * System calls that configure a resource that is + * used for LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_POLL + * actions + * + * epoll_ctl(2) is an example of system call in + * this category + */ + LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_CONFIGURE_POLL, + + /** + * System calls that wait until file descriptor + * are ready for writing or have data to read, + * or until some other event on the file descriptor + * has occurred + * + * epoll_wait(2), poll(2) and pselect6(2) are + * examples of system calls in this category + */ + LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_POLL }; +/** + * System calls that affect a process itself + * + * Much of the information that can be queried + * with system calls in this category may be + * available through a virtual filesystem + */ enum libsyscalls_processes_syscall_subcategory { + /** + * System calls that causes the thread, process, + * process group, or session to exit + * + * exit(2) is an example of a system call in this + * category + */ LIBSYSCALLS_PROCESSES_SUBCAT_EXIT, + + /** + * System calls that retrive information about + * the thread, process, process group, or session + * + * gettid(2), getpid(2), getpgid(2), getsid(2), + * getuid(2), and getcwd(2) are examples of system + * calls in this category + */ LIBSYSCALLS_PROCESSES_SUBCAT_STAT_SELF, - LIBSYSCALLS_PROCESSES_SUBCAT_STAT_CHILD, /* may also stat self */ - LIBSYSCALLS_PROCESSES_SUBCAT_STAT_PARENT, /* may also stat self or children */ + + /** + * System calls that retrive information about the + * process's child processes, or other descendants, + * or itself + */ + LIBSYSCALLS_PROCESSES_SUBCAT_STAT_CHILD, + + /** + * System calls that retrive information about the + * process's parent or other ancestors, or itself + * or its descendants + * + * getppid(2) and getxpid(2) are examples of system + * calls in this category + */ + LIBSYSCALLS_PROCESSES_SUBCAT_STAT_PARENT, + + /** + * System calls that retrive information about any + * process + */ LIBSYSCALLS_PROCESSES_SUBCAT_STAT_OTHER, + + /** + * System calls that change the process's privileges + * + * The system call may also retrieve information + * about the process + * + * setuid(2) in an example of a system call in this + * category + */ LIBSYSCALLS_PROCESSES_SUBCAT_CHANGE_PERMISSIONS, + + /** + * System calls that forks the process, either + * the create a new process or a new thread + * + * fork(2) and clone(2) are examples of system + * calls in this category + */ LIBSYSCALLS_PROCESSES_SUBCAT_CLONE, + + /** + * System calls that changes the program the + * process is executing + * + * execve(2) and execveat(2) are examples of + * system calls in this category + */ LIBSYSCALLS_PROCESSES_SUBCAT_EXEC, + + /** + * System calls that change the working directory + * of the process or thread + * + * chdir(2) in an example of a system call in + * this category + */ LIBSYSCALLS_PROCESSES_SUBCAT_CHDIR, + + /** + * System calls that change the file system root + * of the process or thread + * + * chroot(2) and pivot_root(2) are examples of + * system calls in this category + */ LIBSYSCALLS_PROCESSES_SUBCAT_CHROOT, - LIBSYSCALLS_PROCESSES_SUBCAT_SESSION /* vhangup, setsid, setpgid */ + + /** + * System calls that affect the process's session + * or process group + * + * setsid(2), setpgid(2), and vhangup(2) are + * examples of system calls in this category + */ + LIBSYSCALLS_PROCESSES_SUBCAT_SESSION }; +/** + * System calls that enables or disable system logging + * + * For each system call in this category, the system call + * may use the filesystem or a file descriptor + */ enum libsyscalls_logging_syscall_subcategory { + /** + * System calls that turn on or off logging for + * processes + * + * acct(2) is an example of a system call in this + * category + */ LIBSYSCALLS_LOGGING_SUBCAT_PROCESSES }; +/** + * System calls whose primary function are time related + */ enum libsyscalls_time_syscall_subcategory { + /** + * System calls that can either get or set (or both) + * the current time or time zone information, or the + * time of a virtual clock such as a process's run + * time + * + * adjtime(2), adjtimex(2), and clock_adjtime(2) + * are examples of system calls in this category + */ LIBSYSCALLS_TIME_SUBCAT_GET_OR_SET, + + /** + * System calls that can get the current time or + * time zone information, or the time of a virtual + * clock + * + * time(2), gettimeofday(2), and clock_gettime(2) + * are examples of system calls in this category + */ LIBSYSCALLS_TIME_SUBCAT_GET, + + /** + * System calls that can set the current time or + * time zone information, or the time of a virtual + * clock + * + * stime(2), settimeofday(2), and clock_settime(2) + * are examples of system calls in this category + */ LIBSYSCALLS_TIME_SUBCAT_SET, + + /** + * System calls that receive metadata about a + * clock + * + * clock_gettres(2) is an example of a system call + * in this category + */ LIBSYSCALLS_TIME_SUBCAT_INTROSPECT, + + /** + * System calls that arm or disarm a timer that + * uses relative time + * + * alarm(2) is an example of a system call in this + * category + */ LIBSYSCALLS_TIME_SUBCAT_TIMER_RELATIVE, + + /** + * System calls that arm or disarm a timer that + * uses absolute time + */ LIBSYSCALLS_TIME_SUBCAT_TIMER_ABSOLUTE, + + /** + * System calls that arm or disarm a timer that + * can use either relative or absolute time + */ LIBSYSCALLS_TIME_SUBCAT_TIMER, + + /** + * System calls that read the amount of time + * remaining until a timer that uses relative + * time is run over (is triggered) + * + * These system calls may also retrieve a timer's + * overrun interval + * + * getitimer(2) is an example of a system call + * in this category + */ LIBSYSCALLS_TIME_SUBCAT_TIMER_RELATIVE_READ, + + /** + * System calls that read the time a timer that + * uses absolute time runs over (is triggered) + * + * These system calls may also retrieve a + * timer's overrun interval + */ LIBSYSCALLS_TIME_SUBCAT_TIMER_ABSOLUTE_READ, + + /** + * System calls that act both as + * LIBSYSCALLS_TIME_SUBCAT_TIMER_RELATIVE_READ + * and LIBSYSCALLS_TIME_SUBCAT_TIMER_ABSOLUTE_READ + * system calls + */ LIBSYSCALLS_TIME_SUBCAT_TIMER_READ, + + /** + * System calls that act both as + * LIBSYSCALLS_TIME_SUBCAT_TIMER_RELATIVE + * and LIBSYSCALLS_TIME_SUBCAT_TIMER_RELATIVE_READ + * system calls and may more may not do both at + * the same time + * + * setitimer(2) is an example of a system call + * in this category + */ LIBSYSCALLS_TIME_SUBCAT_TIMER_RELATIVE_WITH_READ, + + /** + * System calls that act both as + * LIBSYSCALLS_TIME_SUBCAT_TIMER_ABSOLUTE + * and LIBSYSCALLS_TIME_SUBCAT_TIMER_ABSOLUTE_READ + * system calls and may more may not do both at + * the same time + */ LIBSYSCALLS_TIME_SUBCAT_TIMER_ABSOLUTE_WITH_READ, + + /** + * System calls that act both as + * LIBSYSCALLS_TIME_SUBCAT_TIMER and + * LIBSYSCALLS_TIME_SUBCAT_TIMER_READ system calls + * and may more may not do both at the same time + */ LIBSYSCALLS_TIME_SUBCAT_TIMER_WITH_READ, + + /** + * System calls that suspends the process until + * a relative point in time (this could be virtual + * time such as a process's run time) + * + * The system call may return early for any reason, + * for example because the a signal was sent to + * the process + * + * nanosleep(2) is an example of a system call + * in this category + */ LIBSYSCALLS_TIME_SUBCAT_SLEEP_RELATIVE, + + /** + * System calls that suspends the process until + * an absolute point in time (this could be virtual + * time such as a process's run time) + * + * The system call may return early for any reason, + * for example because the a signal was sent to the + * process or the time of the clock was modified + */ LIBSYSCALLS_TIME_SUBCAT_SLEEP_ABSOLUTE, + + /** + * System calls that act both as + * LIBSYSCALLS_TIME_SUBCAT_TIMER_RELATIVE_READ + * and LIBSYSCALLS_TIME_SUBCAT_TIMER_ABSOLUTE_READ + * system calls + * + * clock_nanosleep(2) is an example of a system + * call in this category + */ LIBSYSCALLS_TIME_SUBCAT_SLEEP }; +/** + * System calls that deal with signals (signal(7)) + */ enum libsyscalls_signals_syscall_subcategory { + /** + * System calls that only causes the process + * to suspend until it receives a signal + * + * Many system calls will be interrepted if + * there is a pending signal or one is received + * during the system call. There are also some + * system calls that can be used to emulating + * the behaviour of system calls in this category + * but that have another primary purpose. + * + * pause(2) in example of a system call in this + * category + */ LIBSYSCALLS_SIGNALS_SUBCAT_PAUSE, + + /** + * System calls that send a signal to a process + * + * kill(2) in example of a system call in this + * category + */ LIBSYSCALLS_SIGNALS_SUBCAT_KILL }; -/* These may work on memory mapped files */ +/** + * System calls that deal with memory allocations + * including memory mapped files + */ enum libsyscalls_memory_syscall_subcategory { + /** + * System calls that allocate memory or change + * the allocation size of an allocated memory + * segment + * + * The system calls may also return information + * about how much memory has allocated + * + * These system calls may change the address of + * an allocated memory segment + * + * brk(2), mmap(2), mremap(2) are examples of system + * calls in this category + */ LIBSYSCALLS_MEMORY_SUBCAT_ALLOCATE, - LIBSYSCALLS_MEMORY_SUBCAT_READ, + + /** + * System calls that deallocate allocated memory + * segments + * + * munmap(2) is an example of a system call in + * this category + */ + LIBSYSCALLS_MEMORY_SUBCAT_DEALLOCATE, + + /** + * System calls modifies memory + */ LIBSYSCALLS_MEMORY_SUBCAT_WRITE, + + /** + * System calls advises the kernel on issues + * regarding the process's memory + */ LIBSYSCALLS_MEMORY_SUBCAT_ADVISE, + + /** + * System calls that can operate both as + * LIBSYSCALLS_FILESYSTEM_SUBCAT_LINK and + * LIBSYSCALLS_FILESYSTEM_SUBCAT_UNLINK system calls, + * either one at a time or both at the same them + * + * madvise(2) is an example of a system call in + * this category + */ LIBSYSCALLS_MEMORY_SUBCAT_WRITE_OR_ADVISE, + + /** + * System calls that prevent memory to be + * paged out into the swap area + * + * mlock(2) is an example of a system call in + * this category + */ LIBSYSCALLS_MEMORY_SUBCAT_LOCK, + + /** + * System calls that enables memory to be + * paged out into the swap area + * + * munlock(2) is an example of a system call in + * this category + */ LIBSYSCALLS_MEMORY_SUBCAT_UNLOCK, - LIBSYSCALLS_MEMORY_SUBCAT_STAT /* stats memory allocated to the process, not system resources */ + + /** + * System calls that retrieves details about + * memory allocated to the process + * + * mincore(2) is an example of a system call in + * this category + */ + LIBSYSCALLS_MEMORY_SUBCAT_STAT, + + /** + * System calls that changes details about + * memory allocated to the process + * + * mprotect(2) is an example of a system call + * in this category + */ + LIBSYSCALLS_MEMORY_SUBCAT_MODIFY }; +/** + * System calls that deal directly with the + * operating system or machine + */ enum libsyscalls_system_syscall_subcategory { + /** + * System calls that deal set swap memory + * + * swapon(2) and swapoff(2) are examples of system + * calls in this category + */ LIBSYSCALLS_SYSTEM_SUBCAT_SWAP, + + /** + * System calls that poweroff, reboots, suspends + * the machine or live patches the kernel + * + * Note that it is common to preform this task by + * communicating with the init system + * + * reboot(2) is an example of a system call in this + * category + */ LIBSYSCALLS_SYSTEM_SUBCAT_REBOOT, + + /** + * System calls that get the name of the machine + * or the operating system, as well as version + * and CPU details + * + * Note that this information may also be available + * through a virtual file system + * + * uname(2) and gethostname(2) are examples of + * system calls in this category + */ LIBSYSCALLS_SYSTEM_SUBCAT_GET_NAME, + + /** + * System calls that set the name of the machine + * + * Note that this information may also be settable + * via a virtual file system + * + * sethostname(2) is an example of a system call + * in this category + */ LIBSYSCALLS_SYSTEM_SUBCAT_SET_NAME, + + /** + * System calls that get runtime information about + * the system, such as CPU and memory usage and + * entropy + * + * Note that this information may also be settable + * via a virtual file system + * + * sysinfo(2) is an example of a system call + * in this category + */ LIBSYSCALLS_SYSTEM_SUBCAT_STAT, + + /** + * System calls that get generate random data, and + * may thereby deplete the systems entropy pool + * + * Note that this may also be possible to do via a + * virtual file system + * + * getrandom(2) is an example of a system call in + * this category + */ LIBSYSCALLS_SYSTEM_SUBCAT_RANDOM, + + /** + * System calls that are generally harmless and + * required for a process to perform important + * actions + * + * On Linux the following system calls have this + * classification: + * - getpagesize(2) + */ LIBSYSCALLS_SYSTEM_SUBCAT_FUNDAMENTAL }; +/** + * System calls that affect process sheduling + */ enum libsyscalls_scheduling_syscall_subcategory { - LIBSYSCALLS_SCHEDULING_SUBCAT_YEILD, + /** + * System calls that causes the thread, process, + * process group, session, or user the give up it's + * allotted time + * + * sched_yield(2) is an example of system call in + * this category + */ + LIBSYSCALLS_SCHEDULING_SUBCAT_YIELD, + + /** + * System calls that changes a thread's, process's + * process group's, session's, or user's, or the + * machines scheduling parameters + * + * sched_setscheduler(2), sched_setaffinity(2), + * and setpriority(2) are examples of system calls + * in this category + */ LIBSYSCALLS_SCHEDULING_SUBCAT_SET, + + /** + * System calls that retrieves a thread's, process's + * process group's, session's, or user's, or the + * machines scheduling parameters + * + * sched_getscheduler(2), sched_getaffinity(2), + * and getpriority(2) are examples of system calls + * in this category + */ LIBSYSCALLS_SCHEDULING_SUBCAT_GET, + + /** + * System calls that can operate both as + * LIBSYSCALLS_SCHEDULING_SUBCAT_GET and + * LIBSYSCALLS_SCHEDULING_SUBCAT_SET system calls, + * either one at a time or both at the same them + * + * nice(2) is an example of a system call in this + * category + */ + LIBSYSCALLS_SCHEDULING_SUBCAT_GET_OR_SET, + + /** + * System calls the retrieve metadata for the + * scheduling options that are available on the + * system + * + * sched_get_priority_max(2) is an example of + * a system call in this category + */ LIBSYSCALLS_SCHEDULING_SUBCAT_INTROSPECT }; +/** + * Less broad classification on system calls + * + * Each value in `enum libsyscalls_syscall_category` have + * its own field (enumeration of values) name after the + * `enum` value; except that LIBSYSCALLS_CAT_SUPPORT_PENDING + * and LIBSYSCALLS_CAT_NOT_IMPLEMENTED does not have any, + * which also means that whereever this union is used, its + * value is undefined, if the broad classification is either + * LIBSYSCALLS_CAT_SUPPORT_PENDING or LIBSYSCALLS_CAT_NOT_IMPLEMENTED + */ union libsyscalls_syscall_subcategory { - enum_libsyscalls_network_enabled_ipc_syscall_subcategory network_enabled_ipc; - enum_libsyscalls_ipc_syscall_subcategory ipc; - enum_libsyscalls_filesystem_syscall_subcategory filesystem; - enum_libsyscalls_file_descriptors_syscall_subcategory file_descriptors; - enum_libsyscalls_processes_syscall_subcategory processes; - enum_libsyscalls_logging_syscall_subcategory logging; - enum_libsyscalls_time_syscall_subcategory time; - enum_libsyscalls_signals_syscall_subcategory signals; - enum_libsyscalls_memory_syscall_subcategory memory; - enum_libsyscalls_system_syscall_subcategory system; - enum_libsyscalls_scheduling_syscall_subcategory scheduling; + enum_libsyscalls_network_enabled_ipc_syscall_subcategory network_enabled_ipc; /**< Use for LIBSYSCALLS_CAT_NETWORK_ENABLED_IPC */ + enum_libsyscalls_ipc_syscall_subcategory ipc; /**< Use for LIBSYSCALLS_CAT_IPC */ + enum_libsyscalls_filesystem_syscall_subcategory filesystem; /**< Use for LIBSYSCALLS_CAT_FILESYSTEM */ + enum_libsyscalls_file_descriptors_syscall_subcategory file_descriptors; /**< Use for LIBSYSCALLS_CAT_FILE_DESCRIPTORS */ + enum_libsyscalls_processes_syscall_subcategory processes; /**< Use for LIBSYSCALLS_CAT_PROCESSES */ + enum_libsyscalls_logging_syscall_subcategory logging; /**< Use for LIBSYSCALLS_CAT_LOGGING */ + enum_libsyscalls_time_syscall_subcategory time; /**< Use for LIBSYSCALLS_CAT_TIME */ + enum_libsyscalls_signals_syscall_subcategory signals; /**< Use for LIBSYSCALLS_CAT_SIGNALS */ + enum_libsyscalls_memory_syscall_subcategory memory; /**< Use for LIBSYSCALLS_CAT_MEMORY */ + enum_libsyscalls_system_syscall_subcategory system; /**< Use for LIBSYSCALLS_CAT_SYSTEM */ + enum_libsyscalls_scheduling_syscall_subcategory scheduling; /**< Use for LIBSYSCALLS_CAT_SCHEDULING */ }; /** @@ -445,7 +1476,7 @@ struct libsyscalls_syscall_abi { /** * For set any bit indexed I (starting from 0), the * system call parameter I is a pointer that the - * the system call reads from + * system call reads from * * Note that there are types that fundamentally are * pointers (such as strings), for these, this bit @@ -456,7 +1487,7 @@ struct libsyscalls_syscall_abi { /** * For set any bit indexed I (starting from 0), the * system call parameter I is a pointer that the - * the system call write to + * system call write to * * Note that there are types that fundamentally are * pointers (such as strings), for these, this bit @@ -509,7 +1540,7 @@ struct libsyscalls_syscall_abi { short int : LIBSYSCALLS_PAD_(sizeof(short int)/sizeof(char)*CHAR_BIT, 4*16 + 2*6 + 3*1); /** - * This is internally by `libsyscalls_get_syscall_display_info` + * This is used internally by `libsyscalls_get_syscall_display_info` * to find out how values ought to be printed to be both human * and machines friendly (symbolic names are indeed easier for * the application to deal with as their values can depend on @@ -521,8 +1552,8 @@ struct libsyscalls_syscall_abi { * If this is value is 0, `libsyscalls_get_syscall_display_info` * will not be able to provide any useful information, which * would either be because everything is provided here (in - * struct libsyscalls_syscall_abi) or because the library hasn't - * yet added full support for the system call + * `struct libsyscalls_syscall_abi`) or because the library + * hasn't yet added full support for the system call */ LIBSYSCALLS_SYMBOL_PRINTER symbol_printer : 16; @@ -678,7 +1709,7 @@ struct libsyscalls_syscall_type_info { */ enum_libsyscalls_datatype type; - char padding__[LIBSYSCALLS_PAD_(sizeof(long) / sizeof(char), sizeof(enum_libsyscalls_datatype) / sizeof(char) + 1)]; + char padding__[LIBSYSCALLS_PAD_(sizeof(void *)/sizeof(char), sizeof(enum_libsyscalls_datatype)/sizeof(char) + 1)]; unsigned char : CHAR_BIT - 1; /** @@ -814,7 +1845,7 @@ enum libsyscalls_datatype_annotation { }; /** - * Register-split information for a data type + * Register-split/struct field-split information for a data type */ enum libsyscalls_datatype_section { /** @@ -1001,10 +2032,10 @@ enum libsyscalls_datatype_section { LIBSYSCALLS_SECTION_LOWER_QUARTER /* - * Get the number of registers the data type was split into + * Get the number of registers/fields the data type was split into * * @param S:enum libsyscalls_datatype_section The data type section information - * @return :unsigned int The number registers the data type was split into; + * @return :unsigned int The number registers/fields the data type was split into; * invalid if `S` is LIBSYSCALLS_SECTION_UNDETERMINED */ #define LIBSYSCALLS_GET_SECTION_FRACTION(S)\ @@ -1041,23 +2072,29 @@ struct libsyscalls_datatype_description { * number of bits in the entire data type, otherwise the data * type may have been split (LIBSYSCALLS_SECTION_UNDETERMINED, * guaranteed to be split otherwise) and this value is just - * the number of bits stored in the register + * the number of bits stored in the register or struct field + * + * It is possible for the datatype to contain unused dummy + * bits in order to make it a power of 2 or a multiple of + * a smaller data type. For example, on x86, `long double` + * uses 128 bits, even though the value only uses 80 bits. + * The dummy bits are included in the value on this field. */ unsigned width_in_bits; /** * The size (in number of elements) of the array the data type * is used in, or 1 if the data type was not an array or - * 0 if the array size is determined by another parameter + * 0 if the array size is determined by another parameter/field */ unsigned array_size; /** * Only used if .array_size is 0 * - * The position of the arrays size in the parameter list - * relative to the array, e.g. 1 for the next parameter - * or -1 for the previous parameter + * The position of the array's size in the parameter/field list + * relative to the array, e.g. 1 for the next parameter/field + * or -1 for the previous parameter/field * * If 0, use .absolute_position_of_array_size instead */ @@ -1066,7 +2103,7 @@ struct libsyscalls_datatype_description { /** * Only used if .array_size is 0 * - * The position of the arrays size in the parameter list, + * The position of the array's size in the parameter/field list, * indexed starting from 0 * * If -1, use .relative_position_of_array_size instead @@ -1077,10 +2114,10 @@ struct libsyscalls_datatype_description { * Only used if .array_size is 0 * * Assuming the kernel writes into the array, if 1, the number - * of elements written to the array (starting from its - * beginning) is writting into the array size parameter if it - * is marked as an output parameter and return otherwise; if - * 0, the number of bits written must be infered from its + * of elements written to the array (starting from its beginning) + * is writting into the array size parameter/field if it is + * marked as an output parameter/field and return otherwise; + * if 0, the number of bits written must be infered from its * contents, e.g. via null byte termination (how this is done * depends on the system call) */ @@ -1116,17 +2153,17 @@ struct libsyscalls_datatype_description { * * How signed numbers are represented */ - enum libsyscalls_datatype_sign_representation sign_representation; + enum libsyscalls_datatype_sign_representation sign_representation : 8; /** * Additional information about what the value represents */ - enum libsyscalls_datatype_annotation annotation; + enum libsyscalls_datatype_annotation annotation : 8; /** * What part of the value is stored in the instance */ - enum libsyscalls_datatype_section section; + enum libsyscalls_datatype_section section : 16; /** * This is a ~0 terminated array — but, it can also @@ -1143,9 +2180,9 @@ struct libsyscalls_datatype_description { * bits; the bitwise OR of the results is the * unsigned value used in the instance of the data type * - * Data types for register-splits ARE NOT shifted, - * there is always a value in .byteorder that is 0, - * unless .byteorder[0] is ~0 + * Data types for register-splits/struct field-splits + * ARE NOT shifted, there is always a value in + * .byteorder that is 0, unless .byteorder[0] is ~0 * * To avoid problems checking for ~0, use the * LIBSYSCALLS_IS_BYTEORDER_END macro; please also be @@ -1179,6 +2216,187 @@ struct libsyscalls_datatype_description { #endif }; +/** + * Details about of field in a `struct` or `union` + */ +struct libsyscalls_structure_field { + /** + * The name of the field, or `NULL` if anonymous + */ + const char *name; + + /** + * The fields data type + */ + enum_libsyscalls_datatype type : 16; + + /** + * The number bytes from the data type that is used + * for the field, 0 if the field is not a bit field + */ + unsigned short int bitlength : 16; + + /** + * If 1, the field is expected to be populated + * before the system call is entered + */ + unsigned short int input_field : 1; + + /** + * If 1, the field is expected to be populated + * by the system call unless it returns an error + */ + unsigned short int output_field : 1; + + /** + * If 1, the field is expected to be populated + * by the system call provided that it returns + * an error + */ + unsigned short int error_field : 1; + + /** + * If 1, if the field's value can be resolved + * into a symbolic string by the library + */ + unsigned short int symbolic_field : 1; + + /** + * If 1, the field is a pointer that the reads from + * + * Note that there are types that fundamentally are + * pointers (such as strings), for these, this bit + * is not set unless it is a pointer to a string + * + * This field may always 0 when .input_field is 0 + */ + unsigned short int input_pointer : 1; + + /** + * If 1, the field is a pointer that the writes to + * + * Note that there are types that fundamentally are + * pointers (such as strings), for these, this bit + * is not set unless it is a pointer to a string + */ + unsigned short int output_pointer : 1; + + unsigned short int padding1__ : 16 - (6*1); + +#if LIBSYSCALLS_IS_PADDING_REQUIRED_(3, 16, LIBSYSCALLS_POINTER_BIT_) +# if !LIBSYSCALLS_CAN_ALIGN_(3, 16, CHAR_BIT) +# error Sorry, we require that the a byte is no longer than (3*16) bits while evenly dividing (3*16) bits +# endif + char padding2__[LIBSYSCALLS_PAD_(sizeof(void *)/sizeof(char), (3*16)/CHAR_BIT)]; +#endif +}; + +/** + * Details about a `struct` or `union` + */ +struct libsyscalls_structure_description { + /** + * The alignment, in bits, that shall + * be used for the data type; never 0 + */ + unsigned short int alignment : 16; + + /** + * The size of the data type, in bits + * + * If 0, the data type's size is flexible and its + * size is determined by its content but not enough of + * it was provided to determine its size. + * .relative_position_of_size or .absolute_position_of_size + * may or may not be useful to determine the size of the + * data type, if .size is 0 (and .array_size is 1, which + * it in such case must be). + */ + unsigned short int size : 16; + + /** + * The number of fields in the `struct`/`union` + */ + unsigned short int num_fields : 14; + + /** + * Only used if .array_size is 0 + * + * Assuming the kernel writes into the array, if 1, the number + * of elements written to the array (starting from its beginning) + * is writting into the array size parameter/field if it is + * marked as an output parameter/field and return otherwise; + * if 0, the number of bits written must be infered from its + * contents, e.g. via null byte termination (how this is done + * depends on the system call) + */ + unsigned short int fill_is_known : 1; + + /** + * If 1, the data type is a `union`, + * if 0, the data type is a `struct` + */ + unsigned short int is_union : 1; + + /** + * The size (in number of elements) of the array the data type + * is used in, or 1 if the data type was not an array or + * 0 if the array size is determined by another parameter/field + * + * If 1, .relative_position_of_size will be set to 0, + * and .absolute_position_of_size -1, hoever if that is not + * the case and this field is set to 1, then .size (which may + * or may not be 0 at this point) is determined by the indicated + * parameter + */ + unsigned short int array_size : 16; + + /** + * The position of the array's or structure's size in the + * parameter/field list relative to the array/structure, + * e.g. 1 for the next parameter/field or -1 for the previous + * parameter/field + * + * If 0, use .absolute_position_of_size instead + */ + signed short int relative_position_of_size : 16; + + /** + * The position of the array's or structure's size in the + * parameter/field list, indexed starting from 0 + * + * If -1, use .relative_position_of_size instead + */ + signed short int absolute_position_of_size : 16; + + /** + * This is used internally by `libsyscalls_get_struct_display_info` + * to find out how values ought to be printed to be both human + * and machines friendly (symbolic names are indeed easier for + * the application to deal with as their values can depend on + * the architecture) + * + * If this is value is 0, `libsyscalls_get_struct_display_info` + * will not be able to provide any useful information, which + * would either be because everything is provided here (in + * `struct libsyscalls_structure_description`) or because the + * library hasn't yet added full support for the structure + */ + LIBSYSCALLS_SYMBOL_PRINTER symbol_printer : 16; + +#if LIBSYSCALLS_IS_PADDING_REQUIRED_(7, 16, LIBSYSCALLS_POINTER_BIT_) +# if !LIBSYSCALLS_CAN_ALIGN_(7, 16, CHAR_BIT) +# error Sorry, we require that the a byte is no longer than (7*16) bits while evenly dividing (7*16) bits +# endif + char padding__[LIBSYSCALLS_PAD_(sizeof(void *)/sizeof(char), (7*16)/CHAR_BIT)]; +#endif + + /** + * Information about each field in the `struct`/`union` + */ + struct libsyscalls_structure_field fields[LIBSYSCALLS_FLEXABLE_OR_NFIELDS_]; +}; + /** * Return a description of a libsyscalls error @@ -1368,6 +2586,52 @@ enum libsyscalls_error libsyscalls_get_datatype_description(enum libsyscalls_os, enum libsyscalls_arch, enum libsyscalls_datatype, struct libsyscalls_datatype_description *); +/** + * Get the alignment used for or a scalar integer data type + * + * This function does not discriminate between optimal and mandatory + * alignment; some CPUs operate on misalign data for some types, + * whereas other CPUs cannot, but even if it can operate on misalign + * data it will be less efficient. This function returns (into + * `*alignment_out` the optional (default) alignment even there is + * a mandatory alignment that is smaller. As a caveat, the operating + * system may proscribe an multiple of the optimal alignment + * (usually this would be the size of the data type instead of the + * optimal alignment), in such cases, that proscribed alignment will + * be returned instead. + * + * @param os The operating system the data type is used on + * @param arch The architecture the data type is used on + * @param width_in_bits The width of the integer, in bits + * @param alignment_out Output parameter for the alignment, in bits + * (may be NULL, will never be filled with 0) + * @return LIBSYSCALLS_E_OK - On success + * LIBSYSCALLS_E_OSNOSUP - The library is not compiled with support for + * the selected operating system (`os`) + * LIBSYSCALLS_E_ARCHNOSUP - The library is not compiled with support for + * the selected architecture (`arch`) on the + * selected operating system (`os`) + * LIBSYSCALLS_E_INVAL - `width_in_bits` is 0 + * LIBSYSCALLS_E_NOSUCHTYPE - The selected architecture (`arch`) does not + * support any integer width the specified + * width (`width_in_bits`), or the operating + * system (`os`) does not support the data type + * (that would only be the case if the data type + * uses a new register that must be specifically + * supported in the operating system's context + * switching) + * + * The function may complete successfully even if out ought to + * return LIBSYSCALLS_E_ARCHNOSUP, in such cases, the result + * is indeed reliable + */ +LIBSYSCALLS_GCC_ATTRIBUTES_(__warn_unused_result__) +enum libsyscalls_error +libsyscalls_get_integer_alignment(enum libsyscalls_os, enum libsyscalls_arch, unsigned, unsigned *); + +/* TODO add libsyscalls_get_struct_description */ +/* TODO add libsyscalls_get_struct_display_info */ + #include "libsyscalls/internal-end.h" #endif |