Changes between Initial Version and Version 1 of Printf

Timestamp:

2012-07-03T14:03:28Z (12 years ago)

Author:

Vojtech Horky

Comment:

Initial commit

Printf

@@ +1 @@
+= Using `printf` in a safe way =
+
+To ensure portability among different architectures (namely between 32bit and 64bit), do not use generic directives (e.g. `%d`) for printing types with fixed width or for user-defined types. Use HelenOS-specific macros - such as `PRIu32` (unsigned integer, 32bits) - instead.
+
+These macros hide the type modifier only, you can provide width specification and you must enter the leading percentile sign.
+
+The `PRI*` macros are defined in two places `/common.h` (yes, in the root directory of HelenOS source) and in `/uspace/lib/c/arch/ARCHITECTURE/include/inttypes.h`. `common.h` is a generated file that appears after you configure your build.
+
+== Fixed width ==
+
+The macro is of from `PRI<kind><width>`. `<width>` is one of 8, 16, 32 or 64 or `n` for native width. `<kind>` is summarized in following table.
+
+||= `<kind>` =||= Meaning =||
+|| `u` || unsigned integer, decimal ||
+|| `d` || signed integer, decimal ||
+|| `x` || unsigned integer, hexadecimal ||
+|| `o` || unsigned integer, octal ||
+
+== Handles ==
+
+Although handles in HelenOS have their own `typedef`, they are usually backed by integer or pointer. Integers are usually used for handles passed from servers to clients (e.g. devices, files). Typically, they use unsigned integer of the native size.
+Pointers are used for structures used only locally (same application) and are used to hide implementation details.
+
+Thus, for these handles one should use `PRIun` (makes more sense for integer backed handles) or `PRIxn` (usually for pointers).
+
+
+== Other ==
+
+Following table lists common types and allowed (recommended) ways of printing them.
+
+||= Type =||= Directive =||
+|| `size_t` || `"%zu"` ||
+|| `sysarg_t` || `PRIun` / `PRIxn` ||
+|| `uintptr_t` || `"%#" PRIxn` ||
+
+== Annotating your own printf-like functions ==
+
+If you are creating your own `printf`-like function, do not forget to add `PRINTF_ATTRIBUTE()` to it to force checking of the parameters.
+{{{
+#!c
+void my_logging_function(int level, const char *format, ...)
+    PRINTF_ATTRIBUTE(2, 3);
+// 2 .. second argument is the format string
+// 3 .. the variadic arguments are here (third parameter)
+}}}
+
+
+== Example ==
+
+{{{
+#!c
+devman_handle_t device_handle;
+printf("Handle = %" PRIun ".\n", device_handle);
+
+fid_t fibril_handle;
+printf("Fibril handle = %#" PRIxn ".\n", fibril_handle);
+
+uint32_t pci_register;
+printf("Register at 0x%08" PRIx32 ".\n", pci_register);
+
+int16_t small_value;
+printf("16bits: %" PRId16 ".\n", small_value);
+
+sysarg_t ipc_argument;
+printf("IPC  arg1 = %20" PRIun ".\n", ipc_argument);
+
+size_t buffer_size;
+printf("Buffer has %zuB.\n", buffer_size);
+
+uintptr_t pointer_as_number;
+printf("Data at %p or at %#" PRIxn ".\n", (void *) pointer_as_number, pointer_as_number);
+
+void *pointer;
+printf("Pointer is built-in: %p.\n", pointer);
+}}}
+
+
+