Restartable Sequences (The GNU C Library)

35.2.2.5 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 32 (the initial size of struct rseq).

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.