diff options
Diffstat (limited to 'man1p/bc.1p')
| -rw-r--r-- | man1p/bc.1p | 1354 |
1 files changed, 1354 insertions, 0 deletions
diff --git a/man1p/bc.1p b/man1p/bc.1p new file mode 100644 index 000000000..a2860dc69 --- /dev/null +++ b/man1p/bc.1p @@ -0,0 +1,1354 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "BC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" bc +.SH NAME +bc \- arbitrary-precision arithmetic language +.SH SYNOPSIS +.LP +\fBbc\fP \fB[\fP\fB-l\fP\fB] [\fP\fIfile\fP \fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIbc\fP utility shall implement an arbitrary precision calculator. +It shall take input from any files given, then read +from the standard input. If the standard input and standard output +to \fIbc\fP are attached to a terminal, the invocation of +\fIbc\fP shall be considered to be \fIinteractive\fP, causing behavioral +constraints described in the following sections. +.SH OPTIONS +.LP +The \fIbc\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-l\fP +(The letter ell.) Define the math functions and initialize \fIscale\fP +to 20, instead of the default zero; see the EXTENDED +DESCRIPTION section. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a text file containing \fIbc\fP program statements. +After all \fIfile\fPs have been read, \fIbc\fP shall read +the standard input. +.sp +.SH STDIN +.LP +See the INPUT FILES section. +.SH INPUT FILES +.LP +Input files shall be text files containing a sequence of comments, +statements, and function definitions that shall be executed +as they are read. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIbc\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The output of the \fIbc\fP utility shall be controlled by the program +read, and consist of zero or more lines containing the +value of all executed expressions without assignments. The radix and +precision of the output shall be controlled by the values of +the \fBobase\fP and \fBscale\fP variables; see the EXTENDED DESCRIPTION +section. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.SS Grammar +.LP +The grammar in this section and the lexical conventions in the following +section shall together describe the syntax for +\fIbc\fP programs. The general conventions for this style of grammar +are described in \fIGrammar Conventions\fP . A valid program can be +represented as the non-terminal symbol +\fBprogram\fP in the grammar. This formal syntax shall take precedence +over the text syntax description. +.sp +.RS +.nf + +\fB%token EOF NEWLINE STRING LETTER NUMBER +.sp + +%token MUL_OP +/* '*', '/', '%' */ +.sp + +%token ASSIGN_OP +/* '=', '+=', '-=', '*=', '/=', '%=', '^=' */ +.sp + +%token REL_OP +/* '==', '<=', '>=', '!=', '<', '>' */ +.sp + +%token INCR_DECR +/* '++', '--' */ +.sp + +%token Define Break Quit Length +/* 'define', 'break', 'quit', 'length' */ +.sp + +%token Return For If While Sqrt +/* 'return', 'for', 'if', 'while', 'sqrt' */ +.sp + +%token Scale Ibase Obase Auto +/* 'scale', 'ibase', 'obase', 'auto' */ +.sp + +%start program +.sp + +%% +.sp + +program : EOF + | input_item program + ; +.sp + +input_item : semicolon_list NEWLINE + | function + ; +.sp + +semicolon_list : /* empty */ + | statement + | semicolon_list ';' statement + | semicolon_list ';' + ; +.sp + +statement_list : /* empty */ + | statement + | statement_list NEWLINE + | statement_list NEWLINE statement + | statement_list ';' + | statement_list ';' statement + ; +.sp + +statement : expression + | STRING + | Break + | Quit + | Return + | Return '(' return_expression ')' + | For '(' expression ';' + relational_expression ';' + expression ')' statement + | If '(' relational_expression ')' statement + | While '(' relational_expression ')' statement + | '{' statement_list '}' + ; +.sp + +function : Define LETTER '(' opt_parameter_list ')' + '{' NEWLINE opt_auto_define_list + statement_list '}' + ; +.sp + +opt_parameter_list : /* empty */ + | parameter_list + ; +.sp + +parameter_list : LETTER + | define_list ',' LETTER + ; +.sp + +opt_auto_define_list : /* empty */ + | Auto define_list NEWLINE + | Auto define_list ';' + ; +.sp + +define_list : LETTER + | LETTER '[' ']' + | define_list ',' LETTER + | define_list ',' LETTER '[' ']' + ; +.sp + +opt_argument_list : /* empty */ + | argument_list + ; +.sp + +argument_list : expression + | LETTER '[' ']' ',' argument_list + ; +.sp + +relational_expression : expression + | expression REL_OP expression + ; +.sp + +return_expression : /* empty */ + | expression + ; +.sp + +expression : named_expression + | NUMBER + | '(' expression ')' + | LETTER '(' opt_argument_list ')' + | '-' expression + | expression '+' expression + | expression '-' expression + | expression MUL_OP expression + | expression '^' expression + | INCR_DECR named_expression + | named_expression INCR_DECR + | named_expression ASSIGN_OP expression + | Length '(' expression ')' + | Sqrt '(' expression ')' + | Scale '(' expression ')' + ; +.sp + +named_expression : LETTER + | LETTER '[' expression ']' + | Scale + | Ibase + | Obase + ; +\fP +.fi +.RE +.SS Lexical Conventions in bc +.LP +The lexical conventions for \fIbc\fP programs, with respect to the +preceding grammar, shall be as follows: +.IP " 1." 4 +Except as noted, \fIbc\fP shall recognize the longest possible token +or delimiter beginning at a given point. +.LP +.IP " 2." 4 +A comment shall consist of any characters beginning with the two adjacent +characters \fB"/*"\fP and terminated by the next +occurrence of the two adjacent characters \fB"*/"\fP . Comments shall +have no effect except to delimit lexical tokens. +.LP +.IP " 3." 4 +The <newline> shall be recognized as the token \fBNEWLINE\fP. +.LP +.IP " 4." 4 +The token \fBSTRING\fP shall represent a string constant; it shall +consist of any characters beginning with the double-quote +character ( \fB' )'\fP and terminated by another occurrence of the +double-quote character. The value of the string is the +sequence of all characters between, but not including, the two double-quote +characters. All characters shall be taken literally +from the input, and there is no way to specify a string containing +a double-quote character. The length of the value of each string +shall be limited to {BC_STRING_MAX} bytes. +.LP +.IP " 5." 4 +A <blank> shall have no effect except as an ordinary character if +it appears within a \fBSTRING\fP token, or to delimit a +lexical token other than \fBSTRING\fP. +.LP +.IP " 6." 4 +The combination of a backslash character immediately followed by a +<newline> shall have no effect other than to delimit +lexical tokens with the following exceptions: +.RS +.IP " *" 3 +It shall be interpreted as the character sequence \fB"\\<newline>"\fP +in \fBSTRING\fP tokens. +.LP +.IP " *" 3 +It shall be ignored as part of a multi-line \fBNUMBER\fP token. +.LP +.RE +.LP +.IP " 7." 4 +The token \fBNUMBER\fP shall represent a numeric constant. It shall +be recognized by the following grammar: +.sp +.RS +.nf + +\fBNUMBER : integer + | '.' integer + | integer '.' + | integer '.' integer + ; +.sp + +integer : digit + | integer digit + ; +.sp + +digit : 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 + | 8 | 9 | A | B | C | D | E | F + ; +\fP +.fi +.RE +.LP +.IP " 8." 4 +The value of a \fBNUMBER\fP token shall be interpreted as a numeral +in the base specified by the value of the internal register +\fBibase\fP (described below). Each of the \fBdigit\fP characters +shall have the value from 0 to 15 in the order listed here, and +the period character shall represent the radix point. The behavior +is undefined if digits greater than or equal to the value of +\fBibase\fP appear in the token. However, note the exception for single-digit +values being assigned to \fBibase\fP and +\fBobase\fP themselves, in Operations in bc . +.LP +.IP " 9." 4 +The following keywords shall be recognized as tokens: +.TS C +center; lw(15) lw(15) lw(15) lw(15) lw(15). +T{ +\fB +.br +auto +.br +break +.br +define +.br +\fP +T} T{ +\fB +.br +ibase +.br +if +.br +for +.br +\fP +T} T{ +\fB +.br +length +.br +obase +.br +quit +.br +\fP +T} T{ +\fB +.br +return +.br +scale +.br +sqrt +.br +\fP +T} T{ +\fB +.br +while +.br +\fP +T} +.TE +.LP +.IP "10." 4 +Any of the following characters occurring anywhere except within a +keyword shall be recognized as the token \fBLETTER\fP: +.sp +.RS +.nf + +\fBa b c d e f g h i j k l m n o p q r s t u v w x y z +\fP +.fi +.RE +.LP +.IP "11." 4 +The following single-character and two-character sequences shall be +recognized as the token \fBASSIGN_OP\fP: +.sp +.RS +.nf + +\fB= += -= *= /= %= ^= +\fP +.fi +.RE +.LP +.IP "12." 4 +If an \fB'='\fP character, as the beginning of a token, is followed +by a \fB'-'\fP character with no intervening +delimiter, the behavior is undefined. +.LP +.IP "13." 4 +The following single-characters shall be recognized as the token \fBMUL_OP\fP: +.sp +.RS +.nf + +\fB* / % +\fP +.fi +.RE +.LP +.IP "14." 4 +The following single-character and two-character sequences shall be +recognized as the token \fBREL_OP\fP: +.sp +.RS +.nf + +\fB== <= >= != < > +\fP +.fi +.RE +.LP +.IP "15." 4 +The following two-character sequences shall be recognized as the token +\fBINCR_DECR\fP: +.sp +.RS +.nf + +\fB++ -- +\fP +.fi +.RE +.LP +.IP "16." 4 +The following single characters shall be recognized as tokens whose +names are the character: +.sp +.RS +.nf + +\fB<newline> ( ) , + - ; [ ] ^ { } +\fP +.fi +.RE +.LP +.IP "17." 4 +The token \fBEOF\fP is returned when the end of input is reached. +.LP +.SS Operations in bc +.LP +There are three kinds of identifiers: ordinary identifiers, array +identifiers, and function identifiers. All three types consist +of single lowercase letters. Array identifiers shall be followed by +square brackets ( \fB"[]"\fP ). An array subscript is +required except in an argument or auto list. Arrays are singly dimensioned +and can contain up to {BC_DIM_MAX} elements. Indexing +shall begin at zero so an array is indexed from 0 to {BC_DIM_MAX}-1. +Subscripts shall be truncated to integers. The application +shall ensure that function identifiers are followed by parentheses, +possibly enclosing arguments. The three types of identifiers do +not conflict. +.LP +The following table summarizes the rules for precedence and associativity +of all operators. Operators on the same line shall +have the same precedence; rows are in order of decreasing precedence. +.sp +.ce 1 +\fBTable: Operators in \fIbc\fP\fP +.TS C +center; l l. +\fBOperator\fP \fBAssociativity\fP +++, -- N/A +unary - N/A +^ Right to left +*, /, % Left to right ++, binary - Left to right +=, +=, -=, *=, /=, %=, ^= Right to left +==, <=, >=, !=, <, > None +.TE +.LP +Each expression or named expression has a \fIscale\fP, which is the +number of decimal digits that shall be maintained as the +fractional portion of the expression. +.LP +\fINamed expressions\fP are places where values are stored. Named +expressions shall be valid on the left side of an assignment. +The value of a named expression shall be the value stored in the place +named. Simple identifiers and array elements are named +expressions; they have an initial value of zero and an initial scale +of zero. +.LP +The internal registers \fBscale\fP, \fBibase\fP, and \fBobase\fP are +all named expressions. The scale of an expression +consisting of the name of one of these registers shall be zero; values +assigned to any of these registers are truncated to +integers. The \fBscale\fP register shall contain a global value used +in computing the scale of expressions (as described below). +The value of the register \fBscale\fP is limited to 0 <= \fBscale\fP +<= {BC_SCALE_MAX} and shall have a default value of +zero. The \fBibase\fP and \fBobase\fP registers are the input and +output number radix, respectively. The value of \fBibase\fP +shall be limited to: +.sp +.RS +.nf + +\fB2 <= ibase <= 16 +\fP +.fi +.RE +.LP +The value of \fBobase\fP shall be limited to: +.sp +.RS +.nf + +\fB2 <= obase <= {BC_BASE_MAX} +\fP +.fi +.RE +.LP +When either \fBibase\fP or \fBobase\fP is assigned a single \fBdigit\fP +value from the list in Lexical Conventions in bc , the value shall +be assumed in hexadecimal. (For example, \fBibase\fP=A sets to +base ten, regardless of the current \fBibase\fP value.) Otherwise, +the behavior is undefined when digits greater than or equal to +the value of \fBibase\fP appear in the input. Both \fBibase\fP and +\fBobase\fP shall have initial values of 10. +.LP +Internal computations shall be conducted as if in decimal, regardless +of the input and output bases, to the specified number of +decimal digits. When an exact result is not achieved (for example, +\fBscale\fP=0;\ 3.2/1)\fB,\fP the result shall be +truncated. +.LP +For all values of \fBobase\fP specified by this volume of IEEE\ Std\ 1003.1-2001, +\fIbc\fP shall output numeric values +by performing each of the following steps in order: +.IP " 1." 4 +If the value is less than zero, a hyphen ( \fB'-'\fP ) character shall +be output. +.LP +.IP " 2." 4 +One of the following is output, depending on the numerical value: +.RS +.IP " *" 3 +If the absolute value of the numerical value is greater than or equal +to one, the integer portion of the value shall be output +as a series of digits appropriate to \fBobase\fP (as described below), +most significant digit first. The most significant non-zero +digit shall be output next, followed by each successively less significant +digit. +.LP +.IP " *" 3 +If the absolute value of the numerical value is less than one but +greater than zero and the scale of the numerical value is +greater than zero, it is unspecified whether the character 0 is output. +.LP +.IP " *" 3 +If the numerical value is zero, the character 0 shall be output. +.LP +.RE +.LP +.IP " 3." 4 +If the scale of the value is greater than zero and the numeric value +is not zero, a period character shall be output, followed +by a series of digits appropriate to \fBobase\fP (as described below) +representing the most significant portion of the fractional +part of the value. If \fIs\fP represents the scale of the value being +output, the number of digits output shall be \fIs\fP if +\fBobase\fP is 10, less than or equal to \fIs\fP if \fBobase\fP is +greater than 10, or greater than or equal to \fIs\fP if +\fBobase\fP is less than 10. For \fBobase\fP values other than 10, +this should be the number of digits needed to represent a +precision of 10**\fIs\fP. +.LP +.LP +For \fBobase\fP values from 2 to 16, valid digits are the first \fBobase\fP +of the single characters: +.sp +.RS +.nf + +\fB0 1 2 3 4 5 6 7 8 9 A B C D E F +\fP +.fi +.RE +.LP +which represent the values zero to 15, inclusive, respectively. +.LP +For bases greater than 16, each digit shall be written as a separate +multi-digit decimal number. Each digit except the most +significant fractional digit shall be preceded by a single <space>. +For bases from 17 to 100, \fIbc\fP shall write two-digit +decimal numbers; for bases from 101 to 1000, three-digit decimal strings, +and so on. For example, the decimal number 1024 in base +25 would be written as: +.sp +.RS +.nf + +\fB 01 15 24 +\fP +.fi +.RE +.LP +and in base 125, as: +.sp +.RS +.nf + +\fB 008 024 +\fP +.fi +.RE +.LP +Very large numbers shall be split across lines with 70 characters +per line in the POSIX locale; other locales may split at +different character boundaries. Lines that are continued shall end +with a backslash ( \fB'\\'\fP ). +.LP +A function call shall consist of a function name followed by parentheses +containing a comma-separated list of expressions, which +are the function arguments. A whole array passed as an argument shall +be specified by the array name followed by empty square +brackets. All function arguments shall be passed by value. As a result, +changes made to the formal parameters shall have no effect +on the actual arguments. If the function terminates by executing a +\fBreturn\fP statement, the value of the function shall be the +value of the expression in the parentheses of the \fBreturn\fP statement +or shall be zero if no expression is provided or if there +is no \fBreturn\fP statement. +.LP +The result of \fBsqrt\fP( \fIexpression\fP) shall be the square root +of the expression. The result shall be truncated in the +least significant decimal place. The scale of the result shall be +the scale of the expression or the value of \fBscale\fP, +whichever is larger. +.LP +The result of \fBlength\fP( \fIexpression\fP) shall be the total number +of significant decimal digits in the expression. The +scale of the result shall be zero. +.LP +The result of \fBscale\fP( \fIexpression\fP) shall be the scale of +the expression. The scale of the result shall be zero. +.LP +A numeric constant shall be an expression. The scale shall be the +number of digits that follow the radix point in the input +representing the constant, or zero if no radix point appears. +.LP +The sequence (\ \fIexpression\fP\ ) shall be an expression with the +same value and scale as \fIexpression\fP. The +parentheses can be used to alter the normal precedence. +.LP +The semantics of the unary and binary operators are as follows: +.TP 7 +-\fIexpression\fP +.sp +The result shall be the negative of the \fIexpression\fP. The scale +of the result shall be the scale of \fIexpression\fP. +.sp +.LP +The unary increment and decrement operators shall not modify the scale +of the named expression upon which they operate. The +scale of the result shall be the scale of that named expression. +.TP 7 +++\fInamed-expression\fP +.sp +The named expression shall be incremented by one. The result shall +be the value of the named expression after incrementing. +.TP 7 +--\fInamed-expression\fP +.sp +The named expression shall be decremented by one. The result shall +be the value of the named expression after decrementing. +.TP 7 +\fInamed-expression\fP++ +.sp +The named expression shall be incremented by one. The result shall +be the value of the named expression before incrementing. +.TP 7 +\fInamed-expression\fP-- +.sp +The named expression shall be decremented by one. The result shall +be the value of the named expression before decrementing. +.sp +.LP +The exponentiation operator, circumflex ( \fB'^'\fP ), shall bind +right to left. +.TP 7 +\fIexpression\fP^\fIexpression\fP +.sp +The result shall be the first \fIexpression\fP raised to the power +of the second \fIexpression\fP. If the second expression is +not an integer, the behavior is undefined. If \fIa\fP is the scale +of the left expression and \fIb\fP is the absolute value of +the right expression, the scale of the result shall be: +.sp +.RS +.nf + +\fBif b >= 0 min(a * b, max(scale, a)) if b < 0 scale +\fP +.fi +.RE +.sp +The multiplicative operators ( \fB'*'\fP , \fB'/'\fP , \fB'%'\fP ) +shall bind left to right. +.TP 7 +\fIexpression\fP*\fIexpression\fP +.sp +The result shall be the product of the two expressions. If \fIa\fP +and \fIb\fP are the scales of the two expressions, then the +scale of the result shall be: +.sp +.RS +.nf + +\fBmin(a+b,max(scale,a,b)) +\fP +.fi +.RE +.TP 7 +\fIexpression\fP/\fIexpression\fP +.sp +The result shall be the quotient of the two expressions. The scale +of the result shall be the value of \fBscale\fP. +.TP 7 +\fIexpression\fP%\fIexpression\fP +.sp +For expressions \fIa\fP and \fIb\fP, \fIa\fP% \fIb\fP shall be evaluated +equivalent to the steps: +.RS +.IP " 1." 4 +Compute \fIa\fP/ \fIb\fP to current scale. +.LP +.IP " 2." 4 +Use the result to compute: +.sp +.RS +.nf + +\fBa - (a / b) * b +\fP +.fi +.RE +.LP +to scale: +.sp +.RS +.nf + +\fBmax(scale + scale(b), scale(a)) +\fP +.fi +.RE +.LP +.RE +The scale of the result shall be: +.sp +.RS +.nf + +\fBmax(scale + scale(b), scale(a)) +\fP +.fi +.RE +.LP +When \fBscale\fP is zero, the \fB'%'\fP operator is the mathematical +remainder operator. +.sp +.LP +The additive operators ( \fB'+'\fP , \fB'-'\fP ) shall bind left to +right. +.TP 7 +\fIexpression\fP+\fIexpression\fP +.sp +The result shall be the sum of the two expressions. The scale of the +result shall be the maximum of the scales of the +expressions. +.TP 7 +\fIexpression\fP-\fIexpression\fP +.sp +The result shall be the difference of the two expressions. The scale +of the result shall be the maximum of the scales of the +expressions. +.sp +.LP +The assignment operators ( \fB'='\fP , \fB"+="\fP , \fB"-="\fP , \fB"*="\fP +, \fB"/="\fP , \fB"%="\fP , +\fB"^="\fP ) shall bind right to left. +.TP 7 +\fInamed-expression\fP=\fIexpression\fP +.sp +This expression shall result in assigning the value of the expression +on the right to the named expression on the left. The scale +of both the named expression and the result shall be the scale of +\fIexpression\fP. +.sp +.LP +The compound assignment forms: +.sp +.RS +.nf + +\fInamed-expression\fP \fB<\fP\fIoperator\fP\fB>=\fP \fIexpression\fP +.fi +.RE +.LP +shall be equivalent to: +.sp +.RS +.nf + +\fInamed-expression\fP\fB=\fP\fInamed-expression\fP \fB<\fP\fIoperator\fP\fB>\fP \fIexpression\fP +.fi +.RE +.LP +except that the \fInamed-expression\fP shall be evaluated only once. +.LP +Unlike all other operators, the relational operators ( \fB'<'\fP , +\fB'>'\fP , \fB"<="\fP , \fB">="\fP , +\fB"=="\fP , \fB"!="\fP ) shall be only valid as the object of an +\fBif\fP, \fBwhile\fP, or inside a \fBfor\fP +statement. +.TP 7 +\fIexpression1\fP<\fIexpression2\fP +.sp +The relation shall be true if the value of \fIexpression1\fP is strictly +less than the value of \fIexpression2\fP. +.TP 7 +\fIexpression1\fP>\fIexpression2\fP +.sp +The relation shall be true if the value of \fIexpression1\fP is strictly +greater than the value of \fIexpression2\fP. +.TP 7 +\fIexpression1\fP<=\fIexpression2\fP +.sp +The relation shall be true if the value of \fIexpression1\fP is less +than or equal to the value of \fIexpression2\fP. +.TP 7 +\fIexpression1\fP>=\fIexpression2\fP +.sp +The relation shall be true if the value of \fIexpression1\fP is greater +than or equal to the value of \fIexpression2\fP. +.TP 7 +\fIexpression1\fP==\fIexpression2\fP +.sp +The relation shall be true if the values of \fIexpression1\fP and +\fIexpression2\fP are equal. +.TP 7 +\fIexpression1\fP!=\fIexpression2\fP +.sp +The relation shall be true if the values of \fIexpression1\fP and +\fIexpression2\fP are unequal. +.sp +.LP +There are only two storage classes in \fIbc\fP: global and automatic +(local). Only identifiers that are local to a function +need be declared with the \fBauto\fP command. The arguments to a function +shall be local to the function. All other identifiers +are assumed to be global and available to all functions. All identifiers, +global and local, have initial values of zero. +Identifiers declared as auto shall be allocated on entry to the function +and released on returning from the function. They +therefore do not retain values between function calls. Auto arrays +shall be specified by the array name followed by empty square +brackets. On entry to a function, the old values of the names that +appear as parameters and as automatic variables shall be pushed +onto a stack. Until the function returns, reference to these names +shall refer only to the new values. +.LP +References to any of these names from other functions that are called +from this function also refer to the new value until one +of those functions uses the same name for a local variable. +.LP +When a statement is an expression, unless the main operator is an +assignment, execution of the statement shall write the value +of the expression followed by a <newline>. +.LP +When a statement is a string, execution of the statement shall write +the value of the string. +.LP +Statements separated by semicolons or <newline>s shall be executed +sequentially. In an interactive invocation of +\fIbc\fP, each time a <newline> is read that satisfies the grammatical +production: +.sp +.RS +.nf + +\fBinput_item : semicolon_list NEWLINE +\fP +.fi +.RE +.LP +the sequential list of statements making up the \fBsemicolon_list\fP +shall be executed immediately and any output produced by +that execution shall be written without any delay due to buffering. +.LP +In an \fBif\fP statement ( \fBif\fP( \fIrelation\fP) \fIstatement\fP), +the \fIstatement\fP shall be executed if the +relation is true. +.LP +The \fBwhile\fP statement ( \fBwhile\fP( \fIrelation\fP) \fIstatement\fP) +implements a loop in which the \fIrelation\fP is +tested; each time the \fIrelation\fP is true, the \fIstatement\fP +shall be executed and the \fIrelation\fP retested. When the +\fIrelation\fP is false, execution shall resume after \fIstatement\fP. +.LP +A \fBfor\fP statement( \fBfor\fP( \fIexpression\fP; \fIrelation\fP; +\fIexpression\fP) \fIstatement\fP) shall be the same +as: +.sp +.RS +.nf + +\fIfirst-expression\fP\fBwhile (\fP\fIrelation\fP\fB) { + \fP \fIstatement\fP \fB \fP \fIlast-expression\fP\fB} +\fP +.fi +.RE +The application shall ensure that all three expressions are present. +.LP +The \fBbreak\fP statement shall cause termination of a \fBfor\fP or +\fBwhile\fP statement. +.LP +The \fBauto\fP statement ( \fBauto\fP \fIidentifier\fP \fB[\fP, \fIidentifier\fP +\fB]\fP ...) shall cause the values of +the identifiers to be pushed down. The identifiers can be ordinary +identifiers or array identifiers. Array identifiers shall be +specified by following the array name by empty square brackets. The +application shall ensure that the \fBauto\fP statement is the +first statement in a function definition. +.LP +A \fBdefine\fP statement: +.sp +.RS +.nf + +\fBdefine\fP \fILETTER\fP \fB(\fP \fIopt_parameter_list\fP \fB) { + \fP \fIopt_auto_define_list\fP \fB \fP \fIstatement_list\fP\fB} +\fP +.fi +.RE +.LP +defines a function named \fBLETTER\fP. If a function named \fBLETTER\fP +was previously defined, the \fBdefine\fP statement +shall replace the previous definition. The expression: +.sp +.RS +.nf + +\fBLETTER (\fP \fIopt_argument_list\fP \fB) +\fP +.fi +.RE +.LP +shall invoke the function named \fBLETTER\fP. The behavior is undefined +if the number of arguments in the invocation does not +match the number of parameters in the definition. Functions shall +be defined before they are invoked. A function shall be +considered to be defined within its own body, so recursive calls are +valid. The values of numeric constants within a function shall +be interpreted in the base specified by the value of the \fBibase\fP +register when the function is invoked. +.LP +The \fBreturn\fP statements ( \fBreturn\fP and \fBreturn\fP( \fIexpression\fP)) +shall cause termination of a function, +popping of its auto variables, and specification of the result of +the function. The first form shall be equivalent to +\fBreturn\fP(0). The value and scale of the result returned by the +function shall be the value and scale of the expression +returned. +.LP +The \fBquit\fP statement ( \fBquit\fP) shall stop execution of a \fIbc\fP +program at the point where the statement occurs in +the input, even if it occurs in a function definition, or in an \fBif\fP, +\fBfor\fP, or \fBwhile\fP statement. +.LP +The following functions shall be defined when the \fB-l\fP option +is specified: +.TP 7 +\fBs\fP(\ \fIexpression\fP\ ) +.sp +Sine of argument in radians. +.TP 7 +\fBc\fP(\ \fIexpression\fP\ ) +.sp +Cosine of argument in radians. +.TP 7 +\fBa\fP(\ \fIexpression\fP\ ) +.sp +Arctangent of argument. +.TP 7 +\fBl\fP(\ \fIexpression\fP\ ) +.sp +Natural logarithm of argument. +.TP 7 +\fBe\fP(\ \fIexpression\fP\ ) +.sp +Exponential function of argument. +.TP 7 +\fBj\fP(\ \fIexpression\fP,\ \fIexpression\fP\ ) +.sp +Bessel function of integer order. +.sp +.LP +The scale of the result returned by these functions shall be the value +of the \fBscale\fP register at the time the function is +invoked. The value of the \fBscale\fP register after these functions +have completed their execution shall be the same value it had +upon invocation. The behavior is undefined if any of these functions +is invoked with an argument outside the domain of the +mathematical function. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +0 +All input files were processed successfully. +.TP 7 +\fIunspecified\fP +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If any \fIfile\fP operand is specified and the named file cannot be +accessed, \fIbc\fP shall write a diagnostic message to +standard error and terminate without any further action. +.LP +In an interactive invocation of \fIbc\fP, the utility should print +an error message and recover following any error in the +input. In a non-interactive invocation of \fIbc\fP, invalid input +causes undefined behavior. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Automatic variables in \fIbc\fP do not work in exactly the same way +as in either C or PL/1. +.LP +For historical reasons, the exit status from \fIbc\fP cannot be relied +upon to indicate that an error has occurred. Returning +zero after an error is possible. Therefore, \fIbc\fP should be used +primarily by interactive users (who can react to error +messages) or by application programs that can somehow validate the +answers returned as not including error messages. +.LP +The \fIbc\fP utility always uses the period ( \fB'.'\fP ) character +to represent a radix point, regardless of any +decimal-point character specified as part of the current locale. In +languages like C or \fIawk\fP, the period character is used in program +source, so it can be portable and unambiguous, +while the locale-specific character is used in input and output. Because +there is no distinction between source and input in +\fIbc\fP, this arrangement would not be possible. Using the locale-specific +character in \fIbc\fP's input would introduce +ambiguities into the language; consider the following example in a +locale with a comma as the decimal-point character: +.sp +.RS +.nf + +\fBdefine f(a,b) { + ... +} +\&... +.sp + +f(1,2,3) +\fP +.fi +.RE +.LP +Because of such ambiguities, the period character is used in input. +Having input follow different conventions from output would +be confusing in either pipeline usage or interactive usage, so the +period is also used in output. +.SH EXAMPLES +.LP +In the shell, the following assigns an approximation of the first +ten digits of \fB'pi'\fP to the variable \fIx\fP: +.sp +.RS +.nf + +\fBx=$(printf "%s\\n" 'scale = 10; 104348/33215' | bc) +\fP +.fi +.RE +.LP +The following \fIbc\fP program prints the same approximation of \fB'pi'\fP +, with a +label, to standard output: +.sp +.RS +.nf + +\fBscale = 10 +"pi equals " +104348 / 33215 +\fP +.fi +.RE +.LP +The following defines a function to compute an approximate value of +the exponential function (note that such a function is +predefined if the \fB-l\fP option is specified): +.sp +.RS +.nf + +\fBscale = 20 +define e(x){ + auto a, b, c, i, s + a = 1 + b = 1 + s = 1 + for (i = 1; 1 == 1; i++){ + a = a*x + b = b*i + c = a/b + if (c == 0) { + return(s) + } + s = s+c + } +} +\fP +.fi +.RE +.LP +The following prints approximate values of the exponential function +of the first ten integers: +.sp +.RS +.nf + +\fBfor (i = 1; i <= 10; ++i) { + e(i) +} +\fP +.fi +.RE +.SH RATIONALE +.LP +The \fIbc\fP utility is implemented historically as a front-end processor +for \fIdc\fP; \fIdc\fP was not selected to be part +of this volume of IEEE\ Std\ 1003.1-2001 because \fIbc\fP was thought +to have a more intuitive programmatic interface. +Current implementations that implement \fIbc\fP using \fIdc\fP are +expected to be compliant. +.LP +The exit status for error conditions has been left unspecified for +several reasons: +.IP " *" 3 +The \fIbc\fP utility is used in both interactive and non-interactive +situations. Different exit codes may be appropriate for +the two uses. +.LP +.IP " *" 3 +It is unclear when a non-zero exit should be given; divide-by-zero, +undefined functions, and syntax errors are all +possibilities. +.LP +.IP " *" 3 +It is not clear what utility the exit status has. +.LP +.IP " *" 3 +In the 4.3 BSD, System V, and Ninth Edition implementations, \fIbc\fP +works in conjunction with \fIdc\fP. The \fIdc\fP +utility is the parent, \fIbc\fP is the child. This was done to cleanly +terminate \fIbc\fP if \fIdc\fP aborted. +.LP +.LP +The decision to have \fIbc\fP exit upon encountering an inaccessible +input file is based on the belief that \fIbc\fP +\fIfile1\fP \fIfile2\fP is used most often when at least \fIfile1\fP +contains data/function declarations/initializations. Having +\fIbc\fP continue with prerequisite files missing is probably not +useful. There is no implication in the CONSEQUENCES OF ERRORS +section that \fIbc\fP must check all its files for accessibility before +opening any of them. +.LP +There was considerable debate on the appropriateness of the language +accepted by \fIbc\fP. Several reviewers preferred to see +either a pure subset of the C language or some changes to make the +language more compatible with C. While the \fIbc\fP language +has some obvious similarities to C, it has never claimed to be compatible +with any version of C. An interpreter for a subset of C +might be a very worthwhile utility, and it could potentially make +\fIbc\fP obsolete. However, no such utility is known in +historical practice, and it was not within the scope of this volume +of IEEE\ Std\ 1003.1-2001 to define such a language and +utility. If and when they are defined, it may be appropriate to include +them in a future version of IEEE\ Std\ 1003.1. This +left the following alternatives: +.IP " 1." 4 +Exclude any calculator language from this volume of IEEE\ Std\ 1003.1-2001. +.LP +The consensus of the standard developers was that a simple programmatic +calculator language is very useful for both applications +and interactive users. The only arguments for excluding any calculator +were that it would become obsolete if and when a +C-compatible one emerged, or that the absence would encourage the +development of such a C-compatible one. These arguments did not +sufficiently address the needs of current application writers. +.LP +.IP " 2." 4 +Standardize the historical \fIdc\fP, possibly with minor modifications. +.LP +The consensus of the standard developers was that \fIdc\fP is a fundamentally +less usable language and that that would be far +too severe a penalty for avoiding the issue of being similar to but +incompatible with C. +.LP +.IP " 3." 4 +Standardize the historical \fIbc\fP, possibly with minor modifications. +.LP +This was the approach taken. Most of the proponents of changing the +language would not have been satisfied until most or all of +the incompatibilities with C were resolved. Since most of the changes +considered most desirable would break historical applications +and require significant modification to historical implementations, +almost no modifications were made. The one significant +modification that was made was the replacement of the historical \fIbc\fP +assignment operators \fB"=+"\fP , and so on, with the +more modern \fB"+="\fP , and so on. The older versions are considered +to be fundamentally flawed because of the lexical +ambiguity in uses like \fIa\fP=-1. +.LP +In order to permit implementations to deal with backwards-compatibility +as they see fit, the behavior of this one ambiguous +construct was made undefined. (At least three implementations have +been known to support this change already, so the degree of +change involved should not be great.) +.LP +.LP +The \fB'%'\fP operator is the mathematical remainder operator when +\fBscale\fP is zero. The behavior of this operator for +other values of \fBscale\fP is from historical implementations of +\fIbc\fP, and has been maintained for the sake of historical +applications despite its non-intuitive nature. +.LP +Historical implementations permit setting \fBibase\fP and \fBobase\fP +to a broader range of values. This includes values less +than 2, which were not seen as sufficiently useful to standardize. +These implementations do not interpret input properly for values +of \fBibase\fP that are greater than 16. This is because numeric constants +are recognized syntactically, rather than lexically, as +described in this volume of IEEE\ Std\ 1003.1-2001. They are built +from lexical tokens of single hexadecimal digits and +periods. Since <blank>s between tokens are not visible at the syntactic +level, it is not possible to recognize the +multi-digit "digits" used in the higher bases properly. The ability +to recognize input in these bases was not considered useful +enough to require modifying these implementations. Note that the recognition +of numeric constants at the syntactic level is not a +problem with conformance to this volume of IEEE\ Std\ 1003.1-2001, +as it does not impact the behavior of conforming +applications (and correct \fIbc\fP programs). Historical implementations +also accept input with all of the digits \fB'0'\fP - +\fB'9'\fP and \fB'A'\fP - \fB'F'\fP regardless of the value of \fBibase\fP; +since digits with value greater than or equal +to \fBibase\fP are not really appropriate, the behavior when they +appear is undefined, except for the common case of: +.sp +.RS +.nf + +\fBibase=8; + /* Process in octal base. */ +\&... +ibase=A + /* Restore decimal base. */ +\fP +.fi +.RE +.LP +In some historical implementations, if the expression to be written +is an uninitialized array element, a leading <space> +and/or up to four leading 0 characters may be output before the character +zero. This behavior is considered a bug; it is unlikely +that any currently conforming application relies on: +.sp +.RS +.nf + +\fBecho 'b[3]' | bc +\fP +.fi +.RE +.LP +returning 00000 rather than 0. +.LP +Exact calculation of the number of fractional digits to output for +a given value in a base other than 10 can be computationally +expensive. Historical implementations use a faster approximation, +and this is permitted. Note that the requirements apply only to +values of \fBobase\fP that this volume of IEEE\ Std\ 1003.1-2001 requires +implementations to support (in particular, not +to 1, 0, or negative bases, if an implementation supports them as +an extension). +.LP +Historical implementations of \fIbc\fP did not allow array parameters +to be passed as the last parameter to a function. New +implementations are encouraged to remove this restriction even though +it is not required by the grammar. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIGrammar Conventions\fP , \fIawk\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |