String processing

Basic string operations

There exists a small set of string-manipulation operations as global functions in the Genode namespace.

To cover the common case of embedding a string buffer as a member variable in a class, there exists the String class template, which alleviates the need for C-style arrays in such situations.

The String constructor takes any number of arguments, which will appear concatenated in the constructed String. Each argument must be printable as explained in Section Diagnostic output.

Genode::String

There exist a number of printable helper classes that cover typical use cases for producing formatted text output.

Number_of_bytes: wraps an integer value and produces an output suffixed with K, M, or G whenever the value is a multiple of a kilobyte, megabyte, or gigabyte.
Cstring: wraps a plain C character array to make it printable. There exist two constructors. The constructor with one argument expects a null-terminated character array. The other constructor takes the number of to-be-printed characters as arguments.
Hex: wraps an integer value and produces hexadecimal output.
Char: produces a character corresponding to the ASCII value the wrapped integer argument.

To improve safety in situations that require raw byte-wise access of memory, the two utilities Byte_range_ptr and Const_byte_range_ptr hold a pointer together with a size limit in bytes. They should be used instead of traditional C-style pairs of pointer and size arguments to equip each pointer with its legitimate range of access. Note that the utilities are meant for transient arguments only. They are deliberately not copyable to prevent the accidental storing of the embedded pointer values.

Tokenizing

For parsing structured text such as argument strings or XML, simple tokenizing support is provided via the Token class.

Genode::Token

Diagnostic output

To enable components to produce diagnostic output like errors, warnings, and log messages, Genode offers a simple Output interface for sequentially writing single characters or character sequences.

Genode::Output

Functions for generating output for different types are named print and take an Output & as first argument. The second argument is a const & to the value to print. Overloads of the print function for commonly used basic types are provided. Furthermore, there is a function template that is used if none of the type-specific overloads match. This function template expects the argument to be an object with a print method. In contrast to a plain print function overload, such a method is able to incorporate private state into the output.

repos/base/include/base/output.h

The component's execution environment provides an implementation of the Output interface that targets a LOG session. This output back end is offered to the component in the form of the log, warning, error, and trace functions that accept an arbitrary number of arguments that are printed in a concatenated fashion. Each message is implicitly finalized with a newline character.

repos/base/include/base/log.h

Obtaining backtraces

As debugging aid, it is sometimes insightful to obtain call graphs of executed code. Such backtraces can be generated via the utilities provided by os/backtrace.h. As a precondition for getting useful output, make sure to have compiled your executable binary with frame pointers. By adding the following line to the etc/build.conf file of the build directory, one can instruct the build system to produce binaries in the needed form.

 CC_OPT += -fno-omit-frame-pointer

The general mechanism for generating a backtrace has the form of the printable Backtrace class. An object of this type can be passed to any of the log, warning, error, or trace functions to output the backtrace of the point of call. As a convenient shortcut for the common case of printing a backtrace to the log, one can call the backtrace() function instead. The output looks like in the following example.

 [init -> test-log] backtrace "ep"
 [init -> test-log]   401ff89c   10014f4
 [init -> test-log]   401ff90c   1001637
 [init -> test-log]   401ff94c   10006e2
 [init -> test-log]   401ffaec  5008aa9f
 [init -> test-log]   401ffc6c  50048dbb
 [init -> test-log]   401ffc8c  5004be41
 [init -> test-log]   401ffcdc  5003a04d
 [init -> test-log]   401ffe6c  50065218
 [init -> test-log]   401fff7c  50079d54

The first line contains the thread name of the caller, which is followed by one line per stack frame. The first number is the stack address whereas the second line is the return address of the stack frame, both given in hexadecimal format. The latter can be correlated to source code by inspecting the disassembled binary using the objdump utility. In practice, however, one may prefer the convenience of the tool/backtrace utility to streamline this procedure.

Execute the backtrace tool with the debug version of your executable as argument. For example, after having observed a backtrace printed by the test-log program, one may issue:
```
 build/x86_64$ ../../tool/backtrace debug/test-log
```
Once started, the tool waits for you pasting the logged backtrace into the terminal. For each stack frame, it then prints the corresponding function name and source-code location.

Unicode handling

The string-handling utilities described in Section Basic string operations operate on ASCII-encoded character strings where each character is encoded as one byte. It goes without saying that ASCII is unsuitable for user-facing components that are ultimately expected to support the display of international characters. The Utf8_ptr utility accommodates such components with an easy way to extract a sequence of Unicode codepoints from an UTF-8-encoded string.

Genode::Utf8_ptr