1dc(1)                       General Commands Manual                      dc(1)
2
3
4

NAME

6       dc - an arbitrary precision calculator
7

SYNOPSIS

9       dc [-V] [--version] [-h] [--help]
10          [-e scriptexpression] [--expression=scriptexpression]
11          [-f scriptfile] [--file=scriptfile]
12          [file ...]
13

DESCRIPTION

15       dc  is a reverse-polish desk calculator which supports unlimited preci‐
16       sion arithmetic.  It also allows you to define and call  macros.   Nor‐
17       mally  dc  reads  from the standard input; if any command arguments are
18       given to it, they are filenames, and dc reads and executes the contents
19       of  the files before reading from standard input.  All normal output is
20       to standard output; all error output is to standard error.
21
22       A reverse-polish calculator stores numbers on a stack.  Entering a num‐
23       ber  pushes  it  on the stack.  Arithmetic operations pop arguments off
24       the stack and push the results.
25
26       To enter a number in dc, type the digits (using upper  case  letters  A
27       through  F as "digits" when working with input bases greater than ten),
28       with an optional decimal point.  Exponential notation is not supported.
29       To  enter a negative number, begin the number with ``_''.  ``-'' cannot
30       be used for this, as it is a binary operator for  subtraction  instead.
31       To  enter  two numbers in succession, separate them with spaces or new‐
32       lines.  These have no meaning as commands.
33

OPTIONS

35       dc may be invoked with the following command-line options:
36
37       -V
38
39       --version
40              Print out the version of dc that is being run  and  a  copyright
41              notice, then exit.
42
43       -h
44
45       --help Print  a  usage  message  briefly summarizing these command-line
46              options and the bug-reporting address, then exit.
47
48       -e script
49
50       --expression=script
51              Add the commands in script to the set  of  commands  to  be  run
52              while processing the input.
53
54       -f script-file
55
56       --file=script-file
57              Add the commands contained in the file script-file to the set of
58              commands to be run while processing the input.
59
60       If any command-line parameters remain after processing the above, these
61       parameters are interpreted as the names of input files to be processed.
62       A file name of - refers to the standard  input  stream.   The  standard
63       input will processed if no script files or expressions are specified.
64

Printing Commands

66       p      Prints  the  value on the top of the stack, without altering the
67              stack.  A newline is printed after the value.
68
69       n      Prints the value on the top of the stack, popping  it  off,  and
70              does not print a newline after.
71
72       P      Pops  off  the value on top of the stack.  If it it a string, it
73              is simply printed without a trailing newline.  Otherwise it is a
74              number, and the integer portion of its absolute value is printed
75              out as  a  "base  (UCHAR_MAX+1)"  byte  stream.   Assuming  that
76              (UCHAR_MAX+1)  is  256  (as  it  is  on most machines with 8-bit
77              bytes),      the      sequence      KSK0k1/_1Ss      [ls*]Sxd0>x
78              [256~Ssd0<x]dsxxsx[q]Sq[Lsd0>qaPlxx]  dsxxsx0sqLqsxLxLK+k  could
79              also accomplish this function.  (Much of the complexity  of  the
80              above  native-dc  code  is due to the ~ computing the characters
81              backwards, and the desire to ensure that all registers  wind  up
82              back in their original states.)
83
84       f      Prints  the  entire  contents of the stack without altering any‐
85              thing.  This is a good command to use if you are lost or want to
86              figure out what the effect of some command has been.
87

Arithmetic

