.\"

.\" Copyright (C) 1999-2007,2014,2018,2021 Landon Curt Noll

.\"

.\" Calc is open software; you can redistribute it and/or modify it under

.\" the terms of the version 2.1 of the GNU Lesser General Public License

.\" as published by the Free Software Foundation.

.\"

.\" Calc is distributed in the hope that it will be useful, but WITHOUT

.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY

.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General

.\" Public License for more details.

.\"

.\" A copy of version 2.1 of the GNU Lesser General Public License is

.\" distributed with calc under the filename COPYING-LGPL. You should have

.\" received a copy with calc; if not, write to Free Software Foundation, Inc.

.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

.\"

.\" Under source code control: 1991/07/23 05:48:26

.\" File existed as early as: 1991

.\"

.\" chongo <was here> /\oo/\ http://www.isthe.com/chongo/

.\" Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/

.\"

.\" calculator by David I. Bell

.\" man page by Landon Noll

.\"

.TH calc 1 "^..^" "Share and enjoy! :-)"

.SH NAME

calc \- arbitrary precision calculator

.SH SYNOPSIS

\fIcalc\fP

.RB [ \-c ]

.RB [ \-C ]

.RB [ \-d ]

.br

.in +5n

.RB [ -D\ \&calc_debug[:resource_debug[:user_debug]] ]

.br

.RB [ \-e ]

.RB [ \-f\ \&filename ]

.RB [ \-h ]

.RB [ \-i ]

.RB [ \-m\ \&mode ]

.RB [ \-O ]

.br

.RB [ \-p ]

.RB [ \-q ]

.RB [ \-s ]

.RB [ \-u ]

.RB [ \-v ]

.RB [ [\-\-]\ calc_cmd\ \&.\|.\|. ]

.in -5n

.sp

\fI#!${BINDIR}/calc\fP\ [optional_other_flags\ \&...] \fB\-f\fP

.PP

.SH DESCRIPTION

.PP

.TP

.B \-c

Continue reading command lines even after a scan/parse

error has caused the abandonment of a line.

Note that this option only deals with scanning and

parsing of the calc language.

It does not deal with execution or run-time errors.

.sp 1

For example:

.sp 1

.in +5n

.nf

calc read many_errors.cal

.fi

.in -5n

.sp 1

will cause

.B calc

to abort on the first syntax error, whereas:

.sp 1

.in +5n

.nf

calc -c read many_errors.cal

.fi

.in -5n

.sp 1

will

cause

.B calc

to try to process each line being read

despite the scan/parse errors that it encounters.

.sp 1

By default, calc startup resource files are silently

ignored if not found.

This flag will report missing

startup resource files unless

.B \-d

is also given.

.TP

.B \-C

Permit the execution of custom builtin functions.

Without

this flag, calling the custom() builtin function will

simply generate an error.

.sp 1

Use of this flag may cause

.B calc

to execute functions

that are non-standard and that are not portable. Custom builtin

functions are disabled by default for this reason.

.TP

.B \-d

Disable the printing of the opening title. The printing

of resource file debug and informational messages is also disabled

as if \fBconfig("resource_debug", 0)\fP had been executed.

.sp 1

For example:

.sp 1

.in +5n

calc "read qtime; qtime(2)"

.in -5n

.sp 1

will output something like:

.sp 1

.in +5n

.nf

qtime(utc_hr_offset) defined

It's nearly ten past six.

.fi

.in -5n

.sp 1

whereas:

.sp 1

.in +5n

.nf

calc -d "read qtime; qtime(2)"

.fi

.in -5n

.sp 1

will just print:

.sp 1

.in +5n

.nf

It's nearly ten past six.

.fi

.in -5n

.sp 1

This flag disables the reporting of missing calc

startup resource files.

.sp 1

This flag also disables the printing the leading tilde. For example:

.sp 1

.in +5n

.nf

calc 2/3

.fi

.in -5n

.sp 1

will print:

.sp 1

.in +5n

.nf

~0.66666666666666666667

.fi

.in -5n

.sp 1

.sp 1

whereas:

.sp 1

.in +5n

.nf

calc -d 2/3

.fi

.in -5n

