RRDTHREADS(1)                       rrdtool                      RRDTHREADS(1)

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

SYNOPSIS
       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, librrd is thread-safe and no separate thread-
       specific library is needed.

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

       •   Link with librrd (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
           specifications 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.

   NOTES FOR RRD CONTRIBUTORS
       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()
               instead, 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 rrd_is_thread_safe.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  rrd_error.c,
           rrd_thread_safe.c and rrd_non_thread_safe.c

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

           "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
           designed to be thread-safe, like in  functions  wrapping  the  "_r"
           version   of   some  operation  (e.g.,  "rrd_create",  but  not  in
           "rrd_create_r")

   CURRENTLY IMPLEMENTED THREAD SAFE FUNCTIONS
       Currently   there   exist   thread-safe   variants   of   "rrd_update",
       "rrd_create", "rrd_dump", "rrd_info", "rrd_last", and "rrd_fetch".

AUTHOR
       Peter Stamfest <peter@stamfest.at>

1.10.3                            2026-05-25                     RRDTHREADS(1)