89       +      Pops two values off the stack, adds them, and pushes the result.
90              The precision of the result is determined only by the values  of
91              the arguments, and is enough to be exact.
92
93       -      Pops  two values, subtracts the first one popped from the second
94              one popped, and pushes the result.
95
96       *      Pops two values, multiplies them, and pushes  the  result.   The
97              number  of  fraction digits in the result depends on the current
98              precision value and the number of fraction  digits  in  the  two
99              arguments.
100
101       /      Pops  two  values,  divides the second one popped from the first
102              one popped, and pushes the result.  The number of fraction  dig‐
103              its is specified by the precision value.
104
105       %      Pops two values, computes the remainder of the division that the
106              / command would do, and pushes that.  The value computed is  the
107              same as that computed by the sequence Sd dld/ Ld*- .
108
109       ~      Pops  two  values,  divides the second one popped from the first
110              one popped.  The quotient is pushed first, and the remainder  is
111              pushed next.  The number of fraction digits used in the division
112              is specified by the precision value.  (The sequence  SdSn  lnld/
113              LnLd% could also accomplish this function, with slightly differ‐
114              ent error checking.)
115
116       ^      Pops two values and exponentiates, using the first value  popped
117              as the exponent and the second popped as the base.  The fraction
118              part of the exponent is ignored.  The precision value  specifies
119              the number of fraction digits in the result.
120
121       |      Pops  three  values  and computes a modular exponentiation.  The
122              first value popped is used as the reduction modulus; this  value
123              must be a non-zero number, and should be an integer.  The second
124              popped is used as the exponent; this value must be  a  non-nega‐
125              tive  number,  and  any fractional part of this exponent will be
126              ignored.  The third value popped is the base which gets exponen‐
127              tiated,  which should be an integer.  For small integers this is
128              like the sequence Sm^Lm%, but, unlike ^, this command will  work
129              with arbitrarily large exponents.
130
131       v      Pops  one value, computes its square root, and pushes that.  The
132              maximum of the precision value and the precision of the argument
133              is  used  to  determine  the  number  of  fraction digits in the
134              result.
135
136       Most arithmetic operations are affected  by  the  ``precision  value'',
137       which  you  can set with the k command.  The default precision value is
138       zero, which means that all arithmetic except for addition and  subtrac‐
139       tion produces integer results.
140

Stack Control

142       c      Clears the stack, rendering it empty.
143
144       d      Duplicates  the  value  on the top of the stack, pushing another
145              copy of it.  Thus, ``4d*p'' computes 4 squared and prints it.
146
147       r      Reverses the order of (swaps) the top two values on  the  stack.
148              (This can also be accomplished with the sequence SaSbLaLb.)
149
150       R      Pops  the  top-of-stack as an integer n.  Cyclically rotates the
151              top n items on the updated stack.  If n is  positive,  then  the
152              rotation direction will make the topmost element the second-from
153              top; if n is negative, then the rotation will make  the  topmost
154              element  the  n-th  element from the top.  If the stack depth is
155              less than n, then the entire stack is rotated (in the  appropri‐
156              ate direction), without any error being reported.
157

Registers

159       dc provides at least 256 memory registers, each named by a single char‐
160       acter.  You can store a number or a string in a register  and  retrieve
161       it later.
162
163       sr     Pop  the value off the top of the stack and store it into regis‐
164              ter r.
165
166       lr     Copy the value in register r and push it onto  the  stack.   The
167              value  0  is  retrieved  if the register is uninitialized.  This
168              does not alter the contents of r.
169
170       Each register also contains its own stack.  The current register  value
171       is the top of the register's stack.
172
173       Sr     Pop  the  value off the top of the (main) stack and push it onto
174              the stack of register r.  The previous  value  of  the  register
175              becomes inaccessible.
176
177       Lr     Pop the value off the top of register r's stack and push it onto
178              the main stack.  The previous value in register  r's  stack,  if
179              any, is now accessible via the lr command.
180

Parameters

182       dc  has three parameters that control its operation: the precision, the
183       input radix, and the output radix.  The precision specifies the  number
184       of fraction digits to keep in the result of most arithmetic operations.
185       The input radix controls the interpretation of numbers  typed  in;  all
186       numbers typed in use this radix.  The output radix is used for printing
187       numbers.
188
189       The input and output radices are separate parameters; you can make them
190       unequal,  which  can  be  useful or confusing.  The input radix must be
191       between 2 and 16 inclusive.  The output radix must be at least 2.   The
192       precision must be zero or greater.  The precision is always measured in
193       decimal digits, regardless of the current input or output radix.
194
195       i      Pops the value off the top of the stack and uses it to  set  the
196              input radix.
197
198       o      Pops  the  value off the top of the stack and uses it to set the
199              output radix.
200
201       k      Pops the value off the top of the stack and uses it to  set  the
202              precision.
203
204       I      Pushes the current input radix on the stack.
205
206       O      Pushes the current output radix on the stack.
207
208       K      Pushes the current precision on the stack.
209