.sp 1

will just print:

.sp 1

.in +5n

.nf

0.66666666666666666667

.fi

.in -5n

.sp 1

.TP

.BR -D " calc_debug[:resource_debug[:user_debug]]"

Force the initial value of config("calc_debug"),

config("resource_debug") and config("user_debug").

.sp 1

The : separated strings are interpreted as signed 32 bit integers.

After an optional leading sign a leading zero indicates octal

conversion, and a leading ``0x'' or ``0X'' hexadecimal

conversion. Otherwise, decimal conversion is assumed.

.sp 1

By default,

.I calc_debug

is 0,

.I resource_debug

is 3 and

.I user_debug

is 0.

.sp 1

For more information use the following

.B calc

command:

.sp 1

.in +5n

.nf

help config

.fi

.in -5n

.TP

.B \-e

Ignore any environment variables on startup.

The getenv() builtin will still return values, however.

.TP

.BR \-f " filename"

This flag is normally only with calc shell scripts.

.sp 1

This flag is required when using calc in

.BR "shell script mode" .

It must be at the end of the initial

.B #!

line of the script, as in:

.sp 1

.in +5n

.nf

\fI#!${BINDIR}/calc\fP\ [optional_other_flags\ \&...] \fB\-f\fP

.fi

.in -5n

.sp 1

the rest of the file will be processed in

.BR "shell script mode" .

.sp 1

A common flag to use, prior to the

.B \-f

on the #! line is the

.B \-q

flag.

For example:

.sp 1

.in +5n

.nf

\fI#!${BINDIR}/calc\fP \fB\-q\fP \fB\-f\fP

.fi

.in -5n

.sp 1

See

.B "SHELL SCRIPT MODE"

section of this man page

below for details.

.sp 1

While the actual form of this flag is:

.sp 1

.in +5n

.BR \-f

filename

.in -5n

.sp 1

for systems that treat an executable that begins with

.B #!

as a script, the path of the executable is appended by the kernel

as the final argument to the exec() system call.

This is why the

.B \-f

flag at the very end of the

.B #!

line.

.sp 1

It is possible use

.B \-f

filename

on the command line:

.sp 1

.in +5n

.nf

\fIcalc\fP\ [optional_other_flags\ \&...] \fB\-f\fP filename

.fi

.in -5n

.sp 1

This will cause calc to process lines in

.B filename

in

.BR "shell script mode" .

.sp 1

.B NOTE:

The use of

.BR \-f

does

.B NOT

imply

.BR \-q

and thus one would need to use

.sp 1

.in +5n

.nf

\fIcalc\fP\ [optional_other_flags\ \&...] \fB\-q\fP \fB\-f\fP filename

.fi

.in -5n

.sp 1

to disable the use of calc startup files as well.

.sp 1

The use of

.B \-f

filename

implies the

.B \-s

flag.

.TP

.B \-h

Print a help message. This option implies

.BR \-q .

This

is equivalent to the

.B calc

command help help.

The help facility is disabled unless the mode is 5 or 7.

See

.BR \-m .

.TP

.B \-i

Become interactive if possible.

This flag will cause

.B calc

to drop into interactive mode after the

.I calc_cmd

arguments on the command line are evaluated.

Without this flag,

.B calc

will exit after they are evaluated.

.sp 1

For example:

.sp 1

.in +5n

.nf

calc 2+5

.fi

.in -5n

.sp 1

will print the value 7 and exit whereas:

.sp 1

.in +5n

.nf

calc -i 2+5

.fi

.in -5n

.sp 1

will print the value 7 and prompt the user for more

.B calc

commands.

.TP

.BR \-m " mode"

This flag sets the permission mode of

.BR calc .

It controls the ability for

.B calc

to open files and execute programs.

.I Mode

may be a number from 0 to 7.

.sp 1

The mode value is interpreted in a way similar to that

of the

.BR chmod (1)

octal mode:

.sp 1

.in +5n

.nf

0 do not open any file, do not execute progs

1 do not open any file

2 do not open files for reading, do not execute progs

3 do not open files for reading

4 do not open files for writing, do not execute progs

5 do not open files for writing

6 do not execute any program

