doc/librrd.1

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "LIBRRD 1"
 132 .TH LIBRRD 1 "2009-04-20" "1.3.99909060808" "rrdtool"
 133 .SH "NAME"
 134 librrd \- RRD library functions
 135 .SH "DESCRIPTION"
 136 .IX Header "DESCRIPTION"
 137 \&\fBlibrrd\fR contains most of the functionality in \fBRRDTool\fR.  The command
 138 line utilities and language bindings are often just wrappers around the
 139 code contained in \fBlibrrd\fR.
 140 .PP
 141 This manual page documents the \fBlibrrd\fR \s-1API\s0.
 142 .PP
 143 \&\fB\s-1NOTE:\s0\fR This document is a work in progress, and should be considered
 144 incomplete as long as this warning persists.  For more information about
 145 the \fBlibrrd\fR functions, always consult the source code.
 146 .SH "UTILITY FUNCTIONS"
 147 .IX Header "UTILITY FUNCTIONS"
 148 .IP "\fB\f(BIrrd_random()\fB\fR" 4
 149 .IX Item "rrd_random()"
 150 Generates random numbers just like \fIrandom()\fR.  This further ensures that
 151 the random number generator is seeded exactly once per process.
 152 .IP "\fBrrd_add_ptr(void ***dest, size_t *dest_size, void *src)\fR" 4
 153 .IX Item "rrd_add_ptr(void ***dest, size_t *dest_size, void *src)"
 154 Dynamically resize the array pointed to by \f(CW\*(C`dest\*(C'\fR.  \f(CW\*(C`dest_size\*(C'\fR is a
 155 pointer to the current size of \f(CW\*(C`dest\*(C'\fR.  Upon successful \fIrealloc()\fR, the
 156 \&\f(CW\*(C`dest_size\*(C'\fR is incremented by 1 and the \f(CW\*(C`src\*(C'\fR pointer is stored at the
 157 end of the new \f(CW\*(C`dest\*(C'\fR.  Returns 1 on success, 0 on failure.
 158 .Sp
 159 .Vb 5
 160 \&    type **arr = NULL;
 161 \&    type *elem = "whatever";
 162 \&    size_t arr_size = 0;
 163 \&    if (!rrd_add_ptr(&arr, &arr_size, elem))
 164 \&        handle_failure();
 165 .Ve
 166 .IP "\fBrrd_add_strdup(char ***dest, size_t *dest_size, char *src)\fR" 4
 167 .IX Item "rrd_add_strdup(char ***dest, size_t *dest_size, char *src)"
 168 Like \f(CW\*(C`rrd_add_ptr\*(C'\fR, except adds a \f(CW\*(C`strdup\*(C'\fR of the source string.
 169 .Sp
 170 .Vb 5
 171 \&    char **arr = NULL;
 172 \&    size_t arr_size = NULL;
 173 \&    char *str  = "example text";
 174 \&    if (!rrd_add_strdup(&arr, &arr_size, str))
 175 \&        handle_failure();
 176 .Ve
 177 .IP "\fBrrd_free_ptrs(void ***src, size_t *cnt)\fR" 4
 178 .IX Item "rrd_free_ptrs(void ***src, size_t *cnt)"
 179 Free an array of pointers allocated by \f(CW\*(C`rrd_add_ptr\*(C'\fR or
 180 \&\f(CW\*(C`rrd_add_strdup\*(C'\fR.  Also frees the array pointer itself.  On return, the
 181 source pointer will be \s-1NULL\s0 and the count will be zero.
 182 .Sp
 183 .Vb 3
 184 \&    /* created as above */
 185 \&    rrd_free_ptrs(&arr, &arr_size);
 186 \&    /* here, arr == NULL && arr_size == 0 */
 187 .Ve