Strings

211       dc  has  a limited ability to operate on strings as well as on numbers;
212       the only things you can do with strings are print them and execute them
213       as macros (which means that the contents of the string are processed as
214       dc commands).  All registers and the stack can  hold  strings,  and  dc
215       always  knows  whether  any given object is a string or a number.  Some
216       commands such as arithmetic operations demand numbers as arguments  and
217       print errors if given strings.  Other commands can accept either a num‐
218       ber or a string; for example, the  p  command  can  accept  either  and
219       prints the object according to its type.
220
221       [characters]
222              Makes a string containing characters (contained between balanced
223              [ and ] characters), and pushes it on the stack.   For  example,
224              [foo]P prints the characters foo (with no newline).
225
226       a      The  top-of-stack  is popped.  If it was a number, then the low-
227              order byte of this number is converted into a string and  pushed
228              onto  the  stack.   Otherwise the top-of-stack was a string, and
229              the first character of that string is pushed back.
230
231       x      Pops a value off the stack and executes it as a macro.  Normally
232              it  should  be  a string; if it is a number, it is simply pushed
233              back onto the stack.  For example, [1p]x executes the  macro  1p
234              which pushes 1 on the stack and prints 1 on a separate line.
235
236       Macros  are  most  often  stored in registers; [1p]sa stores a macro to
237       print 1 into register a, and lax invokes this macro.
238
239       >r     Pops two values off the stack and compares  them  assuming  they
240              are  numbers, executing the contents of register r as a macro if
241              the original top-of-stack is greater.  Thus, 1 2>a  will  invoke
242              register a's contents and 2 1>a will not.
243
244       !>r    Similar  but  invokes  the macro if the original top-of-stack is
245              not greater than (less than or equal to) what was the second-to-
246              top.
247
248       <r     Similar  but  invokes  the macro if the original top-of-stack is
249              less.
250
251       !<r    Similar but invokes the macro if the  original  top-of-stack  is
252              not less than (greater than or equal to) what was the second-to-
253              top.
254
255       =r     Similar but invokes the macro if  the  two  numbers  popped  are
256              equal.
257
258       !=r    Similar  but invokes the macro if the two numbers popped are not
259              equal.
260
261       ?      Reads a line from the terminal and executes  it.   This  command
262              allows a macro to request input from the user.
263
264       q      exits from a macro and also from the macro which invoked it.  If
265              called from the top level, or from  a  macro  which  was  called
266              directly  from  the  top  level,  the q command will cause dc to
267              exit.
268
269       Q      Pops a value off the stack and uses it as a count of  levels  of
270              macro execution to be exited.  Thus, 3Q exits three levels.  The
271              Q command will never cause dc to exit.
272

Status Inquiry

274       Z      Pops a value off the stack, calculates  the  number  of  decimal
275              digits  it  has (or number of characters, if it is a string) and
276              pushes that number.  The digit  count  for  a  number  does  not
277              include  any leading zeros, even if those appear to the right of
278              the radix point.
279
280       X      Pops a value off the stack, calculates the  number  of  fraction
281              digits  it has, and pushes that number.  For a string, the value
282              pushed is 0.
283
284       z      Pushes the current stack depth: the number  of  objects  on  the
285              stack before the execution of the z command.
286

Miscellaneous

288       !      Will  run  the  rest of the line as a system command.  Note that
289              parsing of the !<, !=, and !> commands take  precedence,  so  if
290              you want to run a command starting with <, =, or > you will need
291              to add a space after the !.
292
293       #      Will interpret the rest of the line as a comment.
294
295       :r     Will pop the top two values off of the stack.  The  old  second-
296              to-top  value  will be stored in the array r, indexed by the old
297              top-of-stack value.
298
299       ;r     Pops the top-of-stack and uses it as an index into the array  r.
300              The selected value is then pushed onto the stack.
301
302       Note that each stacked instance of a register has its own array associ‐
303       ated with it.  Thus 1 0:a 0Sa 2 0:a La 0;ap will print 1, because the 2
304       was stored in an instance of 0:a that was later popped.
305

BUGS

307       Email bug reports to bug-dc@gnu.org.
308
309
310
311GNU Project                       2008-05-22                             dc(1)
Impressum