7 allow everything (default mode)

.fi

.in -5n

.sp 1

If one wished to run

.B calc

from a privileged user, one might want to use

.BR \-m " 0"

in an effort to make

.B calc

somewhat more secure.

.sp 1

Mode bits for reading and writing apply only on an

open.

Files already open are not effected.

Thus if one wanted to use the

.BR \-m " 0"

in an effort to make

.B calc

somewhat more secure, but still wanted to read and write a specific

file, one might want to do in

.BR sh (1),

.BR ksh (1),

.BR bash (1)-like

shells:

.sp 1

.in +5n

.nf

calc -m 0 3<a.file

.fi

.in -5n

.sp 1

Files presented to

.B calc

in this way are opened in an

unknown mode.

.B Calc

will attempt to read or write them if directed.

.sp 1

If the mode disables opening of files for reading, then

the startup resource files are disabled as if

.B \-q

was given.

The reading of key bindings is also disabled

when the mode disables opening of files for reading.

.TP

.B \-O

Use the old classic defaults instead of the

default configuration.

This flag as the same effect

as executing \fBconfig("all", "oldcfg")\fP at startup time.

.sp 1

NOTE: Older versions of calc used

.B \-n

to setup a modified form of the default calc configuration.

The

.B \-n

flag currently does nothing.

Use of the

.B \-n

flag is now deprecated and may be used for

something else in the future.

.TP

.B \-p

Pipe processing is enabled by use of

.BR \-p .

For example:

.sp 1

.in +5n

.nf

calc -p "2^21701-1" | fizzbin

.fi

.in -5n

.sp 1

In pipe mode,

.B calc

does not prompt, does not print leading

tabs and does not print the initial header.

The

.B \-p

flag overrides

.BR \-i .

.sp 1

When running calc as a shell script (see

.B "SHELL SCRIPT MODE"

for details), calc will close standard input (stdin)

during startup

.B UNLESS

the

.B \-p

flag is given on the command line.

When calc is running in

.BR "shell script mode" ,

shell scripts that call the

.BR prompt (str)

builtin will not work properly (the prompt builtin

will always fail) unless the

.B \-p

flag is given on the command line.

.TP

.B \-q

Disable the reading of the startup scripts.

.sp 1

This allows the script to run independently of

startup scripts such those managed by the

.B $CALCRC

environment variable.

For example, this will disable the use of the common calcrc file

(usually ~/.calcrc).

.TP

.B \-s

By default, all

.I calc_cmd

args are evaluated and executed.

This flag will disable their evaluation and instead make

them available as strings for the argv() builtin function.

.TP

.B \-u

Disable buffering of stdin and stdout.

.TP

.B \-v

Print the

.B calc

version number and exit.

.TP

.B \-\-

The double dash indicates to calc that no more options follow.

Thus calc will ignore a later argument on the command line

even if it starts with a dash.

This is useful when entering negative values on the command line as in:

.sp 1

.in +5n

.nf

calc \-p \-\- \-1 - -7

.fi

.in -5n

.sp 1

.PP

.SH CALC COMMAND LINE

.PP

With no

.I calc_cmd

arguments,

.B calc

operates interactively.

If one or more

arguments are given on the command line and

.B \-s

is NOT given, then

.B calc

will read and execute them and either attempt

to go interactive according as the

.B \-i

flag was present or absent.

.sp

If

.B \-s

is given,

.B calc

will not evaluate any

.I calc_cmd

arguments but instead make them available

as strings to the argv() builtin function.

Sufficiently simple commands with no characters like

parentheses, brackets, semicolons, '*', which have special

interpretations in UNIX shells may be entered, possibly with

spaces, until the terminating newline.

For example:

.sp 1

.in +5n

.nf

calc 23 + 47

.fi

.in -5n

.sp 1

will print 70.

However, command lines will have problems:

.sp 1

.in +5n

.nf

calc 23 * 47

.sp 1

calc -23 + 47

.fi

.in -5n

.sp 1

The first example above fails because the shell interprets the '*'

as a file glob.

The second example fails because '\-23' is viewed as a calc option

(which it is not) and do calc objects to that it thinks of as an unknown option.

