diff --git a/doc/rrdthreads.1 b/doc/rrdthreads.1
index f9baa9ad2e78eec75d96730f2cfadaa053093d7c..dbbe8e533bae2fd06419939df188f5d1c943cc3a 100644 (file)
--- a/doc/rrdthreads.1
+++ b/doc/rrdthreads.1
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.08)
.\"
.\" Standard preamble:
.\" ========================================================================
.\"
.\" Standard preamble:
.\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
. ds R" ''
'br\}
.\"
. ds R" ''
'br\}
.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
-.if \nF \{\
+.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
-.\"
-.\" For nroff, turn off justification. Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
+.el \{\
+. de IX
+..
+.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
.\" ========================================================================
.\"
.IX Title "RRDTHREADS 1"
.\" ========================================================================
.\"
.IX Title "RRDTHREADS 1"
-.TH RRDTHREADS 1 "2008-03-15" "1.3rc4" "rrdtool"
+.TH RRDTHREADS 1 "2009-04-19" "1.3.999" "rrdtool"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
.SH "NAME"
rrdthreads \- Provisions for linking the RRD library to use in multi\-threaded programs
.SH "SYNOPSIS"
.SH "NAME"
rrdthreads \- Provisions for linking the RRD library to use in multi\-threaded programs
.SH "SYNOPSIS"
thread-safe at all. This document describes requirements and pitfalls
on the way to use the multi-threaded version of librrd in your own
programs. It also gives hints for future \s-1RRD\s0 development to keep the
thread-safe at all. This document describes requirements and pitfalls
on the way to use the multi-threaded version of librrd in your own
programs. It also gives hints for future \s-1RRD\s0 development to keep the
-library thread\-safe.
+library thread-safe.
.PP
Currently only some \s-1RRD\s0 operations are implemented in a thread-safe
way. They all end in the usual "\f(CW\*(C`_r\*(C'\fR" suffix.
.PP
Currently only some \s-1RRD\s0 operations are implemented in a thread-safe
way. They all end in the usual "\f(CW\*(C`_r\*(C'\fR" suffix.
Use the "\f(CW\*(C`_r\*(C'\fR" functions instead of the normal API-functions
.IP "\(bu" 4
Do not use any at-style time specifications. Parsing of such time
Use the "\f(CW\*(C`_r\*(C'\fR" functions instead of the normal API-functions
.IP "\(bu" 4
Do not use any at-style time specifications. Parsing of such time
-specifications is terribly non\-thread\-safe.
+specifications is terribly non-thread-safe.
.IP "\(bu" 4
Never use non *\f(CW\*(C`_r\*(C'\fR functions unless it is explicitly documented that
.IP "\(bu" 4
Never use non *\f(CW\*(C`_r\*(C'\fR functions unless it is explicitly documented that
-the function is tread\-safe.
+the function is tread-safe.
.IP "\(bu" 4
Every thread \s-1SHOULD\s0 call \f(CW\*(C`rrd_get_context()\*(C'\fR before its first call to
any \f(CW\*(C`librrd_th\*(C'\fR function in order to set up thread specific data. This
.IP "\(bu" 4
Every thread \s-1SHOULD\s0 call \f(CW\*(C`rrd_get_context()\*(C'\fR before its first call to
any \f(CW\*(C`librrd_th\*(C'\fR function in order to set up thread specific data. This
.IP "\(bu" 4
Always call \f(CW\*(C`rrd_error_clear()\*(C'\fR before any call to the
library. Otherwise the call might fail due to some earlier error.
.IP "\(bu" 4
Always call \f(CW\*(C`rrd_error_clear()\*(C'\fR before any call to the
library. Otherwise the call might fail due to some earlier error.
-.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1RRD\s0 \s-1CONTRIBUTORS\s0"
+.SS "\s-1NOTES\s0 \s-1FOR\s0 \s-1RRD\s0 \s-1CONTRIBUTORS\s0"
.IX Subsection "NOTES FOR RRD CONTRIBUTORS"
Some precautions must be followed when developing \s-1RRD\s0 from now on:
.IP "\(bu" 4
Only use thread-safe functions in library code. Many often used libc
.IX Subsection "NOTES FOR RRD CONTRIBUTORS"
Some precautions must be followed when developing \s-1RRD\s0 from now on:
.IP "\(bu" 4
Only use thread-safe functions in library code. Many often used libc
-functions aren't thread\-safe. Take care in the following
+functions aren't thread-safe. Take care in the following
situations or when using the following library functions:
.RS 4
.IP "\(bu" 4
situations or when using the following library functions:
.RS 4
.IP "\(bu" 4
@@ -179,7 +178,7 @@ Direct calls to \f(CW\*(C`strerror()\*(C'\fR must be avoided: use \f(CW\*(C`rrd_
instead, it provides a per-thread error message.
.IP "\(bu" 4
The \f(CW\*(C`getpw*\*(C'\fR, \f(CW\*(C`getgr*\*(C'\fR, \f(CW\*(C`gethost*\*(C'\fR function families (and some more
instead, it provides a per-thread error message.
.IP "\(bu" 4
The \f(CW\*(C`getpw*\*(C'\fR, \f(CW\*(C`getgr*\*(C'\fR, \f(CW\*(C`gethost*\*(C'\fR function families (and some more
-\&\f(CW\*(C`get*\*(C'\fR functions) are not thread\-safe: use the *\f(CW\*(C`_r\*(C'\fR variants
+\&\f(CW\*(C`get*\*(C'\fR functions) are not thread-safe: use the *\f(CW\*(C`_r\*(C'\fR variants
.IP "\(bu" 4
Time functions: \f(CW\*(C`asctime\*(C'\fR, \f(CW\*(C`ctime\*(C'\fR, \f(CW\*(C`gmtime\*(C'\fR, \f(CW\*(C`localtime\*(C'\fR: use
*\f(CW\*(C`_r\*(C'\fR variants
.IP "\(bu" 4
Time functions: \f(CW\*(C`asctime\*(C'\fR, \f(CW\*(C`ctime\*(C'\fR, \f(CW\*(C`gmtime\*(C'\fR, \f(CW\*(C`localtime\*(C'\fR: use
*\f(CW\*(C`_r\*(C'\fR variants
that works with the \s-1GNU\s0 C\-preprocessor to \*(L"poison\*(R" some of the most
common non-thread-safe functions using the \f(CW\*(C`#pragma GCC poison\*(C'\fR
directive. Just include this header in source files you want to keep
that works with the \s-1GNU\s0 C\-preprocessor to \*(L"poison\*(R" some of the most
common non-thread-safe functions using the \f(CW\*(C`#pragma GCC poison\*(C'\fR
directive. Just include this header in source files you want to keep
-thread\-safe.
+thread-safe.
.IP "\(bu" 4
Do not introduce global variables!
.Sp
.IP "\(bu" 4
Do not introduce global variables!
.Sp
**argv arguments for variable length argument lists. See
\&\f(CW\*(C`rrd_update_r\*(C'\fR as an example.
.IP "\(bu" 4
**argv arguments for variable length argument lists. See
\&\f(CW\*(C`rrd_update_r\*(C'\fR as an example.
.IP "\(bu" 4
-Do not use the \f(CW\*(C`parsetime\*(C'\fR function!
+Do not use the \f(CW\*(C`rrd_parsetime\*(C'\fR function!
.Sp
It uses lots of global variables. You may use it in functions not designed
.Sp
It uses lots of global variables. You may use it in functions not designed
-to be thread\-safe, like in functions wrapping the \f(CW\*(C`_r\*(C'\fR version of some
+to be thread-safe, like in functions wrapping the \f(CW\*(C`_r\*(C'\fR version of some
operation (e.g., \f(CW\*(C`rrd_create\*(C'\fR, but not in \f(CW\*(C`rrd_create_r\*(C'\fR)
operation (e.g., \f(CW\*(C`rrd_create\*(C'\fR, but not in \f(CW\*(C`rrd_create_r\*(C'\fR)
-.Sh "\s-1CURRENTLY\s0 \s-1IMPLEMENTED\s0 \s-1THREAD\s0 \s-1SAFE\s0 \s-1FUNCTIONS\s0"
+.SS "\s-1CURRENTLY\s0 \s-1IMPLEMENTED\s0 \s-1THREAD\s0 \s-1SAFE\s0 \s-1FUNCTIONS\s0"
.IX Subsection "CURRENTLY IMPLEMENTED THREAD SAFE FUNCTIONS"
Currently there exist thread-safe variants of \f(CW\*(C`rrd_update\*(C'\fR,
\&\f(CW\*(C`rrd_create\*(C'\fR, \f(CW\*(C`rrd_dump\*(C'\fR, \f(CW\*(C`rrd_info\*(C'\fR, \f(CW\*(C`rrd_last\*(C'\fR, and \f(CW\*(C`rrd_fetch\*(C'\fR.
.IX Subsection "CURRENTLY IMPLEMENTED THREAD SAFE FUNCTIONS"
Currently there exist thread-safe variants of \f(CW\*(C`rrd_update\*(C'\fR,
\&\f(CW\*(C`rrd_create\*(C'\fR, \f(CW\*(C`rrd_dump\*(C'\fR, \f(CW\*(C`rrd_info\*(C'\fR, \f(CW\*(C`rrd_last\*(C'\fR, and \f(CW\*(C`rrd_fetch\*(C'\fR.