From 4b7345f9345915c8061e4b37b26ce8887828c973 Mon Sep 17 00:00:00 2001 From: oetiker Date: Mon, 25 Apr 2005 17:31:11 +0000 Subject: [PATCH] another batch of fixes from fritz git-svn-id: svn://svn.oetiker.ch/rrdtool/branches/1.2/program@425 a5681a0c-68f1-0310-ab6d-d61299d08faa --- doc/bin_dec_hex.pod | 235 +++++++++++++++++++++++--------------------- doc/rpntutorial.pod | 34 ++++--- doc/rrdcgi.pod | 38 +++---- doc/rrdfetch.pod | 180 ++++++++++++++++++---------------- doc/rrdgraph_data.pod | 25 ++--- doc/rrdgraph_examples.pod | 21 ++-- doc/rrdgraph_graph.pod | 97 +++++++++--------- doc/rrdgraph_rpn.pod | 69 +++++++------ doc/rrdtool.pod | 245 ++++++++++++++++++++++++---------------------- doc/rrdtune.pod | 48 ++++----- doc/rrdtutorial.pod | 42 ++++---- doc/rrdupdate.pod | 67 +++++++------ doc/rrdxport.pod | 8 +- 13 files changed, 585 insertions(+), 524 deletions(-) diff --git a/doc/bin_dec_hex.pod b/doc/bin_dec_hex.pod index 3cec7a5..522820c 100644 --- a/doc/bin_dec_hex.pod +++ b/doc/bin_dec_hex.pod @@ -1,16 +1,18 @@ =head1 NAME -bin_dec_hex - About Binary, Decimal, Hexadecimal +bin_dec_hex - How to use binary, decimal, and hexadecimal notation. + +=for html
PDF version.
=head1 DESCRIPTION Most people use the decimal numbering system. This system uses ten symbols to represent numbers. When those ten symbols are used up, they -start all over again and increment the position just before this. The +start all over again and increment the position to the left. The digit 0 is only shown if it is the only symbol in the sequence, or if it is not the first one. -If this sounds cryptic to you, this is what I've said in numbers: +If this sounds cryptic to you, this is what I've just said in numbers: 0 1 @@ -29,17 +31,21 @@ If this sounds cryptic to you, this is what I've said in numbers: and so on. -Each time the digit nine should be incremented, it is reset to 0 and the -position before is incremented. Then number 9 can be seen as "00009" and -when we should increment 9, we reset it to zero and increment the digit -just before the 9 so the number becomes "00010". For zero's we write a -space if it is not the only digit (so: number 0) and if it is the first -digit: "00010" -> " 0010" -> " 010" -> " 10". It is not " 1 ". +Each time the digit nine is incremented, it is reset to 0 and the +position before (to the left) is incremented (from 0 to 1). Then +number 9 can be seen as "00009" and when we should increment 9, we +reset it to zero and increment the digit just before the 9 so the +number becomes "00010". Leading zeros we don't write except if it is +the only digit (number 0). And of course, we write zeros if they occur +anywhere inside or at the end of a number: + + "00010" -> " 0010" -> " 010" -> " 10", but not " 1 ". -This was pretty basic, you already knew this. Why did I tell it ? -Well, computers do not represent numbers with 10 different digits. They -know of only two different symbols, being 0 and 1. Apply the same rules -to this set of digits and you get the binary numbering system: +This was pretty basic, you already knew this. Why did I tell it? +Well, computers usually do not represent numbers with 10 different +digits. They only use two different symbols, namely "0" and "1". Apply +the same rules to this set of digits and you get the binary numbering +system: 0 1 @@ -59,42 +65,47 @@ to this set of digits and you get the binary numbering system: and so on. If you count the number of rows, you'll see that these are again 14 -different numbers. The numbers are the same and mean the same. It is -only a different representation. This means that you have to know the -representation used, or as it is called the numbering system or base. -Normally if we do not speak about the numbering system used, we're -using the decimal system. If we are talking about another numbering -system, we'll have to make that clear. There are a few wide-spread -methods to do so. One common form is to write 1010(2) which means that -you wrote down a number in the binary form. It is the number ten. -If you would write 1010 it means the number one thousand and ten. - -In books, another form is most used. It uses subscript (little chars, -more or less in between two rows). You can leave out the parentheses -in that case and write down the number in normal characters followed -with a little two just behind it. - -The numbering system used is also called the base. We talk of the number -1100 base 2, the number 12 base 10. - -For the binary system, is is common to write leading zero's. The numbers -are written down in series of four, eight or sixteen depending on the -context. - -We can use the binary form when talking to computers (...programming...) -but the numbers will have large representations. The number 65535 would -be written down as 1111111111111111(2) which is 16 times the digit 1. -This is difficult and prone to errors. Therefore we normally would use +different numbers. The numbers are the same and mean the same as in +the first list, we just used a different representation. This means +that you have to know the representation used, or as it is called the +numbering system or base. Normally, if we do not explicitly specify +the numbering system used, we implicitly use the decimal system. If we +want to use any other numbering system, we'll have to make that +clear. There are a few widely adopted methods to do so. One common +form is to write 1010(2) which means that you wrote down a number in +its binary representation. It is the number ten. If you would write +1010 without specifying the base, the number is interpreted as one +thousand and ten using base 10. + +In books, another form is common. It uses subscripts (little +characters, more or less in between two rows). You can leave out the +parentheses in that case and write down the number in normal +characters followed by a little two just behind it. + +As the numbering system used is also called the base, we talk of the +number 1100 base 2, the number 12 base 10. + +Within the binary system, it is common to write leading zeros. The +numbers are written down in series of four, eight or sixteen depending +on the context. + +We can use the binary form when talking to computers +(...programming...), but the numbers will have large +representations. The number 65'535 (often in the decimal system a ' is +used to separate blocks of three digits for readability) would be +written down as 1111111111111111(2) which is 16 times the digit 1. +This is difficult and prone to errors. Therefore, we usually would use another base, called hexadecimal. It uses 16 different symbols. First the symbols from the decimal system are used, thereafter we continue -with the alphabetic characters. We get 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, -B, C, D, E and F. This system is chosen because the hexadecimal form -can be converted into the binary system very easy (and back). +with alphabetic characters. We get 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, +A, B, C, D, E and F. This system is chosen because the hexadecimal +form can be converted into the binary system very easily (and back). There is yet another system in use, called the octal system. This was -more common in the old days but not anymore. You will find it in use -on some places so get used to it. The same story applies, but now with -only eight different symbols. +more common in the old days, but is not used very often anymore. As +you might find it in use sometimes, you should get used to it and +we'll show it below. It's the same story as with the other +representations, but with eight different symbols. Binary (2) Octal (8) @@ -127,7 +138,7 @@ only eight different symbols. Most computers used nowadays are using bytes of eight bits. This means that they store eight bits at a time. You can see why the octal system -is not the most preferred for that: You'd need three digits to represent +is not the most practical for that: You'd need three digits to represent the eight bits and this means that you'd have to use one complete digit to represent only two bits (2+3+3=8). This is a waste. For hexadecimal digits, you need only two digits which are used completely: @@ -135,29 +146,28 @@ digits, you need only two digits which are used completely: (2) (8) (10) (16) 11111111 377 255 FF -You can see why binary and hexadecimal can be converted quickly: -For each hexadecimal digit there are exactly four binary digits. -Take a binary number. Each time take four digits from the right and make -a hexadecimal digit from it (see the table above). Stop when there are -no more digits. -Other way around: Take a hexadecimal number. For each digit, write down -its binary equivalent. - -Computers (or rather the parsers running on them) would have a hard time -converting a number like 1234(16). Therefore hexadecimal numbers get a -prefix. This prefix depends on the language you're writing in. Some of -the prefixes are "0x" for C, "$" for Pascal, "#" for HTML. -It is common to assume that if a number starts with a zero, it is octal. -It does not matter what is used as long as you know what it is. -I will use "0x" for hexadecimal, "%" for binary and "0" for octal. -The following numbers are all the same, just the way they are written is -different: 021 0x11 17 %00010001 +You can see why binary and hexadecimal can be converted quickly: For +each hexadecimal digit there are exactly four binary digits. Take a +binary number: take four digits from the right and make a hexadecimal +digit from it (see the table above). Repeat this until there are no +more digits. And the other way around: Take a hexadecimal number. For +each digit, write down its binary equivalent. + +Computers (or rather the parsers running on them) would have a hard +time converting a number like 1234(16). Therefore hexadecimal numbers +are specified with a prefix. This prefix depends on the language +you're writing in. Some of the prefixes are "0x" for C, "$" for +Pascal, "#" for HTML. It is common to assume that if a number starts +with a zero, it is octal. It does not matter what is used as long as +you know what it is. I will use "0x" for hexadecimal, "%" for binary +and "0" for octal. The following numbers are all the same, just their represenatation (base) is different: 021 0x11 17 %00010001 To do arithmetics and conversions you need to understand one more thing. It is something you already know but perhaps you do not "see" it yet: -If you write down 1234, (so it is decimal) you are talking about the -number one thousand, two hundred and thirty four. In sort of a formula: +If you write down 1234, (no prefix, so it is decimal) you are talking +about the number one thousand, two hundred and thirty four. In sort of +a formula: 1 * 1000 = 1000 2 * 100 = 200 @@ -195,7 +205,7 @@ It is the same in all other representations: 3 * 8^1 4 * 8^0 -This example can not be done for binary as that system can only use two +This example can not be done for binary as that system only uses two symbols. Another example: %1010 would be @@ -205,68 +215,67 @@ symbols. Another example: 1 * 2^1 0 * 2^0 -It would have been more easy to convert it to its hexadecimal form and +It would have been easier to convert it to its hexadecimal form and just translate %1010 into 0xA. After a while you get used to it. You will -not need to do any calculations anymore but just know that 0xA means 10. +not need to do any calculations anymore, but just know that 0xA means 10. -To convert a decimal number into a hexadecimal one you could use the next -method. It will take some time to be able to do the estimates but it will -be more and more easy when you use the system more frequent. Another way -is presented to you thereafter. +To convert a decimal number into a hexadecimal you could use the next +method. It will take some time to be able to do the estimates, but it +will be easier when you use the system more frequently. We'll look at +yet another way afterwards. -First you will need to know how many positions will be used in the other -system. To do so, you need to know the maximum numbers. Well, that's not -so hard as it looks. In decimal, the maximum number that you can form -with two digits is "99". The maximum for three: "999". The next number -would need an extra position. Reverse this idea and you will see that -the number can be found by taking 10^3 (10*10*10 is 1000) minus 1 or -10^2 minus one. +First you need to know how many positions will be used in the other +system. To do so, you need to know the maximum numbers you'll be +using. Well, that's not as hard as it looks. In decimal, the maximum +number that you can form with two digits is "99". The maximum for +three: "999". The next number would need an extra position. Reverse +this idea and you will see that the number can be found by taking 10^3 +(10*10*10 is 1000) minus 1 or 10^2 minus one. -This can be done for hexadecimal too: +This can be done for hexadecimal as well: 16^4 = 0x10000 = 65536 16^3 = 0x1000 = 4096 16^2 = 0x100 = 256 16^1 = 0x10 = 16 -If a number is smaller than 65536 it will thus fit in four positions. -If the number is bigger than 4095, you will need to use position 4. -How many times can you take 4096 from the number without going below +If a number is smaller than 65'536 it will fit in four positions. +If the number is bigger than 4'095, you must use position 4. +How many times you can subtract 4'096 from the number without going below zero is the first digit you write down. This will always be a number from 1 to 15 (0x1 to 0xF). Do the same for the other positions. -Number is 41029. It is smaller than 16^4 but bigger than 16^3-1. This +Let's try with 41'029. It is smaller than 16^4 but bigger than 16^3-1. This means that we have to use four positions. -We can subtract 16^3 from 41029 ten times without going below zero. -The leftmost digit will be "A" so we have 0xA????. -The number is reduced to 41029 - 10*4096 = 41029-40960 = 69. +We can subtract 16^3 from 41'029 ten times without going below zero. +The left-most digit will therefore be "A", so we have 0xA????. +The number is reduced to 41'029 - 10*4'096 = 41'029-40'960 = 69. 69 is smaller than 16^3 but not bigger than 16^2-1. The second digit -is therefore "0" and we know 0xA0??. +is therefore "0" and we now have 0xA0??. 69 is smaller than 16^2 and bigger than 16^1-1. We can subtract 16^1 (which is just plain 16) four times and write down "4" to get 0xA04?. -Take 64 from 69 (69 - 4*16) and the last digit is 5 --> 0xA045. +Subtract 64 from 69 (69 - 4*16) and the last digit is 5 --> 0xA045. -The other method builds the number from the right. Take again 41029. -Divide by 16 and do not use fractions (only whole numbers). +The other method builds ub the number from the right. Let's try 41'029 +again. Divide by 16 and do not use fractions (only whole numbers). - 41029 / 16 is 2564 with a remainder of 5. Write down 5. - 2564 / 16 is 160 with a remainder of 4. Write the 4 before the 5. + 41'029 / 16 is 2'564 with a remainder of 5. Write down 5. + 2'564 / 16 is 160 with a remainder of 4. Write the 4 before the 5. 160 / 16 is 10 with no remainder. Prepend 45 with 0. 10 / 16 is below one. End here and prepend 0xA. End up with 0xA045. -Which method to use is up to you. Use whatever works for you. Personally -I use them both without being able to tell what method I use in each -case, it just depends on the number, I think. Fact is, some numbers -will occur frequently while programming, if the number is close then -I will use the first method (like 32770, translate into 32768 + 2 and -just know that it is 0x8000 + 0x2 = 0x8002). - +Which method to use is up to you. Use whatever works for you. I use +them both without being able to tell what method I use in each case, +it just depends on the number, I think. Fact is, some numbers will +occur frequently while programming. If the number is close to one I am +familiar with, then I will use the first method (like 32'770 which is +into 32'768 + 2 and I just know that it is 0x8000 + 0x2 = 0x8002). For binary the same approach can be used. The base is 2 and not 16, and the number of positions will grow rapidly. Using the second method -has the advantage that you can see very simple if you should write down +has the advantage that you can see very easily if you should write down a zero or a one: if you divide by two the remainder will be zero if it -was an even number and one if it was an odd number: +is an even number and one if it is an odd number: 41029 / 2 = 20514 remainder 1 20514 / 2 = 10257 remainder 0 @@ -315,10 +324,10 @@ Group %1010000001000101 by three and convert into octal: At first while adding numbers, you'll convert them to their decimal form and then back into their original form after doing the addition. If you use the other numbering system often, you will see that you'll -be able to do arithmetics in the base that is used. +be able to do arithmetics directly in the base that is used. In any representation it is the same, add the numbers on the right, -write down the rightmost digit from the result, remember the other -digits and use them in the next round. Continue with the second digits +write down the right-most digit from the result, remember the other +digits and use them in the next round. Continue with the second digit from the right and so on: %1010 + %0111 --> 10 + 7 --> 17 --> %00010001 @@ -336,16 +345,16 @@ will become -------- %10001 is the result, I like to write it as %00010001 -For low values, try to do the calculations yourself, check them with -a calculator. The more you do the calculations yourself, the more you +For low values, try to do the calculations yourself, then check them with +a calculator. The more you do the calculations yourself, the more you'll find that you didn't make mistakes. In the end, you'll do calculi in -other bases as easy as you do in decimal. +other bases as easily as you do them in decimal. When the numbers get bigger, you'll have to realize that a computer is -not called a computer just to have a nice name. There are many different -calculators available. Use them. For Unix you could use "bc" which is -called so as it is short for Binary Calculator. It calculates not only -in decimal, but in all bases you'll ever use (among them Binary). +not called a computer just to have a nice name. There are many +different calculators available, use them. For Unix you could use "bc" +which is short for Binary Calculator. It calculates not only in +decimal, but in all bases you'll ever want to use (among them Binary). For people on Windows: Start the calculator (start->programs->accessories->calculator) @@ -356,7 +365,7 @@ calculator and can compute in binary or hexadecimal. I hope you enjoyed the examples and their descriptions. If you do, help other people by pointing them to this document when they are asking -basic questions. They will not only get their answer but at the same +basic questions. They will not only get their answer, but at the same time learn a whole lot more. Alex van den Bogaerdt Ealex@ergens.op.het.netE diff --git a/doc/rpntutorial.pod b/doc/rpntutorial.pod index 13ee0ec..9829eb8 100644 --- a/doc/rpntutorial.pod +++ b/doc/rpntutorial.pod @@ -15,16 +15,16 @@ The LT, LE, GT, GE and EQ RPN logic operators are not as tricky as they appear. These operators act on the two values on the stack preceding them (to the left). Read these two values on the stack from left to right inserting the operator in the middle. If the -resulting statement is true, the replace the three values from the +resulting statement is true, then replace the three values from the stack with "1". If the statement if false, replace the three values with "0". -For example think about "2,1,GT". This RPN expression could be +For example, think about "2,1,GT". This RPN expression could be read as "is two greater than one?" The answer to that question is "true". So the three values should be replaced with "1". Thus the RPN expression 2,1,GT evaluates to 1. -Now also consider "2,1,LE". This RPN expression could be read as "is +Now consider "2,1,LE". This RPN expression could be read as "is two less than or equal to one?". The natural response is "no" and thus the RPN expression 2,1,LE evaluates to 0. @@ -58,14 +58,14 @@ GT, GE and EQ operators. While compound expressions can look overly complex, they can be considered elegantly simple. To quickly comprehend RPN expressions, you must know the the algorithm for evaluating RPN expressions: -iterate searches from the left to the right looking for an operator, -when it's found, apply that operator by popping the operator and some +iterate searches from the left to the right looking for an operator. +When it's found, apply that operator by popping the operator and some number of values (and by definition, not operators) off the stack. For example, the stack "1,2,3,+,+" gets "2,3,+" evaluated (as "2+3") -during the first iteration which is replaced by 5. This results in +during the first iteration and is replaced by 5. This results in the stack "1,5,+". Finally, "1,5,+" is evaluated resulting in the -answer 6. For convenience sake, it's useful to write this set of +answer 6. For convenience, it's useful to write this set of operations as: 1) 1,2,3,+,+ eval is 2,3,+ = 5 result is 1,5,+ @@ -93,23 +93,27 @@ multiplication operator: 4) 0,7000,1024,IF result is 1024 -Now let's go back to the first example of multiple logic operators +Now let's go back to the first example of multiple logic operators, but replace the value 20 with the variable "input": +=for comment +XXX wo kommt das A ploetzlich her? Hier braucht es einen Satz, dass A als +XXX placeholder zum Lesbarmachen verwendet wird (shortcut). + 1) input,10,GT,10,input,IF eval is input,10,GT result is A Read eval as "if input > 10 then true" and replace "input,10,GT" -with "A: +with "A": 2) A,10,input,IF eval is A,10,input,IF -read "if A then 10 else input". Now replace A it's verbose -description and--voila!--you have a easily readable description +read "if A then 10 else input". Now replace A with it's verbose +description againg and--voila!--you have a easily readable description of the expression: if input > 10 then 10 else input -Lastly, let's to back the first most complex example and replace +Finally, let's go back to the first most complex example and replace the value 128 with "input": 1) input,8,*,7000,GT,7000,input,8,*,IF eval input,8,* result is A @@ -155,8 +159,8 @@ by removing the redundant use of "input,8,*" like so: input,56000,GT,56000,input,IF,8,* -Use tradition notation to show these expressions are not the same. -Write an expression that's equivalent to the first expression but +Use traditional notation to show these expressions are not the same. +Write an expression that's equivalent to the first expression, but uses the LE and DIV operators. Answer 2: @@ -183,7 +187,7 @@ Answer 3: Exercise 4: -Explain why it is desirable for the RRDtool developers to implement +Explain why it was desirable for the RRDtool developers to implement RPN notation instead of traditional mathematical notation. Answer 4: diff --git a/doc/rrdcgi.pod b/doc/rrdcgi.pod index e999fea..45d24ec 100644 --- a/doc/rrdcgi.pod +++ b/doc/rrdcgi.pod @@ -14,16 +14,15 @@ ERRD:: tags. B will interpret and act according to these tags. In the end it will printout a web page including the necessary CGI headers. B parses the contents of the template in 3 steps. In each step it looks -only for a subset of tags. This allows to nest tags. +only for a subset of tags. This allows nesting of tags. -The argument parser uses the same semantics as you are used from your c shell. +The argument parser uses the same semantics as you are used from your C-shell. =over 8 - =item B<--filter> -Assume that rrdcgi is being run as a filter and not as a cgi. +Assume that rrdcgi is run as a filter and not as a cgi. =back @@ -39,12 +38,12 @@ Inserts the CGI variable of the given name. Inserts the CGI variable of the given name but quotes it, ready for use as an argument in another RRD:: tag. So even when there are spaces in the -value of the CGI variable it will still be considered as one argument. +value of the CGI variable it will still be considered to be one argument. =item RRD::CV::PATH I Inserts the CGI variable of the given name, quotes it and makes sure -the it starts neither with a '/' nor contains '..'. This is to make +it starts neither with a '/' nor contains '..'. This is to make sure that no problematic pathnames can be introduced through the CGI interface. @@ -55,18 +54,18 @@ Get the value of an environment variable. might give you the name of the remote user given you are using -some sort of access control on the directory +some sort of access control on the directory. =item RRD::GOODFOR I Specify the number of seconds this page should remain valid. This will prompt the rrdcgi to output a Last-Modified, an Expire and if the number of -seconds is I a Refresh headers. +seconds is I a Refresh header. =item RRD::INCLUDE I -Include the contents of the given file into the page returned from the cgi +Include the contents of the specified file into the page returned from the cgi. =item RRD::SETENV I I @@ -80,11 +79,11 @@ values permitted to TZ depend on your OS. =item RRD::SETVAR I I -Analog to SETENV but for local variables +Analog to SETENV but for local variables. =item RRD::GETVAR I -Analog to GETENV but for local variables +Analog to GETENV but for local variables. =item RRD::TIME::LAST I I @@ -96,8 +95,9 @@ time is I-formatted with the string specified in the second argument. This gets replaced by the current time of day. The time is I-formatted with the string specified in the argument. -Note that if you return : from your strftime format you may have to escape -them using \ if the time is to be used as an argument to a GRAPH command. +Note that if you return : (colons) from your strftime format you may +have to escape them using \ if the time is to be used as an argument +to a GRAPH command. =item RRD::TIME::STRFTIME I I I I @@ -108,12 +108,16 @@ must be supplied as either could be relative to the other. This is intended to allow pretty titles on graphs with times that are easier for non RRDtool folks to figure out than "-2weeks". -Note that if you return : from your strftime format you may have to escape -them using \ if the time is to be used as an argument to a GRAPH command. +Note that again, if you return : (colon) from your strftime format, +you may have to escape them using \ if the time is to be used as an +argument to a GRAPH command. =item RRD::GRAPH I -This tag creates the RRD graph defined in its argument and then gets +=for comment +XXX Shouldn't it be IMAGE-tag below? Fritz + +This tag creates the RRD graph defined by its argument and then is replaced by an appropriate EIMGE tag referring to the graph. The B<--lazy> option in RRD graph can be used to make sure that graphs are only regenerated when they are out of date. The arguments @@ -161,7 +165,7 @@ The example below creates a web pages with a single RRD graph. This script is slightly more elaborate, it allows you to run it from a form which sets RRD_NAME. RRD_NAME is then used to select which RRD -you want to use a source for your graph. +you want to use as source for your graph. #!/usr/local/bin/rrdcgi diff --git a/doc/rrdfetch.pod b/doc/rrdfetch.pod index 16bee22..6eb10d1 100644 --- a/doc/rrdfetch.pod +++ b/doc/rrdfetch.pod @@ -11,9 +11,9 @@ S<[B<--end>|B<-e> I]> =head1 DESCRIPTION -The B function is normally used internally by the graph function, -to get data from Bs. B will analyze the B and -will try to retrieve the data in the resolution requested. +The B function is normally used internally by the graph +function to get data from Bs. B will analyze the B +and try to retrieve the data in the resolution requested. The data fetched is printed to stdout. I<*UNKNOWN*> data is often represented by the string "NaN" depending on your OS's printf function. @@ -26,27 +26,27 @@ the name of the B you want to fetch the data from. =item I -which consolidation function should have been applied to the data you -want to fetch? (AVERAGE,MIN,MAX,LAST) +the consolidation function that is applied to the data you +want to fetch (AVERAGE,MIN,MAX,LAST) =item B<--resolution>|B<-r> I (default is the highest resolution) -what interval should the values have (seconds per value). B will try -to match your request, but it will return data even if no absolute -match is possible. B See note below. +the interval you want the values to have (seconds per +value). B will try to match your request, but it will return +data even if no absolute match is possible. B See note below. =item B<--start>|B<-s> I (default end-1day) -when should the data begin. A time in seconds since epoch (1970-01-01) -is required. Negative numbers are relative to the current time. By default +start of the time series. A time in seconds since epoch (1970-01-01) +is required. Negative numbers are relative to the current time. By default, one day worth of data will be fetched. See also AT-STYLE TIME SPECIFICATION -section for a detailed explanation on ways to specify start time. +section for a detailed explanation on ways to specify the start time. =item B<--end>|B<-e> I (default now) -when should the data end. Time in seconds since epoch. See also -AT-STYLE TIME SPECIFICATION section for a detailed explanation of how to specify -end time. +the end of the time series in seconds since epoch. See also AT-STYLE +TIME SPECIFICATION section for a detailed explanation of how to +specify the end time. =back @@ -54,7 +54,7 @@ end time. In order to get RRDtool to fetch anything other than the finest resolution RRA B the start and end time must be specified on boundaries that are -multiples of the wanted resolution. Consider the following example: +multiples of the desired resolution. Consider the following example: rrdtool create subdata.rrd -s 10 DS:ds0:GAUGE:300:0:U \ RRA:AVERAGE:0.5:30:3600 \ @@ -64,17 +64,19 @@ multiples of the wanted resolution. Consider the following example: RRA:AVERAGE:0.5:8640:600 \ RRA:MAX:0.5:8640:600 -This RRD collects data every 10 seconds and stores its averages over 5 minutes, -15 minutes, 1 hour and 1 day as well as the maxima for 1 hour and 1 day. +This RRD collects data every 10 seconds and stores its averages over 5 +minutes, 15 minutes, 1 hour, and 1 day, as well as the maxima for 1 hour +and 1 day. -Consider now that you want too fetch the 15 minute average data for last hour. -So you might try +Consider now that you want to fetch the 15 minute average data for the +last hour. You might try rrdtool fetch subdata.rrd AVERAGE -r 900 -s -1h -However, this will almost always result in a time series that is B in the 15 -minute RRA. Therefore the highest resolution RRA, i.e. 5 minute averages, will -be chosen which, in this case, is not what you want. +However, this will almost always result in a time series that is +B in the 15 minute RRA. Therefore, the highest resolution RRA, +i.e. 5 minute averages, will be chosen which in this case is not +what you want. Hence, make sure that @@ -86,16 +88,17 @@ both start and end time are a multiple of 900 =item 2. -both start and end time are within the wanted RRA +both start and end time are within the desired RRA =back -So, if time now is called "t", +So, if time now is called "t", do - do end time == int(t/900)*900, - start time == end time -1hour, resolution == 900. + end time == int(t/900)*900, + start time == end time - 1hour, + resolution == 900. -In e.g. bash this could look as: +Using the bash shell, this could look be: TIME=$(date +%s) RRDRES=900 @@ -112,87 +115,91 @@ Or in Perl: =head2 AT-STYLE TIME SPECIFICATION Apart from the traditional I, RRDtool does also -understand at-style time specification. The specification is called -"at-style" after Unix command at(1) that has moderately complex ways -to specify time to run your job at. The at-style specification -consists of two parts: B