These cases can usually be made to work as expected by

enclosing the command between quotes:

.sp 1

.in +5n

.nf

calc '23 * 47'

.sp 1

calc "print sqrt(2), exp(1)"

.fi

.in -5n

.sp 1

or in parentheses and quotes to avoid leading \-'s as in:

.sp 1

.in +5n

.nf

calc '(-23 + 47)'

.fi

.in -5n

.sp 1

One may also use a double dash to denote that calc options have ended as in:

.sp 1

.in +5n

.nf

calc -- -23 + 47

.sp 1

calc -q -- -23 + 47

.fi

.in -5n

.sp 1

If '!' is to be used to indicate the factorial function, for

shells like

.BI csh (1)

for which '!' followed by a non-space character

is used for history substitution, it may be necessary to

include a space or use a backslash to escape the special

meaning of '!'.

For example, the command:

.sp 1

.in +5n

.nf

print 27!^2

.fi

.in -5n

.sp 1

may have to be replaced by:

.sp 1

.in +5n

.nf

print 27! ^2 or print 27\\!^2

.fi

.in -5n

Reading from standard input when calc is part of a pipe works

as long as the \-p flag is given to calc. For example, this

will print chongo was here:

.sp 1

.in +5n

.nf

echo chongo was here | calc \-p 'print fgetline(files(0));'

.sp 1

.fi

.in -5n

.sp 1

while this does not:

.sp 1

.in +5n

.nf

echo chongo was here | calc 'print fgetline(files(0));'

.sp 1

.fi

.in -5n

.sp 1

nor will this print chongo was here:

.sp 1

.in +5n

.nf

echo chongo was here | calc \-i 'print fgetline(files(0));'

.sp 1

.fi

.in -5n

.sp 1

This is because without

.BR \-p ,

the interactive parser, in an effort

to parse interactive commands, flushes data on standard input.

.PP

.SH CALC STARTUP FILES

.PP

Normally on startup,

if the environment variable

.B $CALCRC

is undefined and

.B calc

is invoked without the

.B \-q

flag, or if

.B $CALCRC

is defined and calc is invoked with

.BR \-e ,

.B calc

looks for a file "startup" in the calc resource directory

.B .calcrc

in the user's home directory, and

.B .calcinit in the current directory.

If one or more of these are found, they are read in succession as

.B calc

scripts and their commands executed.

When defined,

.B $CALCRC

is to contain a ':' separated list of names of files,

and if calc is then invoked without either the

.B \-q

or

.B \-e

flags, these files are read in succession and their commands executed.

No error condition is produced if a listed file is not found.

.sp

If the mode specified by

.B \-m

disables opening of files for reading, then the reading of startup

files is also disabled as if

.B \-q

was given.

.PP

.SH CALC FILE SEARCH PATH

.PP

If the environment variable

.B $CALCPATH

is undefined, or if it

is defined and

.B calc

is invoked with the

.B \-e

flag, when a file name not beginning with

.BR / ,

.B ~

or

.BR ./ ,

is specified as in:

.sp 1

.in +5n

.nf

calc read myfile

.fi

.in -5n

.sp 1

.B calc

searches in succession:

.sp 1

.in +5n

.nf

\a./myfile

\a./myfile.cal

${LIBDIR}/myfile

${LIBDIR}/myfile.cal

${CUSTOMCALDIR}/myfile

${CUSTOMCALDIR}/myfile.cal

.fi

.in -5n

.sp 1

If the file is found, the

search stops and the commands in the file are executed.

It is an error if no readable file with the specified name is found.

An alternative search path can be specified by defining

.B $CALCPATH

in the same way as PATH is defined, as a ':' separated

list of directories, and then invoking

.B calc

without the

.B \-e

flag.

.PP

.B Calc

treats all open files, other than stdin, stdout and

stderr as files available for reading and writing.

One may

present

.B calc

with an already open file using

.BR sh (1),

.BR ksh (1),

.BR bash (1)-like

shells is to:

.sp 1

.in +5n

calc 3<open_file 4<open_file2

.in -5n

.sp 1

For more information use the following

.B calc

commands:

.sp 1

.in +5n

.nf

help help

