Restartable Sequences (The GNU C Library)

#### 36.2.9.7 Restartable Sequences ¶

This section describes restartable sequences integration for the GNU C Library. This functionality is only available on Linux.

Data Type: struct rseq ¶

  The type of the restartable sequences area. Future versions of Linux may add additional fields to the end of this structure.

  Users need to obtain the address of the restartable sequences area using the thread pointer and the `__rseq_offset` variable, described below.

  One use of the restartable sequences area is to read the current CPU number from its `cpu_id` field, as an inline version of `sched_getcpu`. The GNU C Library sets the `cpu_id` field to `RSEQ_CPU_ID_REGISTRATION_FAILED` if registration failed or was explicitly disabled.

  Furthermore, users can store the address of a `struct rseq_cs` object into the `rseq_cs` field of `struct rseq`, thus informing the kernel that the thread enters a restartable sequence critical section. This pointer and the code areas it itself points to must not be left pointing to memory areas which are freed or re-used. Several approaches can guarantee this. If the application or library can guarantee that the memory used to hold the `struct rseq_cs` and the code areas it refers to are never freed or re-used, no special action must be taken. Else, before that memory is re-used of freed, the application is responsible for setting the `rseq_cs` field to `NULL` in each thread’s restartable sequence area to guarantee that it does not leak dangling references. Because the application does not typically have knowledge of libraries’ use of restartable sequences, it is recommended that libraries using restartable sequences which may end up freeing or re-using their memory set the `rseq_cs` field to `NULL` before returning from library functions which use restartable sequences.

  The manual for the `rseq` system call can be found at https://git.kernel.org/pub/scm/libs/librseq/librseq.git/tree/doc/man/rseq.2.

Variable: `ptrdiff_t` __rseq_offset ¶

  This variable contains the offset between the thread pointer (as defined by `__builtin_thread_pointer` or the thread pointer register for the architecture) and the restartable sequences area. This value is the same for all threads in the process. If the restartable sequences area is located at a lower address than the location to which the thread pointer points, the value is negative.

Variable: `unsigned int` __rseq_size ¶

  This variable is either zero (if restartable sequence registration failed or has been disabled) or the size of the restartable sequence registration. This can be different from the size of `struct rseq` if the kernel has extended the size of the registration. If registration is successful, `__rseq_size` is at least 20 (the initially active size of `struct rseq`).

  Previous versions of the GNU C Library set this to 32 even if the kernel only supported the initial area of 20 bytes because the value included unused padding at the end of the restartable sequence area.

Variable: `unsigned int` __rseq_flags ¶

  The flags used during restartable sequence registration with the kernel. Currently zero.

Macro: `int` RSEQ_SIG ¶

  Each supported architecture provides a `RSEQ_SIG` macro in `sys/rseq.h` which contains a signature. That signature is expected to be present in the code before each restartable sequences abort handler. Failure to provide the expected signature may terminate the process with a segmentation fault.