Second commit

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 57 insertions, 26 deletions

diff --git a/libsyscalls.h b/libsyscalls.h
index f63d023..4c904b7 100644
--- a/libsyscalls.h
+++ b/libsyscalls.h
@@ -12,10 +12,10 @@
  * 
  * The numbers are stored in `libsyscalls_error`
  * 
- * @param  X(NAME, STR)  Macro that expands, will be given two arguments:
- *                       the enum value name of the error (identifier),
- *                       and the description of the error (string literal)
- * @param  D             Macro that expands between each expansion of X
+ * @param  X:macro(NAME, STR)  Macro that expands, will be given two arguments:
+ *                             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
@@ -281,7 +281,7 @@ enum libsyscalls_syscall_category {
 
 /* IPC that can but does not have to be over a network,
  * "bind" system calls can create inodes in the file system */
-enum libsyscalls_syscall_network_enabled_ipc_subcategory {
+enum libsyscalls_network_enabled_ipc_syscall_subcategory {
 	LIBSYSCALLS_NETWORK_ENABLED_IPC_SUBCAT_ACCEPT,
 	LIBSYSCALLS_NETWORK_ENABLED_IPC_SUBCAT_LISTEN,
 	LIBSYSCALLS_NETWORK_ENABLED_IPC_SUBCAT_BIND,
@@ -289,7 +289,7 @@ enum libsyscalls_syscall_network_enabled_ipc_subcategory {
 	LIBSYSCALLS_NETWORK_ENABLED_IPC_SUBCAT_STAT
 };
 
-enum libsyscalls_syscall_ipc_subcategory {
+enum libsyscalls_ipc_syscall_subcategory {
 	LIBSYSCALLS_IPC_SUBCAT_ADVISORY_FILE_LOCK,
 	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) */
@@ -302,7 +302,7 @@ enum libsyscalls_syscall_ipc_subcategory {
 };
 
 /* syscalls that can work on either paths or FDs ([1]) are located here */
-enum libsyscalls_syscall_filesystem_subcategory {
+enum libsyscalls_filesystem_syscall_subcategory {
 	LIBSYSCALLS_FILESYSTEM_SUBCAT_STAT,
 	LIBSYSCALLS_FILESYSTEM_SUBCAT_MODIFY,
 	LIBSYSCALLS_FILESYSTEM_SUBCAT_SYNC, /* [1] some of these only work on file descriptors or memory maps */
@@ -319,7 +319,7 @@ enum libsyscalls_syscall_filesystem_subcategory {
 };
 
 /* syscalls that work FDs but not paths are located here */
-enum libsyscalls_syscall_file_descriptors_subcategory {
+enum libsyscalls_file_syscall_descriptors_subcategory {
 	LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_STAT,
 	LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_MODIFY,
 	LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_DUP_OR_CLOSE, /* includes partial close (shutdown) */
@@ -340,7 +340,7 @@ enum libsyscalls_syscall_file_descriptors_subcategory {
 	LIBSYSCALLS_FILE_DESCRIPTORS_SUBCAT_POLL /* can work as pause or relative sleep */
 };
 
-enum libsyscalls_syscall_processes_subcategory {
+enum libsyscalls_processes_syscall_subcategory {
 	LIBSYSCALLS_PROCESSES_SUBCAT_EXIT,
 	LIBSYSCALLS_PROCESSES_SUBCAT_STAT_SELF,
 	LIBSYSCALLS_PROCESSES_SUBCAT_STAT_CHILD, /* may also stat self */
@@ -354,11 +354,11 @@ enum libsyscalls_syscall_processes_subcategory {
 	LIBSYSCALLS_PROCESSES_SUBCAT_SESSION /* vhangup, setsid, setpgid */
 };
 
-enum libsyscalls_syscall_logging_subcategory {
+enum libsyscalls_logging_syscall_subcategory {
 	LIBSYSCALLS_LOGGING_SUBCAT_PROCESSES
 };
 
-enum libsyscalls_syscall_time_subcategory {
+enum libsyscalls_time_syscall_subcategory {
 	LIBSYSCALLS_TIME_SUBCAT_GET_OR_SET,
 	LIBSYSCALLS_TIME_SUBCAT_GET,
 	LIBSYSCALLS_TIME_SUBCAT_SET,
@@ -377,13 +377,13 @@ enum libsyscalls_syscall_time_subcategory {
 	LIBSYSCALLS_TIME_SUBCAT_SLEEP
 };
 
-enum libsyscalls_syscall_signals_subcategory {
+enum libsyscalls_signals_syscall_subcategory {
 	LIBSYSCALLS_SIGNALS_SUBCAT_PAUSE,
 	LIBSYSCALLS_SIGNALS_SUBCAT_KILL
 };
 
 /* These may work on memory mapped files */
-enum libsyscalls_syscall_memory_subcategory {
+enum libsyscalls_memory_syscall_subcategory {
 	LIBSYSCALLS_MEMORY_SUBCAT_ALLOCATE,
 	LIBSYSCALLS_MEMORY_SUBCAT_READ,
 	LIBSYSCALLS_MEMORY_SUBCAT_WRITE,
@@ -394,7 +394,7 @@ enum libsyscalls_syscall_memory_subcategory {
 	LIBSYSCALLS_MEMORY_SUBCAT_STAT /* stats memory allocated to the process, not system resources */
 };
 
-enum libsyscalls_syscall_system_subcategory {
+enum libsyscalls_system_syscall_subcategory {
 	LIBSYSCALLS_SYSTEM_SUBCAT_SWAP,
 	LIBSYSCALLS_SYSTEM_SUBCAT_REBOOT,
 	LIBSYSCALLS_SYSTEM_SUBCAT_GET_NAME,
@@ -404,7 +404,7 @@ enum libsyscalls_syscall_system_subcategory {
 	LIBSYSCALLS_SYSTEM_SUBCAT_FUNDAMENTAL
 };
 
-enum libsyscalls_syscall_scheduling_subcategory {
+enum libsyscalls_scheduling_syscall_subcategory {
 	LIBSYSCALLS_SCHEDULING_SUBCAT_YEILD,
 	LIBSYSCALLS_SCHEDULING_SUBCAT_SET,
 	LIBSYSCALLS_SCHEDULING_SUBCAT_GET,
@@ -412,17 +412,17 @@ enum libsyscalls_syscall_scheduling_subcategory {
 };
 
 union libsyscalls_syscall_subcategory {
-	enum_libsyscalls_syscall_network_enabled_ipc_subcategory network_enabled_ipc;
-	enum_libsyscalls_syscall_ipc_subcategory ipc;
-	enum_libsyscalls_syscall_filesystem_subcategory filesystem;
-	enum_libsyscalls_syscall_file_descriptors_subcategory file_descriptors;
-	enum_libsyscalls_syscall_processes_subcategory processes;
-	enum_libsyscalls_syscall_logging_subcategory logging;
-	enum_libsyscalls_syscall_time_subcategory time;
-	enum_libsyscalls_syscall_signals_subcategory signals;
-	enum_libsyscalls_syscall_memory_subcategory memory;
-	enum_libsyscalls_syscall_system_subcategory system;
-	enum_libsyscalls_syscall_scheduling_subcategory scheduling;
+	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;
 };
 
 /**
@@ -1145,8 +1145,23 @@ struct libsyscalls_datatype_description {
 	 * Data types for register-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
 	 */
 	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.
+	 * 
+	 * @param   SHIFT  The value to test `struct libsyscalls_datatype_description.byteorder`
+	 * @return  :int   Whether the value is ~0
+	 */
+#define LIBSYSCALLS_IS_BYTEORDER_END(SHIFT)\
+	(!~((SHIFT) | ~LIBSYSCALLS_FIELD_MASK_(1ULL, struct libsyscalls_datatype_description, byteorder[0])))
 };
 
 
@@ -1185,6 +1200,10 @@ libsyscalls_perror(const char *, enum libsyscalls_error);
  *                                             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
+ * 
  * Beware that range is used system call numbers are [*min_out, *max_out]
  * (not [*min_out, *max_out - 1]) but there may still be numbers within
  * this range that does not correspond to a system call
@@ -1211,6 +1230,10 @@ libsyscalls_get_syscall_range(enum libsyscalls_os, enum libsyscalls_arch, long l
  *                       LIBSYSCALLS_E_NOSUCHSYSCALL - `syscallnr` 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__)
 enum libsyscalls_error
@@ -1237,6 +1260,10 @@ libsyscalls_get_syscall(enum libsyscalls_os, enum libsyscalls_arch, long long in
  *                                                    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
  */
 enum libsyscalls_error
 libsyscalls_get_syscall_errors(enum libsyscalls_os, enum libsyscalls_arch, const struct libsyscalls_named_number **, size_t *);
@@ -1262,6 +1289,10 @@ libsyscalls_get_syscall_errors(enum libsyscalls_os, enum libsyscalls_arch, const
  *                                                      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
  */
 enum libsyscalls_error
 libsyscalls_get_signals(enum libsyscalls_os, enum libsyscalls_arch, const struct libsyscalls_named_number **, size_t *);