help overview

help usage

help environment

help config

.fi

.in -5n

.sp 1

.PP

.SH SHELL SCRIPT MODE

.PP

If the first line of an executable file begins

.B #!

followed by the absolute pathname of the

.B calc

program and the first line ends with the flag

.B \-f

as in:

.sp 1

.in +5n

.nf

\fI#!${BINDIR}/calc\fP\ [optional_other_flags\ \&...] \fB\-f\fP

.fi

.in -5n

.sp 1

the rest of the file will be processed in

.BR "shell script mode" .

Note that

.B \-s

.B \-f

must be at the end of the initial ``#!'' line.

Any other optional

.B "optional_other_flags"

must come before

the

.B \-f

flag.

.sp 1

In

.B "shell script mode"

the contents of the file are read and

executed as if they were in a file being processed by a read

command, except that a "command" beginning with '#' followed by

whitespace and ending at the next newline is treated as a comment.

Any optional

.B "optional_other_flags"

will be parsed first followed by

the later lines within the script itself.

.sp 1

In

.BR "shell script mode" ,

.B \-s

is always assumed.

In addition,

.B \-d

and

.B \-p

are automatically set if

.B \-i

is not given.

.sp 1

.B NOTE:

The use of

.BR \-f

does

.B NOT

imply

.BR \-q

and thus one would need to use

.sp 1

.in +5n

.nf

\fIcalc\fP\ [optional_other_flags\ \&...] \fB\-q\fP \fB\-f\fP filename

.fi

.in -5n

.sp 1

to disable the use of calc startup files as well.

.sp 1

For example, if

the file

.BR /tmp/mersenne :

.sp 1

.in +5n

.nf

\fI#!${BINDIR}/calc\fP\ \&\fB\-q\fP \fB\-f\fP

/* setup */

argc = argv();

program = argv(0);

stderr = files(2);

/* parse args */

if (argc != 2) {

fprintf(stderr, "usage: %s exp\n", program);

abort "must give one exponent arg";

}

exp = eval(argv(1));

if (!isint(exp) || exp < 0) {

fprintf(stderr, "%s: exp must be non-negative integer\n", program);

abort "must give one exponent arg";

}

/* print the mersenne number */

print "2^": exp : "-1 =", 2^exp-1;

.fi

.in -5n

.sp 1

is made an executable file by:

.sp 1

.in +5n

.nf

chmod +x /tmp/mersenne

.fi

.in -5n

.sp 1

then the command line:

.sp 1

.in +5n

.nf

/tmp/mersenne 127

.fi

.in -5n

.sp 1

will print:

.sp 1

.in +5n

.nf

2^127-1 = 170141183460469231731687303715884105727

.fi

.in -5n

.sp 1

Note that because

.B \-s

is required in

.B "shell script mode"

non-dashed args are made available as

strings via the

.BR argv ()

builtin function.

Therefore:

.sp 1

.in +5n

.nf

2^eval(argv(1))-1

.fi

.in -5n

.sp 1

will print the decimal value of 2^n-1

whereas

.sp 1

.in +5n

.nf

2^argv(1)-1

.fi

.in -5n

.sp 1

will not.

.sp 1

By default, using calc startup in

.BR "shell script mode" ,

calc will close standard input (stdin).

Thus builtin functions such as

.BR prompt (str)

will fail (return a null value).

Calc shell scripts that call the

.BR prompt (str)

builtin will not work properly (the prompt builtin

will always fail and return a null value) unless the

.B \-p

flag is given on the command line.

.sp 1

The following shell script will always print "got null" because

stdin will be closed by calc during startup:

.sp 1

.in +5n

.nf

#!/usr/bin/calc \-q \-f

# The prompt will ALWAYS FAIL and return a null value

n = prompt("Test> ");

if (isnull(n)) {

print("got null");

} else {

print("got " + n);

}

.fi

.in -5n

.sp 1

However the following shell script (note the

.B \-p

before the

.B \-f

in the 1st line) will be interactive, prompt with "Test> " and print

the "got" result as expected:

.sp 1

.in +5n

.nf

#!/usr/bin/calc \-q \-p \-f

n = prompt("Test> ");