libc/docs/redirectors.rst

   1 Redirectors
   2 ===========
   3
   4 When implementing a new C standard library (referred to as *libc* henceforth in
   5 this document) starting from scratch, it is unrealistic to expect that we will
   6 have the entire library available from day one. In such a scenario, a practical
   7 approach is to redirect calls to the unimplemented functions to the same
   8 functions from another fully functional libc implementation. Such a scheme can
   9 also serve users who would like to mix and match implementations from LLVM libc
  10 and another libc implementation. On most platforms, this other libc can be the
  11 system libc itself. In this document, we present a strategy one can employ to
  12 build redirectors to redirect from LLVM libc to the system libc. For now, the
  13 scheme presented is limited to ELF platforms.
  14
  15 Highlevel Mechanism
  16 -------------------
  17
  18 The highlevel scheme is as below:
  19
  20 <img src="./redirectors_schematic.svg">
  21
  22 As shown in the diagram, the mechanism involves a redirector dynamic library
  23 which goes in between the llvm-libc static library and the system libc dynamic
  24 library. Essentially, LLVM libc provides implementations for all public
  25 functions. However, some of the implementations do not actually implement the
  26 expected functionality. Instead, they just call the corresponding function in
  27 the redirector library, which in turn calls the same function from the system
  28 libc.
  29
  30 Implementation of redirecting entrypoints
  31 -----------------------------------------
  32
  33 Let us take the ``round`` function from ``math.h`` as an example to see what
  34 it's implementation looks like when it just redirects to the ``round`` function
  35 from the system libc.
  36
  37 ::
  38     namespace llvm_libc {
  39
  40     double __redirected_round(double);
  41
  42     double LLVM_LIBC_ENTRYPOINT(round)(double x) {
  43         return __redirected_round(x);
  44     }
  45
  46     } // namespace llvm_libc
  47
  48 As can be seen, the ``round`` function from LLVM libc does not call the
  49 ``round`` function from the system libc directly. It calls a function
  50 ``__redirected_round`` from the redirector library. The rest of the
  51 code follows the conventions described in the *implementation standard*
  52 document.
  53
  54 Implementation of the redirector function
  55 -----------------------------------------
  56
  57 The function ``__redirected_round`` calls the ``round`` function from the system
  58 libc. Its implementation is as follows::
  59
  60     #include <math.h>  // Header file from the system libc
  61
  62     namespace llvm_libc {
  63
  64     double __redirected_round(double x) {
  65         return ::round(x);  // Call to round from the system libc
  66     }
  67
  68     } // namespace llvm_libc
  69