diff options
Diffstat (limited to 'upstream/debian-unstable/man1/dc.1')
| -rw-r--r-- | upstream/debian-unstable/man1/dc.1 | 528 |
1 files changed, 528 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/dc.1 b/upstream/debian-unstable/man1/dc.1 new file mode 100644 index 00000000..02c4abdd --- /dev/null +++ b/upstream/debian-unstable/man1/dc.1 @@ -0,0 +1,528 @@ +.\" +.\" dc.1 - the *roff document processor source for the dc manual +.\" +.\" This file is part of GNU dc. +.\" Copyright (C) 1994, 1997, 1998, 2000, 2001, 2005, 2006, 2008, 2013, 2016 +.\" Free Software Foundation, Inc. +.\" +.\" Permission is granted to copy, distribute and/or modify this document +.\" under the terms of the GNU Free Documentation License, Version 1.2 or +.\" any later version published by the Free Software Foundation; with no +.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +.\" Texts. +.\" +.TH dc 1 "2008-05-22" "GNU Project" +.ds dc \fIdc\fP +.ds Dc \fIdc\fP +.SH NAME +dc \- an arbitrary precision calculator +.SH SYNOPSIS +dc [\-V] [\-\-version] [\-h] [\-\-help] + [\-e scriptexpression] [\-\-expression=scriptexpression] + [\-f scriptfile] [\-\-file=scriptfile] + [file ...] +.SH DESCRIPTION +.PP +\*(Dc is a reverse-polish desk calculator which supports +unlimited precision arithmetic. +It also allows you to define and call macros. +Normally \*(dc reads from the standard input; +if any command arguments are given to it, they are filenames, +and \*(dc reads and executes the contents of the files before reading +from standard input. +All normal output is to standard output; +all error output is to standard error. +.PP +A reverse-polish calculator stores numbers on a stack. +Entering a number pushes it on the stack. +Arithmetic operations pop arguments off the stack and push the results. +.PP +To enter a number in +.IR dc , +type the digits +(using upper case letters +.I A +through +.I F +as "digits" when working +with input bases greater than ten), +with an optional decimal point. +Exponential notation is not supported. +To enter a negative number, +begin the number with ``_''. +``-'' cannot be used for this, +as it is a binary operator for subtraction instead. +To enter two numbers in succession, +separate them with spaces or newlines. +These have no meaning as commands. +.SH OPTIONS +\*(Dc may be invoked with the following command-line options: +.TP +.B -V +.TP +.B --version +Print out the version of \*(dc that is being run and a copyright notice, +then exit. +.TP +.B -h +.TP +.B --help +Print a usage message briefly summarizing these command-line options +and the bug-reporting address, +then exit. +.TP +.B -e \fIscript\fP +.TP +.BI --expression= script +Add the commands in +.I script +to the set of commands to be run while processing the input. +.TP +.B -f \fIscript-file\fP +.TP +.BI --file= script-file +Add the commands contained in the file +.I script-file +to the set of commands to be run while processing the input. +.PP +If any command-line parameters remain after processing the above, +these parameters are interpreted as the names of input files to +be processed. +A file name of +.B - +refers to the standard input stream. +The standard input will processed if no script files or +expressions are specified. +.PD +.SH +Printing Commands +.TP +.B p +Prints the value on the top of the stack, +without altering the stack. +A newline is printed after the value. +.TP +.B n +Prints the value on the top of the stack, popping it off, +and does not print a newline after. +.TP +.B P +Pops off the value on top of the stack. +If it it a string, it is simply printed without a trailing newline. +Otherwise it is a number, and the integer portion of its absolute +value is printed out as a "base (UCHAR_MAX+1)" byte stream. +Assuming that (UCHAR_MAX+1) is 256 +(as it is on most machines with 8-bit bytes), +the sequence \fBKSK0k1/_1Ss [ls*]Sxd0>x +[256~Ssd0<x]dsxxsx[q]Sq[Lsd0>qaPlxx] +dsxxsx0sqLqsxLxLK+k\fP +could also accomplish this function. +(Much of the complexity of the above native-dc code is due +to the ~ computing the characters backwards, +and the desire to ensure that all registers wind up back +in their original states.) +.TP +.B f +Prints the entire contents of the stack +.ig +and the contents of all of the registers, +.. +without altering anything. +This is a good command to use if you are lost or want +to figure out what the effect of some command has been. +.PD +.SH +Arithmetic +.TP +.B + +Pops two values off the stack, adds them, +and pushes the result. +The precision of the result is determined only +by the values of the arguments, +and is enough to be exact. +.TP +.B - +Pops two values, +subtracts the first one popped from the second one popped, +and pushes the result. +.TP +.B * +Pops two values, multiplies them, and pushes the result. +The number of fraction digits in the result depends on +the current precision value and the number of fraction +digits in the two arguments. +.TP +.B / +Pops two values, +divides the second one popped from the first one popped, +and pushes the result. +The number of fraction digits is specified by the precision value. +.TP +.B % +Pops two values, +computes the remainder of the division that the +.B / +command would do, +and pushes that. +The value computed is the same as that computed by +the sequence \fBSd dld/ Ld*-\fP . +.TP +.B ~ +Pops two values, +divides the second one popped from the first one popped. +The quotient is pushed first, and the remainder is pushed next. +The number of fraction digits used in the division +is specified by the precision value. +(The sequence \fBSdSn lnld/ LnLd%\fP could also accomplish +this function, with slightly different error checking.) +.TP +.B ^ +Pops two values and exponentiates, +using the first value popped as the exponent +and the second popped as the base. +The fraction part of the exponent is ignored. +The precision value specifies the number of fraction +digits in the result. +.TP +.B | +Pops three values and computes a modular exponentiation. +The first value popped is used as the reduction modulus; +this value must be a non-zero number, +and should be an integer. +The second popped is used as the exponent; +this value must be a non-negative number, +and any fractional part of this exponent will be ignored. +The third value popped is the base which gets exponentiated, +which should be an integer. +For small integers this is like the sequence \fBSm^Lm%\fP, +but, unlike \fB^\fP, this command will work with arbitrarily large exponents. +.TP +.B v +Pops one value, +computes its square root, +and pushes that. +The maximum of the precision value and the precision of the argument +is used to determine the number of fraction digits in the result. +.PP +Most arithmetic operations are affected by the ``precision value'', +which you can set with the +.B k +command. +The default precision value is zero, +which means that all arithmetic except for +addition and subtraction produces integer results. +.SH +Stack Control +.TP +.B c +Clears the stack, rendering it empty. +.TP +.B d +Duplicates the value on the top of the stack, +pushing another copy of it. +Thus, ``4d*p'' computes 4 squared and prints it. +.TP +.B r +Reverses the order of (swaps) the top two values on the stack. +(This can also be accomplished with the sequence \fBSaSbLaLb\fP.) +.TP +.B R +Pops the top-of-stack as an integer +.IR n . +Cyclically rotates the top +.I n +items on the updated stack. +If +.I n +is positive, then the rotation direction will make the topmost +element the second-from top; +if +.I n +is negative, then the rotation will make the topmost element the +.IR n -th +element from the top. +If the stack depth is less than +.IR n , +then the entire stack is rotated (in the appropriate direction), +without any error being reported. +.SH +Registers +.PP +\*(Dc provides at least 256 memory registers, +each named by a single character. +You can store a number or a string in a register and retrieve it later. +.TP +.BI s r +Pop the value off the top of the stack and store +it into register +.IR r . +.TP +.BI l r +Copy the value in register +.I r +and push it onto the stack. +The value 0 is retrieved if the register is uninitialized. +This does not alter the contents of +.IR r . +.PP +Each register also contains its own stack. +The current register value is the top of the register's stack. +.TP +.BI S r +Pop the value off the top of the (main) stack and +push it onto the stack of register +.IR r . +The previous value of the register becomes inaccessible. +.TP +.BI L r +Pop the value off the top of register +.IR r 's +stack and push it onto the main stack. +The previous value +in register +.IR r 's +stack, if any, +is now accessible via the +.BI l r +command. +.ig +.PP +The +.B f +command prints a list of all registers that have contents stored in them, +together with their contents. +Only the current contents of each register +(the top of its stack) +is printed. +.. +.SH +Parameters +.PP +\*(Dc has three parameters that control its operation: +the precision, the input radix, and the output radix. +The precision specifies the number +of fraction digits to keep in the result of most arithmetic operations. +The input radix controls the interpretation of numbers typed in; +all numbers typed in use this radix. +The output radix is used for printing numbers. +.PP +The input and output radices are separate parameters; +you can make them unequal, +which can be useful or confusing. +The input radix must be between 2 and 16 inclusive. +The output radix must be at least 2. +The precision must be zero or greater. +The precision is always measured in decimal digits, +regardless of the current input or output radix. +.TP +.B i +Pops the value off the top of the stack +and uses it to set the input radix. +.TP +.B o +Pops the value off the top of the stack +and uses it to set the output radix. +.TP +.B k +Pops the value off the top of the stack +and uses it to set the precision. +.TP +.B I +Pushes the current input radix on the stack. +.TP +.B O +Pushes the current output radix on the stack. +.TP +.B K +Pushes the current precision on the stack. +.SH +Strings +.PP +\*(Dc has a limited ability to operate on strings +as well as on numbers; +the only things you can do with strings are +print them and execute them as macros +(which means that the contents of the string are processed as +\*(dc commands). +All registers and the stack can hold strings, +and \*(dc always knows whether any given object is a string or a number. +Some commands such as arithmetic operations demand numbers +as arguments and print errors if given strings. +Other commands can accept either a number or a string; +for example, the +.B p +command can accept either and prints the object +according to its type. +.TP +.BI [ characters ] +Makes a string containing +.I characters +(contained between balanced +.B [ +and +.B ] +characters), +and pushes it on the stack. +For example, +.B [foo]P +prints the characters +.B foo +(with no newline). +.TP +.B a +The top-of-stack is popped. +If it was a number, then the low-order byte of this number +is converted into a string and pushed onto the stack. +Otherwise the top-of-stack was a string, +and the first character of that string is pushed back. +.TP +.B x +Pops a value off the stack and executes it as a macro. +Normally it should be a string; +if it is a number, +it is simply pushed back onto the stack. +For example, +.B [1p]x +executes the macro +.B 1p +which pushes +.B 1 +on the stack and prints +.B 1 +on a separate line. +.PP +Macros are most often stored in registers; +.B [1p]sa +stores a macro to print +.B 1 +into register +.BR a , +and +.B lax +invokes this macro. +.TP +.BI > r +Pops two values off the stack and compares them +assuming they are numbers, +executing the contents of register +.I r +as a macro if the original top-of-stack +is greater. +Thus, +.B 1 2>a +will invoke register +.BR a 's +contents and +.B 2 1>a +will not. +.TP +.BI !> r +Similar but invokes the macro if the original top-of-stack is +not greater than (less than or equal to) what was the second-to-top. +.TP +.BI < r +Similar but invokes the macro if the original top-of-stack is less. +.TP +.BI !< r +Similar but invokes the macro if the original top-of-stack is +not less than (greater than or equal to) what was the second-to-top. +.TP +.BI = r +Similar but invokes the macro if the two numbers popped are equal. +.TP +.BI != r +Similar but invokes the macro if the two numbers popped are not equal. +.ig +This can also be validly used to compare two strings for equality. +.. +.TP +.B ? +Reads a line from the terminal and executes it. +This command allows a macro to request input from the user. +.TP +.B q +exits from a macro and also from the macro which invoked it. +If called from the top level, +or from a macro which was called directly from the top level, +the +.B q +command will cause \*(dc to exit. +.TP +.B Q +Pops a value off the stack and uses it as a count +of levels of macro execution to be exited. +Thus, +.B 3Q +exits three levels. +The +.B Q +command will never cause \*(dc to exit. +.SH +Status Inquiry +.TP +.B Z +Pops a value off the stack, +calculates the number of decimal digits it has +(or number of characters, if it is a string) +and pushes that number. +The digit count for a number does +.I not +include any leading zeros, +even if those appear to the right of the radix point. +.TP +.B X +Pops a value off the stack, +calculates the number of fraction digits it has, +and pushes that number. +For a string, +the value pushed is +.\" -1. +0. +.TP +.B z +Pushes the current stack depth: +the number of objects on the stack before the execution of the +.B z +command. +.SH +Miscellaneous +.TP +.B ! +Will run the rest of the line as a system command. +Note that parsing of the !<, !=, and !> commands take precedence, +so if you want to run a command starting with <, =, or > you will +need to add a space after the !. +.TP +.B # +Will interpret the rest of the line as a comment. +.TP +.BI : r +Will pop the top two values off of the stack. +The old second-to-top value will be stored in the array +.IR r , +indexed by the old top-of-stack value. +.TP +.BI ; r +Pops the top-of-stack and uses it as an index into +the array +.IR r . +The selected value is then pushed onto the stack. +.P +Note that each stacked instance of a register has its own +array associated with it. +Thus \fB1 0:a 0Sa 2 0:a La 0;ap\fP will print 1, +because the 2 was stored in an instance of 0:a that +was later popped. +.SH +FILES +.TP 15 +~/.dcrc +The commands in this file will be executed when +.I dc +is first run. +.PP +.SH +BUGS +.PP +Email bug reports to +.BR bug-dc@gnu.org . |