diff options
Diffstat (limited to '')
| -rw-r--r-- | libsyscalls.h | 826 |
1 files changed, 530 insertions, 296 deletions
diff --git a/libsyscalls.h b/libsyscalls.h index f2d5fdd..df4de69 100644 --- a/libsyscalls.h +++ b/libsyscalls.h @@ -16,7 +16,7 @@ * the enum value name of the error (identifier), * and the description of the error (string literal) * @param D:code Macro that expands between each expansion of X - * + * * The primary purpose of the existance of this macro * is to ease implementation of the library; it will * probably not disappear (no promises) @@ -119,28 +119,34 @@ enum libsyscalls_datatype { /* You can use these macros classify and convert data types */ #define LIBSYSCALLS_TYPEBITSMASK 0xF000 #define LIBSYSCALLS_TYPEBITS_SCALAR 0x0000 /* predefined total width, even if aggregate */ -#define LIBSYSCALLS_TYPEBITS_ARRAY 0x1000 /* count is stored in next parameter, and is updated with fill - * or returned if no outputable to the next parameter */ -#define LIBSYSCALLS_TYPEBITS_ARRAY_UNKNOWN_FILL 0x2000 /* count is stored in next parameter, fill is in no way returned, - * this chould either be because the array is always (unless an - * error is returned) entirely filled or because the end is - * infered from the contents (e.g. null byte termination) */ +#define LIBSYSCALLS_TYPEBITS_ARRAY 0x1000 /* count is stored in next parameter, and is + * updated with fill or returned if no outputable + * to the next parameter */ +#define LIBSYSCALLS_TYPEBITS_ARRAY_UNKNOWN_FILL 0x2000 /* count is stored in next parameter, fill is + * in no way returned, this chould either be + * because the array is always (unless an error + * is returned) entirely filled or because the + * end is inferred from the contents (e.g. null + * byte termination) */ #define LIBSYSCALLS_LIST_SPECIAL_TYPES(X, SUFFIX, D, FIRST)\ - /* the type used in the system call has not yet be added recorded in the library */\ + /* the type used in the system call has not yet be + * added recorded in the library */\ X(LIBSYSCALLS_TYPE_UNKNOWN ## SUFFIX, FIRST, "(unknown type)") D\ /* the type depends on the system call input or output */\ X(LIBSYSCALLS_TYPE_DYNAMIC ## SUFFIX,, "(undetermined type)") D\ - /* the system call should never returned to the calling process (return to tracer is usually expected) */\ + /* 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, 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)), or to add padding - * (or reserved space for future expansion) to a struct */\ + /* 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)), + * 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)\ @@ -332,17 +338,17 @@ enum libsyscalls_syscall_category { */ LIBSYSCALLS_CAT_NOT_IMPLEMENTED, - 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 */ + 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 */ }; /** @@ -1473,17 +1479,17 @@ enum libsyscalls_scheduling_syscall_subcategory { * LIBSYSCALLS_CAT_SUPPORT_PENDING or LIBSYSCALLS_CAT_NOT_IMPLEMENTED */ union libsyscalls_syscall_subcategory { - 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 */ + enum_libsyscalls_network_enabled_ipc_syscall_subcategory network_enabled_ipc; /**< If LIBSYSCALLS_CAT_NETWORK_ENABLED_IPC */ + enum_libsyscalls_ipc_syscall_subcategory ipc; /**< If LIBSYSCALLS_CAT_IPC */ + enum_libsyscalls_filesystem_syscall_subcategory filesystem; /**< If LIBSYSCALLS_CAT_FILESYSTEM */ + enum_libsyscalls_file_descriptors_syscall_subcategory file_descriptors; /**< If LIBSYSCALLS_CAT_FILE_DESCRIPTORS */ + enum_libsyscalls_processes_syscall_subcategory processes; /**< If LIBSYSCALLS_CAT_PROCESSES */ + enum_libsyscalls_logging_syscall_subcategory logging; /**< If LIBSYSCALLS_CAT_LOGGING */ + enum_libsyscalls_time_syscall_subcategory time; /**< If LIBSYSCALLS_CAT_TIME */ + enum_libsyscalls_signals_syscall_subcategory signals; /**< If LIBSYSCALLS_CAT_SIGNALS */ + enum_libsyscalls_memory_syscall_subcategory memory; /**< If LIBSYSCALLS_CAT_MEMORY */ + enum_libsyscalls_system_syscall_subcategory system; /**< If LIBSYSCALLS_CAT_SYSTEM */ + enum_libsyscalls_scheduling_syscall_subcategory scheduling; /**< If LIBSYSCALLS_CAT_SCHEDULING */ }; /** @@ -1567,7 +1573,8 @@ struct libsyscalls_syscall_abi { */ unsigned short int queer : 1; - short int : LIBSYSCALLS_PAD_(sizeof(short int)/sizeof(char)*CHAR_BIT, 4*16 + 2*6 + 3*1); + short int : LIBSYSCALLS_PAD_(sizeof(short int)/sizeof(char)*CHAR_BIT, + 4*16 + 2*6 + 3*1); /** * This is used internally by `libsyscalls_get_syscall_display_info` @@ -1714,7 +1721,9 @@ struct libsyscalls_named_number { * none was found. The returned string may be stored * in `data` and those override at the next call. */ -typedef const char *libsyscalls_symbol_printer_function(LIBSYSCALLS_SYMBOL_PRINTER_DATA *, unsigned long long int *, char *); +typedef const char *libsyscalls_symbol_printer_function(LIBSYSCALLS_SYMBOL_PRINTER_DATA *data, + unsigned long long int *valuep, + char *fallback_out); /** * Information about a system call parameter or return value @@ -1739,7 +1748,8 @@ struct libsyscalls_syscall_type_info { */ enum_libsyscalls_datatype type; - char padding__[LIBSYSCALLS_PAD_(sizeof(void *)/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; /** @@ -1792,8 +1802,8 @@ struct libsyscalls_syscall_display_info { */ enum libsyscalls_datatype_sign_representation { /** - * The data type was LIBSYSCALLS_TYPE_UNKNOWN or - * LIBSYSCALLS_TYPE_DYNAMIC + * The data type was LIBSYSCALLS_TYPE_UNKNOWN + * or LIBSYSCALLS_TYPE_DYNAMIC */ LIBSYSCALLS_SIGN_UNDETERMINED, @@ -1844,43 +1854,45 @@ enum libsyscalls_datatype_annotation { LIBSYSCALLS_ANNOTATION_NONE, /** - * The value represents an operating system signal (e.g. SIGKILL) + * The value represents an operating system signal + * (e.g. SIGKILL) * - * This affords the application the opportunity to print - * more detail information about a signal (such as when - * it is used, whether it is a realtime signal, default - * action, whether it can be caught, and what its normal - * usage is) + * This affords the application the opportunity + * to print more detail information about a signal + * (such as when it is used, whether it is a + * realtime signal, default action, whether it + * can be caught, and what its normal usage is) */ LIBSYSCALLS_ANNOTATION_SIGNAL, /** * The value represents a file descriptor * - * This affords the application the opportunity to print - * file information (such as file name, address, file type, - * and offset) + * This affords the application the opportunity + * toprint file information (such as file name, + * address, file type, and offset) */ LIBSYSCALLS_ANNOTATION_FD, /** - * The value represents a file descriptor or a special value - * for a known file such as AT_FDCWD + * The value represents a file descriptor or a + * special value for a known file such as AT_FDCWD * - * This affords the application the opportunity to print - * file information (such as file name, address, file type, - * and offset) + * This affords the application the opportunity + * to print file information (such as file name, + * address, file type, and offset) */ LIBSYSCALLS_ANNOTATION_ATFD }; /** - * Register-split/struct field-split information for a data type + * Register-split/struct field-split information + * for a data type */ enum libsyscalls_datatype_section { /** - * The data type was LIBSYSCALLS_TYPE_UNKNOWN or - * LIBSYSCALLS_TYPE_DYNAMIC + * The data type was LIBSYSCALLS_TYPE_UNKNOWN + * or LIBSYSCALLS_TYPE_DYNAMIC */ LIBSYSCALLS_SECTION_UNDETERMINED, @@ -1891,12 +1903,15 @@ enum libsyscalls_datatype_section { */ LIBSYSCALLS_SECTION_WHOLE, - /* + /** * This whether a data type represents a half section * of larger data type * - * @param S:enum libsyscalls_datatype_section The data type section information - * @return :int Whether the larger that type was split into two halves + * @param S:enum libsyscalls_datatype_section + * The data type section information + * + * @return :int Whether the larger that type was + * split into two halves */ #define LIBSYSCALLS_IS_SECTION_HALF(S)\ (((S) >= LIBSYSCALLS_SECTION_UPPER_HALF) &&\ @@ -1998,12 +2013,15 @@ enum libsyscalls_datatype_section { */ LIBSYSCALLS_SECTION_ODD_BYTES_AS_HALF, - /* + /** * This whether a data type represents a quarter section * of larger data type * - * @param S:enum libsyscalls_datatype_section The data type section information - * @return :int Whether the larger that type was split into four quarters + * @param S:enum libsyscalls_datatype_section + * The data type section information + * + * @return :int Whether the larger that type was + * split into four quarters */ #define LIBSYSCALLS_IS_SECTION_QUARTER(S)\ (((S) >= LIBSYSCALLS_SECTION_UPPER_QUARTER) &&\ @@ -2061,18 +2079,73 @@ enum libsyscalls_datatype_section { */ LIBSYSCALLS_SECTION_LOWER_QUARTER - /* - * Get the number of registers/fields 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 * - * @param S:enum libsyscalls_datatype_section The data type section information - * @return :unsigned int The number registers/fields the data type was split into; - * invalid if `S` is LIBSYSCALLS_SECTION_UNDETERMINED + * @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)\ (LIBSYSCALLS_IS_SECTION_HALF(S) ? 2U :\ LIBSYSCALLS_IS_SECTION_QUARTER(S) ? 4U : 1U) }; + +/** + * Macro for enumerating type-split sections + * + * The numbers are stored in `enum libsyscalls_datatype_section` + * + * @param X:macro(NAME, ...) Macro that expands, will a number of arguments: + * 1) The name of the enum value + * 2) 1 if the section is both compatible with 16-bit + * integers and is the first section with its + * pattern of covered bits for 16-bit integers, + * 0 otherwise + * 3) Mask of bits the section covers for a 16-bit integer + * 4) 1 if the section is both compatible with 32-bit + * integers and is the first section with its + * pattern of covered bits for 32-bit integers, + * 0 otherwise + * 5) Mask of bits the section covers for a 32-bit integer + * 6) 1 if the section is both compatible with 64-bit + * integers and is the first section with its + * pattern of covered bits for 64-bit integers, + * 0 otherwise + * 7) Mask of bits the section covers for a 64-bit integer + * Arguments 3, 5, and 7 are `0` when the section is not + * compatible with the data type and otherwise a `0x` + * prefixed uppercase hexadecimal number without any type + * suffix. + * Addition arguments may be added in the future. + * @param D:code Macro that expands between each expansion of X + * + * The primary purpose of the existance of this macro + * is to ease implementation of the library; it will + * probably not disappear (no promises) + */ +#define LIBSYSCALLS_LIST_SECTIONS(X, D)\ + X(LIBSYSCALLS_SECTION_WHOLE, 1, 0xFFFF, 1, 0xFFFFFFFF, 1, 0xFFFFFFFFFFFFFFFF) D\ + X(LIBSYSCALLS_SECTION_UPPER_HALF, 1, 0xFF00, 1, 0xFFFF0000, 1, 0xFFFFFFFF00000000) D\ + X(LIBSYSCALLS_SECTION_LOWER_HALF, 1, 0x00FF, 1, 0x0000FFFF, 1, 0x00000000FFFFFFFF) D\ + X(LIBSYSCALLS_SECTION_INNER_HALF, 0, 0, 1, 0x00FFFF00, 1, 0x0000FFFFFFFF0000) D\ + X(LIBSYSCALLS_SECTION_OUTER_HALF, 0, 0, 1, 0xFF0000FF, 1, 0xFFFF00000000FFFF) D\ + X(LIBSYSCALLS_SECTION_EVEN_QUARTERS_AS_HALF, 0, 0, 1, 0x00FF00FF, 1, 0x0000FFFF0000FFFF) D\ + X(LIBSYSCALLS_SECTION_ODD_QUARTERS_AS_HALF, 0, 0, 1, 0xFF00FF00, 1, 0xFFFF0000FFFF0000) D\ + X(LIBSYSCALLS_SECTION_EVEN_BYTES_AS_HALF, 0, 0, 0, 0x00FF00FF, 1, 0x00FF00FF00FF00FF) D\ + X(LIBSYSCALLS_SECTION_ODD_BYTES_AS_HALF, 0, 0, 0, 0xFF00FF00, 1, 0xFF00FF00FF00FF00) D\ + X(LIBSYSCALLS_SECTION_UPPER_QUARTER, 0, 0, 1, 0xFF000000, 1, 0xFFFF000000000000) D\ + X(LIBSYSCALLS_SECTION_UPPER_MID_QUARTER, 0, 0, 1, 0x00FF0000, 1, 0x0000FFFF00000000) D\ + X(LIBSYSCALLS_SECTION_LOWER_MID_QUARTER, 0, 0, 1, 0x0000FF00, 1, 0x00000000FFFF0000) D\ + X(LIBSYSCALLS_SECTION_LOWER_QUARTER, 0, 0, 1, 0x000000FF, 1, 0x000000000000FFFF) + + /** * Information on how an instance of data type is to be parsed * @@ -2176,7 +2249,8 @@ struct libsyscalls_datatype_description { */ unsigned min_is_minus_max : 1; - int padding__ : LIBSYSCALLS_PAD_(sizeof(int)/sizeof(char)*CHAR_BIT, 2*5 + 4*1); + int padding__ : LIBSYSCALLS_PAD_(sizeof(int)/sizeof(char)*CHAR_BIT, + 2*5 + 4*1); /** * Only used if .is_signed is 1 @@ -2231,20 +2305,25 @@ struct libsyscalls_datatype_description { unsigned char byteorder[32]; /** - * Test whether a value in `struct libsyscalls_datatype_description.byteorder` - * marks the end of the byteorder's shift value (testing - * that the value is ~0). Using this macro helps avoiding - * bugs caused by integer type promotion. + * Test whether a value in `struct + * libsyscalls_datatype_description.byteorder` + * marks the end of the byteorder's shift value + * (testing that the value is ~0). Using this + * macro helps avoiding bugs caused by integer + * type promotion. * - * @param SHIFT The value to test `struct libsyscalls_datatype_description.byteorder` + * @param SHIFT The value to test `struct + * libsyscalls_datatype_description.byteorder` * @return :int Whether the value is ~0 */ #ifdef UINTMAX_C # define LIBSYSCALLS_IS_BYTEORDER_END(SHIFT)\ - (!~((SHIFT) | ~LIBSYSCALLS_FIELD_MASK_(UINTMAX_C(1), struct libsyscalls_datatype_description, byteorder[0]))) + (!~((SHIFT) | ~LIBSYSCALLS_FIELD_MASK_(UINTMAX_C(1),\ + struct libsyscalls_datatype_description, byteorder[0]))) #else # define LIBSYSCALLS_IS_BYTEORDER_END(SHIFT)\ - (!~((SHIFT) | ~LIBSYSCALLS_FIELD_MASK_(1ULL, struct libsyscalls_datatype_description, byteorder[0]))) + (!~((SHIFT) | ~LIBSYSCALLS_FIELD_MASK_(1ULL,\ + struct libsyscalls_datatype_description, byteorder[0]))) #endif /** @@ -2252,8 +2331,8 @@ struct libsyscalls_datatype_description { * the (post-last) end of `DESC->byteorder` */ #define LIBSYSCALLS_IS_BYTEORDER_END_AT(DESC, INDEX)\ - ((size_t)(INDEX) == sizeof((DESC)->byteorder) / sizeof(*(DESC)->byteorder) || \ - LIBSYSCALLS_IS_BYTEORDER_END((DESC)->byteorder[INDEX])) + ((size_t)(INDEX) == sizeof((DESC)->byteorder) / sizeof(*(DESC)->byteorder) || \ + LIBSYSCALLS_IS_BYTEORDER_END((DESC)->byteorder[INDEX])) }; /** @@ -2506,7 +2585,8 @@ struct libsyscalls_structure_description { # 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)]; + char padding__[LIBSYSCALLS_PAD_(sizeof(void *)/sizeof(char), + (7*16)/CHAR_BIT)]; #endif /** @@ -2520,11 +2600,13 @@ struct libsyscalls_structure_description { * Return a description of a libsyscalls error * * @param error The libsyscalls error - * @return Description of the error, the first character will be in uppercase + * @return Description of the error, the first + * character will be in uppercase */ LIBSYSCALLS_GCC_ATTRIBUTES_(__const__, __returns_nonnull__, __warn_unused_result__) const char * -libsyscalls_strerror(enum libsyscalls_error); +libsyscalls_strerror(enum libsyscalls_error error); + /** * Print a line with a description of a @@ -2535,21 +2617,25 @@ libsyscalls_strerror(enum libsyscalls_error); * @param error The libsyscalls error */ void -libsyscalls_perror(const char *, enum libsyscalls_error); +libsyscalls_perror(const char *prefix, enum libsyscalls_error err); + /** * Get the valid range system call numbers * - * @param os The operating system the range shall valid for - * @param arch The architecture the range shall valid for - * @param min_out Output parameter for the lowest used system call number (may be NULL) - * @param max_out Output parameter for the highest used system call number (may be NULL) - * @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`) + * @param os The operating system the range shall valid for + * @param arch The architecture the range shall valid for + * @param min_out Output parameter for the lowest used + * system call number (may be NULL) + * @param max_out Output parameter for the highest used + * system call number (may be NULL) + * + * @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`) * * This function always fails if the selected combination * of operating system (`os`) and architecture (`arch`) is @@ -2559,36 +2645,45 @@ libsyscalls_perror(const char *, enum libsyscalls_error); * (not [*min_out, *max_out - 1]) but there may still be numbers within * this range that does not correspond to a system call */ -LIBSYSCALLS_GCC_ATTRIBUTES_(__warn_unused_result__, __access__(__write_only__, 3), __access__(__write_only__, 4)) +LIBSYSCALLS_GCC_ATTRIBUTES_(__warn_unused_result__, + __access__(__write_only__, 3), + __access__(__write_only__, 4)) enum libsyscalls_error -libsyscalls_get_syscall_range(enum libsyscalls_os, enum libsyscalls_arch, long long int *, long long int *); +libsyscalls_get_syscall_range(enum libsyscalls_os os, enum libsyscalls_arch arch, + long long int *min_out, long long int *max_out); + /** * Get the description of a system call * - * @param os The operating system the range shall valid for - * @param arch The architecture the range shall valid for - * @param syscallnr The system call's number - * @param syscall_out Output parameter for the system call description - * (the argument may be NULL, *syscall_out will - * never be set to NULL) - * @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_NOSUCHSYSCALL - `syscallnr` does not correspond to a known - * system call for the selected architecture (`arch`) - * on the selected operating system (`os`) + * @param os The operating system the range shall valid for + * @param arch The architecture the range shall valid for + * @param syscall_nr The system call's number + * @param syscall_out Output parameter for the system call description + * (the argument may be NULL, *syscall_out will + * never be set to NULL) + * + * @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_NOSUCHSYSCALL - `syscall_nr` does not correspond to a known + * system call for the selected architecture (`arch`) + * on the selected operating system (`os`) * * This function always fails if the selected combination * of operating system (`os`) and architecture (`arch`) is * unsupported */ -LIBSYSCALLS_GCC_ATTRIBUTES_(__warn_unused_result__, __access__(__write_only__, 4)) +LIBSYSCALLS_GCC_ATTRIBUTES_(__warn_unused_result__, + __access__(__write_only__, 4)) enum libsyscalls_error -libsyscalls_get_syscall(enum libsyscalls_os, enum libsyscalls_arch, long long int, const struct libsyscalls_syscall **); +libsyscalls_get_syscall(enum libsyscalls_os os, enum libsyscalls_arch arch, + long long int syscall_nr, + const struct libsyscalls_syscall **syscall_out); + /** * Get the system call errors defined by an operating system @@ -2599,27 +2694,36 @@ libsyscalls_get_syscall(enum libsyscalls_os, enum libsyscalls_arch, long long in * The returned listing will be sorted by the error numbers * in ascending order * - * @param os The operating system whose errors shall be returned - * @param arch The architecture the error numbers shall be valid for - * @param errors_out Output parameter for the error list (may be NULL, never filled with NULL) - * @param num_errors_out Output parameter for the number of errors returned in `*errors_out` (may be NULL) - * (if `errors_out` is NULL, the number that would be returned is stored) - * @param are_signed_out Output parameter for whether the error numbers are signed (may be NULL) - * @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_NOERRORS - The operating system does not use named error numbers + * @param os The operating system whose errors shall be returned + * @param arch The architecture the error numbers shall be valid for + * @param errors_out Output parameter for the error list + * (may be NULL, never filled with NULL) + * @param num_errors_out Output parameter for the number of errors returned + * in `*errors_out` (may be NULL) (if `errors_out` is NULL, + * the number that would be returned is stored) + * @param are_signed_out Output parameter for whether the error numbers are + * signed (may be NULL) + * + * @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_NOERRORS - The operating system does not use named error numbers * * This function will always fail if the operating system (`os`) * is not supported, however it may be successful even if the * architecture (`arch`) not supported */ -LIBSYSCALLS_GCC_ATTRIBUTES_(__access__(__write_only__, 3), __access__(__write_only__, 4), __access__(__write_only__, 5)) +LIBSYSCALLS_GCC_ATTRIBUTES_(__access__(__write_only__, 3), + __access__(__write_only__, 4), + __access__(__write_only__, 5)) enum libsyscalls_error -libsyscalls_get_syscall_errors(enum libsyscalls_os, enum libsyscalls_arch, const struct libsyscalls_named_number **, size_t *, int *); +libsyscalls_get_syscall_errors(enum libsyscalls_os os, enum libsyscalls_arch arch, + const struct libsyscalls_named_number **errors_out, + size_t *num_errors_out, int *are_signed_out); + /** * Get the system signals defined by an operating system @@ -2630,58 +2734,140 @@ libsyscalls_get_syscall_errors(enum libsyscalls_os, enum libsyscalls_arch, const * The returned listing will be sorted by the signal * numbers in ascending order * - * @param os The operating system whose errors shall be returned - * @param arch The architecture the error numbers shall be valid for - * @param signals_out Output parameter for the signal list (may be NULL, never filled with NULL) - * @param num_signals_out Output parameter for the number of signals returned in `*signals_out` (may be NULL) - * (if `signals_out` is NULL, the number that would be returned is stored) - * @param are_signed_ out Output parameter for whether the signal numbers are signed (may be NULL) - * @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_NOSIGNALS - The operating system does not use named signal numbers + * @param os The operating system whose errors shall be returned + * @param arch The architecture the error numbers shall be valid for + * @param signals_out Output parameter for the signal list + * (may be NULL, never filled with NULL) + * @param num_signals_out Output parameter for the number of signals returned + * in `*signals_out` (may be NULL) (if `signals_out` is + * NULL, the number that would be returned is stored) + * @param are_signed_out Output parameter for whether the signal numbers are + * signed (may be NULL) + * + * @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_NOSIGNALS - The operating system does not use named signal numbers * * This function will always fail if the operating system (`os`) * is not supported, however it may be successful even if the * architecture (`arch`) not supported */ -LIBSYSCALLS_GCC_ATTRIBUTES_(__access__(__write_only__, 3), __access__(__write_only__, 4), __access__(__write_only__, 5)) +LIBSYSCALLS_GCC_ATTRIBUTES_(__access__(__write_only__, 3), + __access__(__write_only__, 4), + __access__(__write_only__, 5)) enum libsyscalls_error -libsyscalls_get_signals(enum libsyscalls_os, enum libsyscalls_arch, const struct libsyscalls_named_number **, size_t *, int *); +libsyscalls_get_signals(enum libsyscalls_os os, enum libsyscalls_arch arch, + const struct libsyscalls_named_number **signals_out, + size_t *num_signals_out, int *are_signed_out); + + +/** + * Finds a named number in a sorted array by its signed number + * + * @param key The signed number of the named number to find + * @param base The array of named numbers, sorted in ascending + * order by their signed numbers + * @param n The number of elements in `base` + * @return The element in `base` whose signed number is `key`, + * `NULL` if not found + */ +LIBSYSCALLS_GCC_ATTRIBUTES_(__warn_unused_result__, __pure__, + __access__(__read_only__, 2, 3)) +const struct libsyscalls_named_number * +libsyscalls_find_signed_named_number(signed long long int key, + const struct libsyscalls_named_number *base, size_t n); + + +/** + * Finds a named number in a sorted array by its unsigned number + * + * @param key The unsigned number of the named number to find + * @param base The array of named numbers, sorted in ascending + * order by their unsigned numbers + * @param n The number of elements in `base` + * @return The element in `base` whose unsigned number is `key`, + * `NULL` if not found + */ +LIBSYSCALLS_GCC_ATTRIBUTES_(__warn_unused_result__, __pure__, + __access__(__read_only__, 2, 3)) +const struct libsyscalls_named_number * +libsyscalls_find_unsigned_named_number(unsigned long long int key, + const struct libsyscalls_named_number *base, size_t n); + + +/** + * Finds a named number in a sorted array by its number + * + * @param key The number of the named number to find + * @param is_signed Whether the numbers are signed + * @param base The array of named numbers, sorted in ascending + * order by their numbers + * @param n The number of elements in `base` + * @return The element in `base` whose number is `key`, + * `NULL` if not found + * + * If `is_signed` is non-zero, `key` is reinterpreted (not cast) as a signed number; + * thus it is important that if `key` uses all bits in `long long int`, + * would be an error to take a `int`, reinterpret it as an `unsigned int`, + * and input it to as `key` casting it to `unsigned long long int`; rather + * an `int` must first be cast to `long long int`, and then reinterpreted + * as a `unsigned long long int` before it is input as `key`. Using + * `libsyscalls_find_signed_named_number` instead removes this complication + * in such a senario. + */ +LIBSYSCALLS_GCC_ATTRIBUTES_(__warn_unused_result__, __pure__, + __access__(__read_only__, 3, 4)) +inline const struct libsyscalls_named_number * +libsyscalls_find_named_number(unsigned long long int key, int is_signed, + const struct libsyscalls_named_number *base, size_t n) +{ + signed long long int skey = *(signed long long int *)&key; + return is_signed ? libsyscalls_find_signed_named_number(skey, base, n) + : libsyscalls_find_unsigned_named_number(key, base, n); +} + /** * Get system call information tweak for the arguments passed * to the system call, as well as information about how to * print named values in the arguments and return * - * @param os The operating system the system call was invoked on - * @param arch The architecture the system call was invoked on - * @param syscall The ABI of the system call (see libsyscalls_get_syscall) - * @param syscall_number The system call's number - * @param syscall_arguments The values store in register (as upon system call entry) - * the used for the system call, in the order the registers - * are used as system call arguments - * @param info_out Output parameter for the additional system call information; - * the caller responsible for deallocating the `*info_out` - * with free(3) when it is no longer needed. Be aware that - * `*info_out` will only be set when LIBSYSCALLS_E_OK is - * returned. - * @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_NOMEM - Failed to allocate memory for `*info_out` - * LIBSYSCALLS_E_INVAL - One of the arguments was NULL + * @param os The operating system the system call was invoked on + * @param arch The architecture the system call was invoked on + * @param syscall The ABI of the system call (see libsyscalls_get_syscall) + * @param syscall_number The system call's number + * @param syscall_arguments The values store in register (as upon system call entry) + * the used for the system call, in the order the registers + * are used as system call arguments + * @param info_out Output parameter for the additional system call information; + * the caller responsible for deallocating the `*info_out` + * with free(3) when it is no longer needed. Be aware that + * `*info_out` will only be set when LIBSYSCALLS_E_OK is + * returned. + * + * @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_NOMEM - Failed to allocate memory for `*info_out` + * LIBSYSCALLS_E_INVAL - One of the arguments was NULL */ -LIBSYSCALLS_GCC_ATTRIBUTES_(__warn_unused_result__, __nonnull__, __access__(__read_only__, 3), __access__(__write_only__, 6)) +LIBSYSCALLS_GCC_ATTRIBUTES_(__warn_unused_result__, __nonnull__, + __access__(__read_only__, 3), + __access__(__write_only__, 6)) enum libsyscalls_error -libsyscalls_get_syscall_display_info(enum libsyscalls_os, enum libsyscalls_arch, const struct libsyscalls_syscall_abi *, - long long int, const unsigned long long int *, struct libsyscalls_syscall_display_info **); +libsyscalls_get_syscall_display_info(enum libsyscalls_os os, enum libsyscalls_arch arch, + const struct libsyscalls_syscall_abi *syscall, + long long int syscall_number, + const unsigned long long int *syscall_arguments, + struct libsyscalls_syscall_display_info **info_out); + /** * Get information on how an instance of non-struct, non-union @@ -2692,32 +2878,36 @@ libsyscalls_get_syscall_display_info(enum libsyscalls_os, enum libsyscalls_arch, * in the structure's field, as it may contain * important adjustments * - * @param os The operating system the data type is used on - * @param arch The architecture the data type is used on - * @param datatype The data type, `LIBSYSCALLS_TYPE_DYNAMIC` can - * be used to get the size of the registers used - * as system call parameters - * @param description_out Output parameter for the type description - * @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 - `datatype` is not a valid data type - * LIBSYSCALLS_E_NOSUCHTYPE - `datatype` does not exist on the selected - * operating system (`os`) or architecture (`arch`) - * LIBSYSCALLS_E_ISSTRUCT - `datatype` represents a structure or union, - * or an array of a structure or union + * @param os The operating system the data type is used on + * @param arch The architecture the data type is used on + * @param datatype The data type, `LIBSYSCALLS_TYPE_DYNAMIC` can + * be used to get the size of the registers used + * as system call parameters + * @param description_out Output parameter for the type description + * + * @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 - `datatype` is not a valid data type + * LIBSYSCALLS_E_NOSUCHTYPE - `datatype` does not exist on the selected + * operating system (`os`) or architecture (`arch`) + * LIBSYSCALLS_E_ISSTRUCT - `datatype` represents a structure or union, + * or an array of a structure or union * * The function may complete successfully for some data * types even if it for other data types would return * LIBSYSCALLS_E_OSNOSUP or LIBSYSCALLS_E_ARCHNOSUP */ -LIBSYSCALLS_GCC_ATTRIBUTES_(__warn_unused_result__, __access__(__write_only__, 4)) +LIBSYSCALLS_GCC_ATTRIBUTES_(__warn_unused_result__, + __access__(__write_only__, 4)) enum libsyscalls_error -libsyscalls_get_datatype_description(enum libsyscalls_os, enum libsyscalls_arch, enum libsyscalls_datatype, - struct libsyscalls_datatype_description *); +libsyscalls_get_datatype_description(enum libsyscalls_os os, enum libsyscalls_arch arch, + enum libsyscalls_datatype datatype, + struct libsyscalls_datatype_description *description_out); + /** * Get the alignment used for or a scalar integer data type @@ -2733,34 +2923,38 @@ libsyscalls_get_datatype_description(enum libsyscalls_os, enum libsyscalls_arch, * 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) + * @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__, __access__(__write_only__, 4)) +LIBSYSCALLS_GCC_ATTRIBUTES_(__warn_unused_result__, + __access__(__write_only__, 4)) enum libsyscalls_error -libsyscalls_get_integer_alignment(enum libsyscalls_os, enum libsyscalls_arch, unsigned, unsigned *); +libsyscalls_get_integer_alignment(enum libsyscalls_os os, enum libsyscalls_arch arch, + unsigned width_in_bits, unsigned *alignment_out); + /** * Parse a string of bits as a signed integer @@ -2768,20 +2962,26 @@ libsyscalls_get_integer_alignment(enum libsyscalls_os, enum libsyscalls_arch, un * In case `representation` is LIBSYSCALLS_SIGN_UNDETERMINED, * the bits are parsed as an unsigned integer * - * @param value_in The bits to parse as a signed integer - * @param representation The sign representation used on the interger - * @param bits The number of bits in the integer - * @param value_out Output parameter for the absolute value of the signed integer (may be NULL) - * @param negative_out Output parameter for whether the signed integer is negative (may be NULL) - * @return LIBSYSCALLS_E_OK - On success - * LIBSYSCALLS_E_INVAL - `representation` is not recognised by the library - * LIBSYSCALLS_E_INVAL - `bits` is 0 - * LIBSYSCALLS_E_INVAL - `bits` is greater than `sizeof(long long int) * CHAR_BIT` + * @param value_in The bits to parse as a signed integer + * @param representation The sign representation used on the interger + * @param bits The number of bits in the integer + * @param value_out Output parameter for the absolute value + * of the signed integer (may be NULL) + * @param negative_out Output parameter for whether the signed + * integer is negative (may be NULL) + * + * @return LIBSYSCALLS_E_OK - On success + * LIBSYSCALLS_E_INVAL - `representation` is not recognised by the library + * LIBSYSCALLS_E_INVAL - `bits` is 0 + * LIBSYSCALLS_E_INVAL - `bits > sizeof(long long int) * CHAR_BIT` */ -LIBSYSCALLS_GCC_ATTRIBUTES_(__access__(__write_only__, 4), __access__(__write_only__, 5)) +LIBSYSCALLS_GCC_ATTRIBUTES_(__access__(__write_only__, 4), + __access__(__write_only__, 5)) enum libsyscalls_error -libsyscalls_parse_signed_integer(unsigned long long int, enum libsyscalls_datatype_sign_representation, - size_t, unsigned long long int *, int *); +libsyscalls_parse_signed_integer(unsigned long long int value_in, + enum libsyscalls_datatype_sign_representation representation, + size_t bits, unsigned long long int *value_out, int *negative_out); + /** * Create a string of bits representing a signed integer @@ -2789,20 +2989,23 @@ libsyscalls_parse_signed_integer(unsigned long long int, enum libsyscalls_dataty * In case `representation` is LIBSYSCALLS_SIGN_UNDETERMINED, * the bit string will represent an unsigned integer * - * @param value_in The absolute value if the signed integer - * @param negative Whether the signed integer is negative - * @param representation The sign representation used on the interger - * @param bits The number of bits in the integer - * @param value_out Output parameter for the bit string (may be NULL) - * @return LIBSYSCALLS_E_OK - On success - * LIBSYSCALLS_E_INVAL - `representation` is not recognised by the library - * LIBSYSCALLS_E_INVAL - `bits` is 0 - * LIBSYSCALLS_E_INVAL - `bits` is greater than `sizeof(long long int) * CHAR_BIT` + * @param value_in The absolute value if the signed integer + * @param negative Whether the signed integer is negative + * @param representation The sign representation used on the interger + * @param bits The number of bits in the integer + * @param value_out Output parameter for the bit string (may be NULL) + * + * @return LIBSYSCALLS_E_OK - On success + * LIBSYSCALLS_E_INVAL - `representation` is not recognised by the library + * LIBSYSCALLS_E_INVAL - `bits` is 0 + * LIBSYSCALLS_E_INVAL - `bits > sizeof(long long int) * CHAR_BIT` */ LIBSYSCALLS_GCC_ATTRIBUTES_(__access__(__write_only__, 5)) enum libsyscalls_error -libsyscalls_make_signed_integer(unsigned long long int, int, enum libsyscalls_datatype_sign_representation, - size_t, unsigned long long int *); +libsyscalls_make_signed_integer(unsigned long long int value_in, int negative, + enum libsyscalls_datatype_sign_representation representation, + size_t bits, unsigned long long int *value_out); + /** * Take bits from a section of a split value @@ -2813,18 +3016,23 @@ libsyscalls_make_signed_integer(unsigned long long int, int, enum libsyscalls_da * If `section` is LIBSYSCALLS_SECTION_UNDETERMINED, * no changes will be made * - * @param value_in The contiguous bits in the section of the value - * @param bits The number of bits in the section of the value - * @param section The section of the value - * @param value_out Output parameter for the value with its bits shifted into place (may be NULL) - * @return LIBSYSCALLS_E_OK - On success - * LIBSYSCALLS_E_INVAL - `representation` is not recognised by the library - * LIBSYSCALLS_E_INVAL - `bits` is invalid for `section` - * LIBSYSCALLS_E_INVAL - `bits` is greater than `sizeof(long long int) * CHAR_BIT` + * @param value_in The contiguous bits in the section of the value + * @param bits The number of bits in the section of the value + * @param section The section of the value + * @param value_out Output parameter for the value with its + * bits shifted into place (may be NULL) + * + * @return LIBSYSCALLS_E_OK - On success + * LIBSYSCALLS_E_INVAL - `representation` is not recognised by the library + * LIBSYSCALLS_E_INVAL - `bits` is invalid for `section` + * LIBSYSCALLS_E_INVAL - `bits > sizeof(long long int) * CHAR_BIT` */ LIBSYSCALLS_GCC_ATTRIBUTES_(__access__(__write_only__, 4)) enum libsyscalls_error -libsyscalls_unsection_value(unsigned long long int, size_t, enum libsyscalls_datatype_section, unsigned long long int *); +libsyscalls_unsection_value(unsigned long long int value_in, size_t bits, + enum libsyscalls_datatype_section section, + unsigned long long int *value_out); + /** * Create a split section from a value @@ -2832,51 +3040,70 @@ libsyscalls_unsection_value(unsigned long long int, size_t, enum libsyscalls_dat * If `section` is LIBSYSCALLS_SECTION_UNDETERMINED, * no changes will be made * - * @param value_in The whole value - * @param bits The number of bits in the whole value - * @param section The section of the value to return - * @param value_out Output parameter for bits in the section value shifted into contiguity (may be NULL) - * @return LIBSYSCALLS_E_OK - On success - * LIBSYSCALLS_E_INVAL - `representation` is not recognised by the library - * LIBSYSCALLS_E_INVAL - `bits` is invalid for `section` - * LIBSYSCALLS_E_INVAL - `bits` is greater than `sizeof(long long int) * CHAR_BIT` + * @param value_in The whole value + * @param bits The number of bits in the whole value + * @param section The section of the value to return + * @param value_out Output parameter for bits in the section + * value shifted into contiguity (may be NULL) + * + * @return LIBSYSCALLS_E_OK - On success + * LIBSYSCALLS_E_INVAL - `representation` is not recognised by the library + * LIBSYSCALLS_E_INVAL - `bits` is invalid for `section` + * LIBSYSCALLS_E_INVAL - `bits > sizeof(long long int) * CHAR_BIT` */ LIBSYSCALLS_GCC_ATTRIBUTES_(__access__(__write_only__, 4)) enum libsyscalls_error -libsyscalls_section_value(unsigned long long int, size_t, enum libsyscalls_datatype_section, unsigned long long int *); +libsyscalls_section_value(unsigned long long int value_in, size_t bits, + enum libsyscalls_datatype_section section, + unsigned long long int *value_out); + /** * Converts a value from the tracee's endian to the tracer's endian * - * @param value_in Buffer containing the value to convert (does not need to be aligned) - * @param offset_in Offset in `value_in`, in bits - * @param type Details about the data type - * @param value_out Output parameter for the value in the tracer's endian - * @return LIBSYSCALLS_E_OK - On success - * LIBSYSCALLS_E_INVAL - Either parameter is NULL - * LIBSYSCALLS_E_INVAL - The data type is too wide + * @param value_in Buffer containing the value to convert + * (does not need to be aligned) + * @param offset_in Offset in `value_in`, in bits + * @param type Details about the data type + * @param value_out Output parameter for the value in the tracer's endian + * + * @return LIBSYSCALLS_E_OK - On success + * LIBSYSCALLS_E_INVAL - Either parameter is NULL + * LIBSYSCALLS_E_INVAL - The data type is too wide */ -LIBSYSCALLS_GCC_ATTRIBUTES_(__nonnull__, __access__(__read_only__, 1), __access__(__read_only__, 3), __access__(__write_only__, 4)) +LIBSYSCALLS_GCC_ATTRIBUTES_(__nonnull__, + __access__(__read_only__, 1), + __access__(__read_only__, 3), + __access__(__write_only__, 4)) enum libsyscalls_error -libsyscalls_to_tracer_endian(const void *, size_t, const struct libsyscalls_datatype_description *, unsigned long long int *); +libsyscalls_to_tracer_endian(const void *value_in, size_t offset_in, + const struct libsyscalls_datatype_description *type, + unsigned long long int *value_out); + /** * Converts a value from the tracer's endian to the tracee's endian * - * @param value_in Buffer containing the value to convert - * @param type Details about the data type - * @param value_out Output parameter for the value in the tracee's - * endian (does not need to be aligned); preexisting - * bits that do not overlap with the position of the - * value will be retained - * @param out_offset Offset in `value_out`, in bits - * @return LIBSYSCALLS_E_OK - On success - * LIBSYSCALLS_E_INVAL - Either parameter is NULL - * LIBSYSCALLS_E_INVAL - The data type is too wide + * @param value_in Buffer containing the value to convert + * @param type Details about the data type + * @param value_out Output parameter for the value in the tracee's + * endian (does not need to be aligned); preexisting + * bits that do not overlap with the position of the + * value will be retained + * @param out_offset Offset in `value_out`, in bits + * + * @return LIBSYSCALLS_E_OK - On success + * LIBSYSCALLS_E_INVAL - Either parameter is NULL + * LIBSYSCALLS_E_INVAL - The data type is too wide */ -LIBSYSCALLS_GCC_ATTRIBUTES_(__nonnull__, __access__(__read_only__, 2), __access__(__read_write__, 3)) +LIBSYSCALLS_GCC_ATTRIBUTES_(__nonnull__, + __access__(__read_only__, 2), + __access__(__read_write__, 3)) enum libsyscalls_error -libsyscalls_to_tracee_endian(unsigned long long int, const struct libsyscalls_datatype_description *, void *, size_t); +libsyscalls_to_tracee_endian(unsigned long long int value_in, + const struct libsyscalls_datatype_description *type, + void *value_out, size_t out_offset); + /** * Get information on how an instance of struct or union is to be parsed @@ -2886,37 +3113,44 @@ libsyscalls_to_tracee_endian(unsigned long long int, const struct libsyscalls_da * structure's field, as it may contain important * adjustments * - * @param os The operating system the data type is used on - * @param arch The architecture the data type is used on - * @param datatype The data type - * @param data The data that is to be parsed (may be `NULL` if `data_size` is 0) - * @param data_size The number of bytes available in `data`, may be short or in excess - * @param description_out Output parameter for the type description; - * the caller responsible for deallocating the `*info_out` - * with free(3) when it is no longer needed. Be aware that - * `*info_out` will only be set when LIBSYSCALLS_E_OK is - * returned. - * @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 - `datatype` is not a valid data type - * LIBSYSCALLS_E_NOSUCHTYPE - `datatype` does not exist on the selected - * operating system (`os`) or architecture (`arch`) - * LIBSYSCALLS_E_ISNOTSTRUCT - `datatype` does not represent a structure or - * union, nor an array of structure or union + * @param os The operating system the data type is used on + * @param arch The architecture the data type is used on + * @param datatype The data type + * @param data The data that is to be parsed + * (may be `NULL` if `data_size` is 0) + * @param data_size The number of bytes available in `data`, + * may be short or in excess + * @param description_out Output parameter for the type description; + * the caller responsible for deallocating the `*info_out` + * with free(3) when it is no longer needed. Be aware that + * `*info_out` will only be set when LIBSYSCALLS_E_OK is + * returned. + * + * @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 - `datatype` is not a valid data type + * LIBSYSCALLS_E_NOSUCHTYPE - `datatype` does not exist on the selected + * operating system (`os`) or architecture (`arch`) + * LIBSYSCALLS_E_ISNOTSTRUCT - `datatype` does not represent a structure or + * union, nor an array of structure or union * * The function may complete successfully for some data * types even if it for other data types would return * LIBSYSCALLS_E_ARCHNOSUP */ #if 0 /* work in progress */ -LIBSYSCALLS_GCC_ATTRIBUTES_(__warn_unused_result__, __access__(__read_only__, 4, 5), __access__(__write_only__, 6)) +LIBSYSCALLS_GCC_ATTRIBUTES_(__warn_unused_result__, + __access__(__read_only__, 4, 5), + __access__(__write_only__, 6)) enum libsyscalls_error -libsyscalls_get_struct_description(enum libsyscalls_os, enum libsyscalls_arch, enum libsyscalls_datatype, - const void *, size_t, struct libsyscalls_structure_description **); +libsyscalls_get_struct_description(enum libsyscalls_os os, enum libsyscalls_arch arch, + enum libsyscalls_datatype datatype, + const void *data, size_t data_size, + struct libsyscalls_structure_description **description_out); #endif /* TODO add libsyscalls_get_struct_display_info */ |