DC(1) -- 1997-03-25 -- GNU Project

NAME
	dc - an arbitrary precision calculator

SYNOPSIS
	dc [-V] [--version] [-h] [--help]
	   [-e scriptexpression] [--expression=scriptexpression]
	   [-f scriptfile] [--file=scriptfile]
	   [file ...]

DESCRIPTION

	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.

	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.

	To enter  a number in dc,  type the digits  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.

OPTIONS
	Dc may be invoked with the following command-line options:

	-V

	--version
		Print out  the version  of dc that  is being run  and a
		copyright notice, then exit.

	-h

	--help
		Print  a   usage  message  briefly   summarizing  these
		command-line  options  and  the bug-reporting  address,
		then exit.

	-e script

	--expression=script
		Add the commands in script to the set of commands to be
		run while processing the input.

	-f script-file

	--file=script-file
		Add the  commands contained in the  file script-file to
		the  set of  commands to  be run  while  processing the
		input.

	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 - refers to the
	standard input stream.  The standard input will processed if
	no file names are specified.

Printing Commands

	p    Prints  the value  on  the top  of  the stack,  without
		altering  the stack.   A newline  is printed  after the
		value.

	n    Prints the  value on the  top of the stack,  popping it
		off, and does not print a newline after.

	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  KSK  0k1/  [_1*]sx  d0>x
		[256~aPd0<x]dsxx  sxLKk   could  also  accomplish  this
		function, except for  the side-effect of clobbering the
		x register.

	f    Prints  the  entire   contents  of  the  stack  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.

Arithmetic

	+    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.

	-    Pops two  values, subtracts  the first one  popped from
		the second one popped, and pushes the result.

	*    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.

	/    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.

	%    Pops two values, computes the remainder of the division
		that  the /  command would  do, and  pushes  that.  The
		value  computed is  the same  as that  computed  by the
		sequence Sd dld/ Ld*- .

	~    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 SdSn lnld/ LnLd% could
		also accomplish this  function, with slightly different
		error checking.)

	^    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.

	|    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 Sm^Lm%, but,
		unlike ^, this command will work with arbitrarily large
		exponents.

	v    Pops one  value, computes  its square root,  and pushes
		that.   The  precision value  specifies  the number  of
		fraction digits in the result.

	Most arithmetic  operations are affected  by the ``precision
	value'', which you can set  with the k command.  The default
	precision  value is  zero, which  means that  all arithmetic
	except  for   addition  and  subtraction   produces  integer
	results.

Stack Control

	c    Clears the stack, rendering it empty.

	d    Duplicates the  value on the top of  the stack, pushing
		another copy of it.   Thus, ``4d*p'' computes 4 squared
		and prints it.

	r    Reverses the order of (swaps) the top two values on the
		stack.

Registers

	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.

	sr   Pop the  value off  the top of  the stack and  store it
		into register r.

	lr   Copy  the value  in register  r  and push  it onto  the
		stack.  This does not alter the contents of r.

	Each  register also  contains  its own  stack.  The  current
	register value is the top of the register's stack.

	Sr   Pop the value off the  top of the (main) stack and push
		it onto the stack of register r.  The previous value of
		the register becomes inaccessible.

	Lr   Pop the  value off  the top of  register r's  stack and
		push  it onto the  main stack.   The previous  value in
		register r's  stack, if any, is now  accessible via the
		lr command.

Parameters

	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.

	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.

	i    Pops the value off the top  of the stack and uses it to
		set the input radix.

	o    Pops the value off the top  of the stack and uses it to
		set the output radix.

	k    Pops the value off the top  of the stack and uses it to
		set the precision.

	I    Pushes the current input radix on the stack.

	O    Pushes the current output radix on the stack.

	K    Pushes the current precision on the stack.

Strings

	Dc can 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 p command  can accept
	either and prints the object according to its type.

	[characters]
		Makes a string containing characters (contained between
		balanced  [ and  ] characters),  and pushes  it  on the
		stack.  For  example, [foo]P prints  the characters foo
		(with no newline).

	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.

	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,
		[1p]x executes the macro 1p which pushes 1 on the stack
		and prints 1 on a separate line.

	Macros are  most often stored in registers;  [1p]sa stores a
	macro  to print  1 into  register  a, and  lax invokes  this
	macro.

	>r   Pops  two  values  off  the  stack  and  compares  them
		assuming  they are numbers,  executing the  contents of
		register r  as a macro if the  original top-of-stack is
		greater.  Thus, 1 2>a will invoke register a's contents
		and 2 1>a will not.

	!>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.

	<r   Similar   but  invokes  the   macro  if   the  original
		top-of-stack is less.

	!<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.

	=r   Similar but invokes the macro if the two numbers popped
		are equal.

	!=r  Similar but invokes the macro if the two numbers popped
		are not equal.

	?    Reads a  line from the terminal and  executes it.  This
		command allows a macro to request input from the user.

	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
		q command will cause dc to exit.

	Q    Pops a  value off the stack  and uses it as  a count of
		levels of macro execution to be exited.  Thus, 3Q exits
		three  levels.  The Q  command will  never cause  dc to
		exit.

Status Inquiry

	Z    Pops a  value off the  stack, calculates the  number of
		digits  it has  (or number  of characters,  if it  is a
		string) and pushes that number.

	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 0.

	z    Pushes the  current stack depth: the  number of objects
		on the stack before the execution of the z command.

Miscellaneous

	!    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
		!.

	#    Will interpret the rest of the line as a comment.

	:r   Will pop the top two  values off of the stack.  The old
		second-to-top  value will  be  stored in  the array  r,
		indexed by the old top-of-stack value.

	;r   Pops the top-of-stack and uses  it as an index into the
		array r.   The selected value  is then pushed  onto the
		stack.

	Note that  each stacked instance  of a register has  its own
	array associated with it.  Thus 1 0:a 0Sa 2 0:a La 0;ap will
	print 1, because the 2 was stored in an instance of 0:a that
	was later popped.

BUGS

	Email bug reports to bug-dc@gnu.org.
