_R_R_D_T_H_R_E_A_D_S(1)                        rrdtool                       _R_R_D_T_H_R_E_A_D_S(1)

NNAAMMEE
     rrdthreads   -   Provisions   for   linking  the  RRD  library  to  use  in
     multi-threaded programs

SSYYNNOOPPSSIISS
     Using librrd in multi-threaded programs requires  some  extra  precautions.
     This  document describes requirements and pitfalls on the way to use librrd
     in your own programs. It also gives hints for  future  RRD  development  to
     keep the library thread-safe.

     Since  RRDtool  1.6,  _l_i_b_r_r_d is thread-safe and no separate thread-specific
     library is needed.

DDEESSCCRRIIPPTTIIOONN
     In order to use librrd in multi-threaded programs you must:

     •   Link with _l_i_b_r_r_d (use "-lrrd" when linking)

     •   Use the ""_r"" functions instead of the normal API-functions

     •   Do not use any at-style time specifications. Parsing of such time spec‐
         ifications is terribly non-thread-safe.

     •   Never use non *"_r" functions unless it is explicitly  documented  that
         the function is thread-safe.

     •   Every thread SHOULD call rrd_get_context() before its first call to any
         "librrd"  function in order to set up thread specific data. This is not
         strictly required, but it is the only way to test if memory  allocation
         can  be  done  by  this  function. Otherwise the program may die with a
         SIGSEGV in a low-memory situation.

     •   Always call rrd_clear_error() before any call to the library. Otherwise
         the call might fail due to some earlier error.

   NNOOTTEESS FFOORR RRRRDD CCOONNTTRRIIBBUUTTOORRSS
     Some precautions must be followed when developing RRD from now on:

     •   Only use thread-safe functions in library code. Many  often  used  libc
         functions  aren't thread-safe. Take care in the following situations or
         when using the following library functions:

         •   Direct calls to strerror() must be avoided: use rrd_strerror()  in‐
             stead, it provides a per-thread error message.

         •   The "getpw*", "getgr*", "gethost*" function families (and some more
             "get*" functions) are not thread-safe: use the *"_r" variants

         •   Time  functions:  "asctime",  "ctime",  "gmtime",  "localtime": use
             *"_r" variants

         •   "strtok": use "strtok_r"

         •   "tmpnam": use "tmpnam_r"

         •   Many others (lookup documentation)

     •   A header file named _r_r_d___i_s___t_h_r_e_a_d___s_a_f_e_._h is provided  that  works  with
         the   GNU   C-preprocessor   to   "poison"  some  of  the  most  common
         non-thread-safe functions using the  "#pragma  GCC  poison"  directive.
         Just include this header in source files you want to keep thread-safe.

     •   Do not introduce global variables!

         If  you  really, really have to use a global variable you may add a new
         field  to  the  "rrd_context"   structure   and   modify   _r_r_d___e_r_r_o_r_._c,
         _r_r_d___t_h_r_e_a_d___s_a_f_e_._c and _r_r_d___n_o_n___t_h_r_e_a_d___s_a_f_e_._c

     •   Do not use "getopt" or "getopt_long" in *"_r" (neither directly nor in‐
         directly).

         "getopt"  uses  global  variables and behaves badly in a multi-threaded
         application when called concurrently. Instead provide  a  *_r  function
         taking  all  options  as  function parameters. You may provide argc and
         **argv arguments for variable length argument lists. See "rrd_update_r"
         as an example.

     •   Do not use the "rrd_parsetime" function!

         It uses lots of global variables. You may use it in functions  not  de‐
         signed  to  be thread-safe, like in functions wrapping the "_r" version
         of some operation (e.g., "rrd_create", but not in "rrd_create_r")

   CCUURRRREENNTTLLYY IIMMPPLLEEMMEENNTTEEDD TTHHRREEAADD SSAAFFEE FFUUNNCCTTIIOONNSS
     Currently there exist thread-safe variants of  "rrd_update",  "rrd_create",
     "rrd_dump", "rrd_info", "rrd_last", and "rrd_fetch".

AAUUTTHHOORR
     Peter Stamfest <peter@stamfest.at>

1.10.2                             2026-06-03                      _R_R_D_T_H_R_E_A_D_S(1)
