diff options
Diffstat (limited to 'usr.bin')
28 files changed, 0 insertions, 10045 deletions
diff --git a/usr.bin/bc/USD.doc/bc b/usr.bin/bc/USD.doc/bc deleted file mode 100644 index c4e68c6..0000000 --- a/usr.bin/bc/USD.doc/bc +++ /dev/null @@ -1,1241 +0,0 @@ -.\" $FreeBSD$ -.\" $OpenBSD: bc,v 1.9 2004/07/09 10:23:05 jmc Exp $ -.\" -.\" Copyright (C) Caldera International Inc. 2001-2002. -.\" All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code and documentation must retain the above -.\" copyright notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed or owned by Caldera -.\" International, Inc. -.\" 4. Neither the name of Caldera International, Inc. nor the names of other -.\" contributors may be used to endorse or promote products derived from -.\" this software without specific prior written permission. -.\" -.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA -.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES -.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. -.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT, -.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, -.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING -.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -.\" POSSIBILITY OF SUCH DAMAGE. -.\" -.\" @(#)bc 6.2 (Berkeley) 4/17/91 -.\" -.if n \{\ -.po 5n -.ll 70n -.\} -.EH 'USD:6-%''BC \- An Arbitrary Precision Desk-Calculator Language' -.OH 'BC \- An Arbitrary Precision Desk-Calculator Language''USD:6-%' -.\".RP -.TL -BC \- An Arbitrary Precision Desk-Calculator Language -.AU -Lorinda Cherry -.AU -Robert Morris -.AI -.\" .MH -.AB -BC is a language and a compiler for doing arbitrary precision arithmetic -on the PDP-11 under the -.UX -time-sharing -system. The output of the compiler is interpreted and executed by -a collection of routines which can input, output, and do -arithmetic on indefinitely large integers and on scaled fixed-point -numbers. -.PP -These routines are themselves based on a dynamic storage allocator. -Overflow does not occur until all available core storage -is exhausted. -.PP -The language has a complete control structure as well as immediate-mode -operation. Functions can be defined and saved for later execution. -.PP -Two five hundred-digit numbers can be multiplied to give a -thousand digit result in about ten seconds. -.PP -A small collection of library functions is also available, -including sin, cos, arctan, log, exponential, and Bessel functions of -integer order. -.PP -Some of the uses of this compiler are -.IP \- -to do computation with large integers, -.IP \- -to do computation accurate to many decimal places, -.IP \- -conversion of numbers from one base to another base. -.AE -.PP -.SH -Introduction -.PP -BC is a language and a compiler for doing arbitrary precision -arithmetic on the -.UX -time-sharing system [1]. -The compiler was written to make conveniently available a -collection of routines (called DC [5]) which are capable of doing -arithmetic on integers of arbitrary size. The compiler -is by no means intended to provide a complete programming -language. -It is a minimal language facility. -.PP -There is a scaling provision that permits the -use of decimal point notation. -Provision is made for input and output in bases other than -decimal. Numbers can be converted from decimal to octal by -simply setting the output base to equal 8. -.PP -The actual limit on the number of digits that can -be handled depends on the amount of storage available on the machine. -Manipulation of numbers with many hundreds of digits -is possible even on the smallest versions of -.UX . -.PP -The syntax of BC has been deliberately selected to agree -substantially with the C language [2]. Those who -are familiar with C will find few surprises in this language. -.SH -Simple Computations with Integers -.PP -The simplest kind of statement is an arithmetic expression -on a line by itself. -For instance, if you type in the line: -.DS -.ft B -142857 + 285714 -.ft P -.DE -the program responds immediately with the line -.DS -.ft B -428571 -.ft P -.DE -The operators \-, *, /, %, and ^ can also be used; they -indicate subtraction, multiplication, division, remaindering, and -exponentiation, respectively. Division of integers produces an -integer result truncated toward zero. -Division by zero produces an error -comment. -.PP -Any term in an expression may be prefixed by a minus sign to -indicate that it is to be negated (the `unary' minus sign). -The expression -.DS -.ft B -7+\-3 -.ft P -.DE -is interpreted to mean that \-3 is to be added to 7. -.PP -More complex expressions with several operators and with -parentheses are interpreted just as in -Fortran, with ^ having the greatest binding -power, then * and % and /, and finally + and \-. -Contents of parentheses are evaluated before material -outside the parentheses. -Exponentiations are -performed from right to left and the other operators -from left to right. -The two expressions -.DS -.ft B -a^b^c and a^(b^c) -.ft P -.DE -are equivalent, as are the two expressions -.DS -.ft B -a*b*c and (a*b)*c -.ft P -.DE -BC shares with Fortran and C the undesirable convention that -.DS -\fBa/b*c\fP is equivalent to \fB(a/b)*c\fP -.ft P -.DE -.PP -Internal storage registers to hold numbers have single lower-case -letter names. The value of an expression can be assigned to -a register in the usual way. The statement -.DS -.ft B -x = x + 3 -.ft P -.DE -has the effect of increasing by three the value of the contents of the -register named x. -When, as in this case, the outermost operator is an =, the -assignment is performed but the result is not printed. -Only 26 of these named storage registers are available. -.PP -There is a built-in square root function whose -result is truncated to an integer (but see scaling below). -The lines -.DS -.ft B -x = sqrt(191) -x -.ft P -.DE -produce the printed result -.DS -.ft B -13 -.ft P -.DE -.SH -Bases -.PP -There are special internal quantities, called `ibase' and `obase'. -The contents of `ibase', initially set to 10, -determines the base used for interpreting numbers read in. -For example, the lines -.DS -.ft B -ibase = 8 -11 -.ft P -.DE -will produce the output line -.DS -.ft B -9 -.ft P -.DE -and you are all set up to do octal to decimal conversions. -Beware, however of trying to change the input base back -to decimal by typing -.DS -.ft B -ibase = 10 -.ft P -.DE -Because the number 10 is interpreted as octal, this statement will -have no effect. -For those who deal in hexadecimal notation, -the characters A\-F are permitted in numbers -(no matter what base is in effect) -and are -interpreted as digits having values 10\-15 respectively. -The statement -.DS -.ft B -ibase = A -.ft P -.DE -will change you back to decimal input base no matter what the -current input base is. -Negative and large positive input bases are -permitted but useless. -No mechanism has been provided for the input of arbitrary -numbers in bases less than 1 and greater than 16. -.PP -The contents of `obase', initially set to 10, are used as the base for output -numbers. The lines -.DS -.ft B -obase = 16 -1000 -.ft P -.DE -will produce the output line -.DS -.ft B -3E8 -.ft P -.DE -which is to be interpreted as a 3-digit hexadecimal number. -Very large output bases are permitted, and they are sometimes useful. -For example, large numbers can be output in groups of five digits -by setting `obase' to 100000. -Strange (i.e. 1, 0, or negative) output bases are -handled appropriately. -.PP -Very large numbers are split across lines with 70 characters per line. -Lines which are continued end with \\. -Decimal output conversion is practically instantaneous, but output -of very large numbers (i.e., more than 100 digits) with other bases -is rather slow. -Non-decimal output conversion of -a one hundred digit number takes about -three seconds. -.PP -It is best to remember that `ibase' and `obase' have no effect -whatever on the course of internal computation or -on the evaluation of expressions, but only affect input and -output conversion, respectively. -.SH -Scaling -.PP -A third special internal quantity called `scale' is -used to determine the scale of calculated -quantities. -Numbers may have -up to a specific number of decimal digits after the decimal point. -This fractional part is retained in further computations. -We refer to the number of digits after the decimal point of -a number as its scale. -The current implementation allows scales to be as large as can be -represented by a 32-bit unsigned number minus one. -This is a non-portable extension. -The original implementation allowed for a maximum scale of 99. -.PP -When two scaled numbers are combined by -means of one of the arithmetic operations, the result -has a scale determined by the following rules. For -addition and subtraction, the scale of the result is the larger -of the scales of the two operands. In this case, -there is never any truncation of the result. -For multiplications, the scale of the result is never -less than the maximum of the two scales of the operands, -never more than the sum of the scales of the operands -and, subject to those two restrictions, -the scale of the result is set equal to the contents of the internal -quantity `scale'. -The scale of a quotient is the contents of the internal -quantity `scale'. The scale of a remainder is -the sum of the scales of the quotient and the divisor. -The result of an exponentiation is scaled as if -the implied multiplications were performed. -An exponent must be an integer. -The scale of a square root is set to the maximum of the scale -of the argument and the contents of `scale'. -.PP -All of the internal operations are actually carried out in terms -of integers, with digits being discarded when necessary. -In every case where digits are discarded, truncation and -not rounding is performed. -.PP -The contents of -`scale' must be no greater than -4294967294 and no less than 0. It is initially set to 0. -.PP -The internal quantities `scale', `ibase', and `obase' can be -used in expressions just like other variables. -The line -.DS -.ft B -scale = scale + 1 -.ft P -.DE -increases the value of `scale' by one, and the line -.DS -.ft B -scale -.ft P -.DE -causes the current value of `scale' to be printed. -.PP -The value of `scale' retains its meaning as a -number of decimal digits to be retained in internal -computation even when `ibase' or `obase' are not equal to 10. -The internal computations (which are still conducted in decimal, -regardless of the bases) are performed to the specified number -of decimal digits, never hexadecimal or octal or any -other kind of digits. -.SH -Functions -.PP -The name of a function is a single lower-case letter. -Function names are permitted to collide with simple -variable names. -Twenty-six different defined functions are permitted -in addition to the twenty-six variable names. -The line -.DS -.ft B - define a(x){ -.ft P -.DE -begins the definition of a function with one argument. -This line must be followed by one or more statements, -which make up the body of the function, ending -with a right brace }. -Return of control from a function occurs when a return -statement is executed or when the end of the function is reached. -The return statement can take either -of the two forms -.DS -.ft B -return -return(x) -.ft P -.DE -In the first case, the value of the function is 0, and in -the second, the value of the expression in parentheses. -.PP -Variables used in the function can be declared as automatic -by a statement of the form -.DS -.ft B -auto x,y,z -.ft P -.DE -There can be only one `auto' statement in a function and it must -be the first statement in the definition. -These automatic variables are allocated space and initialized -to zero on entry to the function and thrown away on return. The -values of any variables with the same names outside the function -are not disturbed. -Functions may be called recursively and the automatic variables -at each level of call are protected. -The parameters named in a function definition are treated in -the same way as the automatic variables of that function -with the single exception that they are given a value -on entry to the function. -An example of a function definition is -.DS -.ft B - define a(x,y){ - auto z - z = x*y - return(z) - } -.ft P -.DE -The value of this function, when called, will be the -product of its -two arguments. -.PP -A function is called by the appearance of its name -followed by a string of arguments enclosed in -parentheses and separated by commas. -The result -is unpredictable if the wrong number of arguments is used. -.PP -Functions with no arguments are defined and called using -parentheses with nothing between them: b(). -.PP -If the function -.ft I -a -.ft -above has been defined, then the line -.DS -.ft B -a(7,3.14) -.ft P -.DE -would cause the result 21.98 to be printed and the line -.DS -.ft B -x = a(a(3,4),5) -.ft P -.DE -would cause the value of x to become 60. -.SH -Subscripted Variables -.PP -A single lower-case letter variable name -followed by an expression in brackets is called a subscripted -variable (an array element). -The variable name is called the array name and the expression -in brackets is called the subscript. -Only one-dimensional arrays are -permitted. The names of arrays are permitted to -collide with the names of simple variables and function names. -Any fractional -part of a subscript is discarded before use. -Subscripts must be greater than or equal to zero and -less than or equal to 2047. -.PP -Subscripted variables may be freely used in expressions, in -function calls, and in return statements. -.PP -An array name may be used as an argument to a function, -or may be declared as automatic in -a function definition by the use of empty brackets: -.DS -.ft B -f(a[\|]) -define f(a[\|]) -auto a[\|] -.ft P -.DE -When an array name is so used, the whole contents of the array -are copied for the use of the function, and thrown away on exit -from the function. -Array names which refer to whole arrays cannot be used -in any other contexts. -.SH -Control Statements -.PP -The `if', the `while', and the `for' statements -may be used to alter the flow within programs or to cause iteration. -The range of each of them is a statement or -a compound statement consisting of a collection of -statements enclosed in braces. -They are written in the following way -.DS -.ft B -if(relation) statement -if(relation) statement else statement -while(relation) statement -for(expression1; relation; expression2) statement -.ft P -.DE -or -.DS -.ft B -if(relation) {statements} -if(relation) {statements} else {statements} -while(relation) {statements} -for(expression1; relation; expression2) {statements} -.ft P -.DE -.PP -A relation in one of the control statements is an expression of the form -.DS -.ft B -x>y -.ft P -.DE -where two expressions are related by one of the six relational -operators `<', `>', `<=', `>=', `==', or `!='. -The relation `==' -stands for `equal to' and `!=' stands for `not equal to'. -The meaning of the remaining relational operators is -clear. -.PP -BEWARE of using `=' instead of `==' in a relational. Unfortunately, -both of them are legal, so you will not get a diagnostic -message, but `=' really will not do a comparison. -.PP -The `if' statement causes execution of its range -if and only if the relation is true. -Then control passes to the next statement in sequence. -If an `else' branch is present, the statements in this branch are -executed if the relation is false. -The `else' keyword is a non-portable extension. -.PP -The `while' statement causes execution of its range -repeatedly as long as the relation -is true. The relation is tested before each execution -of its range and if the relation -is false, control passes to the next statement beyond the range -of the while. -.PP -The `for' statement begins -by executing `expression1'. Then the relation is tested -and, if true, the statements in the range of the `for' are executed. -Then `expression2' is executed. The relation is tested, and so on. -The typical use of the `for' statement is for a controlled iteration, -as in the statement -.DS -.ft B -for(i=1; i<=10; i=i+1) i -.ft P -.DE -which will print the integers from 1 to 10. -Here are some examples of the use of the control statements. -.DS -.ft B -define f(n){ -auto i, x -x=1 -for(i=1; i<=n; i=i+1) x=x*i -return(x) -} -.ft P -.DE -The line -.DS -.ft B - f(a) -.ft P -.DE -will print -.ft I -a -.ft -factorial if -.ft I -a -.ft -is a positive integer. -Here is the definition of a function which will -compute values of the binomial coefficient -(m and n are assumed to be positive integers). -.DS -.ft B -define b(n,m){ -auto x, j -x=1 -for(j=1; j<=m; j=j+1) x=x*(n\-j+1)/j -return(x) -} -.ft P -.DE -The following function computes values of the exponential function -by summing the appropriate series -without regard for possible truncation errors: -.DS -.ft B -scale = 20 -define e(x){ - auto a, b, c, d, n - a = 1 - b = 1 - c = 1 - d = 0 - n = 1 - while(1==1){ - a = a*x - b = b*n - c = c + a/b - n = n + 1 - if(c==d) return(c) - d = c - } -} -.ft P -.DE -.SH -Some Details -.PP -There are some language features that every user should know -about even if he will not use them. -.PP -Normally statements are typed one to a line. It is also permissible -to type several statements on a line separated by semicolons. -.PP -If an assignment statement is parenthesized, it then has -a value and it can be used anywhere that an expression can. -For example, the line -.DS -.ft B -(x=y+17) -.ft P -.DE -not only makes the indicated assignment, but also prints the -resulting value. -.PP -Here is an example of a use of the value of an -assignment statement even when it is not parenthesized. -.DS -.ft B -x = a[i=i+1] -.ft P -.DE -causes a value to be assigned to x and also increments i -before it is used as a subscript. -.PP -The following constructs work in BC in exactly the same manner -as they do in the C language. Consult the appendix or the -C manuals [2] for their exact workings. -.DS -.ft B -.ta 2i -x=y=z is the same as x=(y=z) -x += y x = x+y -x \-= y x = x\-y -x *= y x = x*y -x /= y x = x/y -x %= y x = x%y -x ^= y x = x^y -x++ (x=x+1)\-1 -x\-\- (x=x\-1)+1 -++x x = x+1 -\-\-x x = x\-1 -.ft P -.DE -Even if you don't intend to use the constructs, -if you type one inadvertently, something correct but unexpected -may happen. -.SH -Three Important Things -.PP -1. To exit a BC program, type `quit'. -.PP -2. There is a comment convention identical to that of C and -of PL/I. Comments begin with `/*' and end with `*/'. -As a non-portable extension, comments may also start with a `#' and end with -a newline. -The newline is not part of the comment. -.PP -3. There is a library of math functions which may be obtained by -typing at command level -.DS -.ft B -bc \-l -.ft P -.DE -This command will load a set of library functions -which, at the time of writing, consists of sine (named `s'), -cosine (`c'), arctangent (`a'), natural logarithm (`l'), -exponential (`e') and Bessel functions of integer order (`j(n,x)'). Doubtless more functions will be added -in time. -The library sets the scale to 20. You can reset it to something -else if you like. -The design of these mathematical library routines -is discussed elsewhere [3]. -.PP -If you type -.DS -.ft B -bc file ... -.ft P -.DE -BC will read and execute the named file or files before accepting -commands from the keyboard. In this way, you may load your -favorite programs and function definitions. -.SH -Acknowledgement -.PP -The compiler is written in YACC [4]; its original -version was written by S. C. Johnson. -.SH -References -.IP [1] -K. Thompson and D. M. Ritchie, -.ft I -UNIX Programmer's Manual, -.ft -Bell Laboratories, -1978. -.IP [2] -B. W. Kernighan and -D. M. Ritchie, -.ft I -The C Programming Language, -.ft -Prentice-Hall, 1978. -.IP [3] -R. Morris, -.ft I -A Library of Reference Standard Mathematical Subroutines, -.ft -Bell Laboratories internal memorandum, 1975. -.IP [4] -S. C. Johnson, -.ft I -YACC \(em Yet Another Compiler-Compiler. -.ft -Bell Laboratories Computing Science Technical Report #32, 1978. -.IP [5] -R. Morris and L. L. Cherry, -.ft I -DC \- An Interactive Desk Calculator. -.ft -.LP -.bp -.ft B -.DS C -Appendix -.DE -.ft -.NH -Notation -.PP -In the following pages syntactic categories are in \fIitalics\fP; -literals are in \fBbold\fP; material in brackets [\|] is optional. -.NH -Tokens -.PP -Tokens consist of keywords, identifiers, constants, operators, -and separators. -Token separators may be blanks, tabs or comments. -Newline characters or semicolons separate statements. -.NH 2 -Comments -.PP -Comments are introduced by the characters /* and terminated by -*/. -As a non-portable extension, comments may also start with a # and -end with a newline. -The newline is not part of the comment. -.NH 2 -Identifiers -.PP -There are three kinds of identifiers \- ordinary identifiers, array identifiers -and function identifiers. -All three types consist of single lower-case letters. -Array identifiers are followed by square brackets, possibly -enclosing an expression describing a subscript. -Arrays are singly dimensioned and may contain up to 2048 -elements. -Indexing begins at zero so an array may be indexed from 0 to 2047. -Subscripts are truncated to integers. -Function identifiers are followed by parentheses, possibly enclosing arguments. -The three types of identifiers do not conflict; -a program can have a variable named \fBx\fP, -an array named \fBx\fP and a function named \fBx\fP, all of which are separate and -distinct. -.NH 2 -Keywords -.PP -The following are reserved keywords: -.ft B -.ta .5i 1.0i -.nf - ibase if - obase break - scale define - sqrt auto - length return - while quit - for continue - else last - print -.fi -.ft -.NH 2 -Constants -.PP -Constants consist of arbitrarily long numbers -with an optional decimal point. -The hexadecimal digits \fBA\fP\-\fBF\fP are also recognized as digits with -values 10\-15, respectively. -.NH 1 -Expressions -.PP -The value of an expression is printed unless the main -operator is an assignment. -The value printed is assigned to the special variable \fBlast\fP. -A single dot may be used as a synonym for \fBlast\fP. -This is a non-portable extension. -Precedence is the same as the order -of presentation here, with highest appearing first. -Left or right associativity, where applicable, is -discussed with each operator. -.bp -.NH 2 -Primitive expressions -.NH 3 -Named expressions -.PP -Named expressions are -places where values are stored. -Simply stated, -named expressions are legal on the left -side of an assignment. -The value of a named expression is the value stored in the place named. -.NH 4 -\fIidentifiers\fR -.PP -Simple identifiers are named expressions. -They have an initial value of zero. -.NH 4 -\fIarray-name\fP\|[\|\fIexpression\fP\|] -.PP -Array elements are named expressions. -They have an initial value of zero. -.NH 4 -\fBscale\fR, \fBibase\fR and \fBobase\fR -.PP -The internal registers -\fBscale\fP, \fBibase\fP and \fBobase\fP are all named expressions. -\fBscale\fP is the number of digits after the decimal point to be -retained in arithmetic operations. -\fBscale\fR has an initial value of zero. -\fBibase\fP and \fBobase\fP are the input and output number -radix respectively. -Both \fBibase\fR and \fBobase\fR have initial values of 10. -.NH 3 -Function calls -.NH 4 -\fIfunction-name\fB\|(\fR[\fIexpression\fR\|[\fB,\|\fIexpression\|\fR.\|.\|.\|]\|]\fB) -.PP -A function call consists 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 is specified by the -array name followed by empty square brackets. -All function arguments are passed by -value. -As a result, changes made to the formal parameters have -no effect on the actual arguments. -If the function terminates by executing a return -statement, the value of the function is -the value of the expression in the parentheses of the return -statement or is zero if no expression is provided -or if there is no return statement. -.NH 4 -sqrt\|(\|\fIexpression\fP\|) -.PP -The result is the square root of the expression. -The result is truncated in the least significant decimal place. -The scale of the result is -the scale of the expression or the -value of -.ft B -scale, -.ft -whichever is larger. -.NH 4 -length\|(\|\fIexpression\fP\|) -.PP -The result is the total number of significant decimal digits in the expression. -The scale of the result is zero. -.NH 4 -scale\|(\|\fIexpression\fP\|) -.PP -The result is the scale of the expression. -The scale of the result is zero. -.NH 3 -Constants -.PP -Constants are primitive expressions. -.NH 3 -Parentheses -.PP -An expression surrounded by parentheses is -a primitive expression. -The parentheses are used to alter the -normal precedence. -.NH 2 -Unary operators -.PP -The unary operators -bind right to left. -.NH 3 -\-\|\fIexpression\fP -.PP -The result is the negative of the expression. -.NH 3 -++\|\fInamed-expression\fP -.PP -The named expression is -incremented by one. -The result is the value of the named expression after -incrementing. -.NH 3 -\-\-\|\fInamed-expression\fP -.PP -The named expression is -decremented by one. -The result is the value of the named expression after -decrementing. -.NH 3 -\fInamed-expression\fP\|++ -.PP -The named expression is -incremented by one. -The result is the value of the named expression before -incrementing. -.NH 3 -\fInamed-expression\fP\|\-\- -.PP -The named expression is -decremented by one. -The result is the value of the named expression before -decrementing. -.NH 2 -Exponentiation operator -.PP -The exponentiation operator binds right to left. -.NH 3 -\fIexpression\fP ^ \fIexpression\fP -.PP -The result is the first -expression raised to the power of the -second expression. -The second expression must be an integer. -If \fIa\fP -is the scale of the left expression -and \fIb\fP is the absolute value -of the right expression, -then the scale of the result is: -.PP -min\|(\|\fIa\(mub\fP,\|max\|(\|\fBscale\fP,\|\fIa\fP\|)\|) -.NH 2 -Multiplicative operators -.PP -The operators *, /, % bind left to right. -.NH 3 -\fIexpression\fP * \fIexpression\fP -.PP -The result is 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 is: -.PP -min\|(\|\fIa+b\fP,\|max\|(\|\fBscale\fP,\|\fIa\fP,\|\fIb\fP\|)\|) -.NH 3 -\fIexpression\fP / \fIexpression\fP -.PP -The result is the quotient of the two expressions. -The scale of the result is the value of \fBscale\fR. -.NH 3 -\fIexpression\fP % \fIexpression\fP -.PP -The % operator produces the remainder of the division -of the two expressions. -More precisely, -\fIa\fP%\fIb\fP is \fIa\fP\-\fIa\fP/\fIb\fP*\fIb\fP. -.PP -The scale of the result is the sum of the scale of -the divisor and the value of -.ft B -scale -.ft -.NH 2 -Additive operators -.PP -The additive operators bind left to right. -.NH 3 -\fIexpression\fP + \fIexpression\fP -.PP -The result is the sum of the two expressions. -The scale of the result is -the maximum of the scales of the expressions. -.NH 3 -\fIexpression\fP \- \fIexpression\fP -.PP -The result is the difference of the two expressions. -The scale of the result is the -maximum of the scales of the expressions. -.NH 2 -assignment operators -.PP -The assignment operators bind right to left. -.NH 3 -\fInamed-expression\fP = \fIexpression\fP -.PP -This expression results in assigning the value of the expression -on the right -to the named expression on the left. -.NH 3 -\fInamed-expression\fP += \fIexpression\fP -.NH 3 -\fInamed-expression\fP \-= \fIexpression\fP -.NH 3 -\fInamed-expression\fP *= \fIexpression\fP -.NH 3 -\fInamed-expression\fP /= \fIexpression\fP -.NH 3 -\fInamed-expression\fP %= \fIexpression\fP -.NH 3 -\fInamed-expression\fP ^= \fIexpression\fP -.PP -The result of the above expressions is equivalent -to ``named expression = named expression OP expression'', -where OP is the operator after the = sign. -.NH 1 -Relations -.PP -Unlike all other operators, the relational operators -are only valid as the object of an \fBif\fP, \fBwhile\fP, -or inside a \fBfor\fP statement. -.NH 2 -\fIexpression\fP < \fIexpression\fP -.NH 2 -\fIexpression\fP > \fIexpression\fP -.NH 2 -\fIexpression\fP <= \fIexpression\fP -.NH 2 -\fIexpression\fP >= \fIexpression\fP -.NH 2 -\fIexpression\fP == \fIexpression\fP -.NH 2 -\fIexpression\fP != \fIexpression\fP -.NH 1 -Storage classes -.PP -There are only two storage classes in BC, global and automatic -(local). -Only identifiers that are to be local to a function need be -declared with the \fBauto\fP command. -The arguments to a function -are 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 \fBauto\fP are allocated on entry to the function -and released on returning from the function. -They therefore do not retain values between function calls. -\fBauto\fP arrays are specified by the array name followed by empty square brackets. -.PP -Automatic variables in BC do not work in exactly the same way -as in either C or PL/I. On entry to a function, the old values of -the names that appear as parameters and as automatic -variables are pushed onto a stack. -Until return is made from the function, reference to these -names refers only to the new values. -.NH 1 -Statements -.PP -Statements must be separated by semicolon or newline. -Except where altered by control statements, execution -is sequential. -.NH 2 -Expression statements -.PP -When a statement is an expression, unless -the main operator is an assignment, the value -of the expression is printed, followed by a newline character. -.NH 2 -Compound statements -.PP -Statements may be grouped together and used when one statement is expected -by surrounding them with { }. -.NH 2 -Quoted string statements -.PP -"any string" -.sp .5 -This statement prints the string inside the quotes. -.NH 2 -If statements -.sp .5 -\fBif\|(\|\fIrelation\fB\|)\|\fIstatement\fR -.PP -The substatement is executed if the relation is true. -.NH 2 -If-else statements -.sp .5 -\fBif\|(\|\fIrelation\fB\|)\|\fIstatement\fB\|else\|\fIstatement\fR -.PP -The first substatement is executed if the relation is true, the second -substatement if the relation is false. -The \fBif-else\fR statement is a non-portable extension. -.NH 2 -While statements -.sp .5 -\fBwhile\|(\|\fIrelation\fB\|)\|\fIstatement\fR -.PP -The statement is executed while the relation -is true. -The test occurs before each execution of the statement. -.NH 2 -For statements -.sp .5 -\fBfor\|(\|\fIexpression\fB; \fIrelation\fB; \fIexpression\fB\|)\|\fIstatement\fR -.PP -The \fBfor\fR statement is the same as -.nf -.ft I - first-expression - \fBwhile\|(\fPrelation\|\fB) {\fP - statement - last-expression - } -.ft R -.fi -.PP -All three expressions may be left out. -This is a non-portable extension. -.NH 2 -Break statements -.sp .5 -\fBbreak\fP -.PP -\fBbreak\fP causes termination of a \fBfor\fP or \fBwhile\fP statement. -.NH 2 -Continue statements -.sp .5 -\fBcontinue\fP -.PP -\fBcontinue\fP causes the next iteration of a \fBfor\fP or \fBwhile\fP -statement to start, skipping the remainder of the loop. -For a \fBwhile\fP statement, execution continues with the evaluation -of the condition. -For a \fBfor\fP statement, execution continues with evaluation of -the last-expression. -The \fBcontinue\fP statement is a non-portable extension. -.NH 2 -Auto statements -.sp .5 -\fBauto \fIidentifier\fR\|[\|\fB,\fIidentifier\fR\|] -.PP -The \fBauto\fR statement causes the values of the identifiers to be pushed down. -The identifiers can be ordinary identifiers or array identifiers. -Array identifiers are specified by following the array name by empty square -brackets. -The auto statement must be the first statement -in a function definition. -.NH 2 -Define statements -.sp .5 -.nf -\fBdefine(\|\fR[\fIparameter\|\fR[\fB\|,\|\fIparameter\|.\|.\|.\|\fR]\|]\|\fB)\|{\fI - statements\|\fB}\fR -.fi -.PP -The \fBdefine\fR statement defines a function. -The parameters may -be ordinary identifiers or array names. -Array names must be followed by empty square brackets. -As a non-portable extension, the opening brace may also appear on the -next line. -.NH 2 -Return statements -.sp .5 -\fBreturn\fP -.sp .5 -\fBreturn(\fI\|expression\|\fB)\fR -.PP -The \fBreturn\fR statement causes termination of a function, -popping of its auto variables, and -specifies the result of the function. -The first form is equivalent to \fBreturn(0)\fR. -The result of the function is the result of the expression -in parentheses. -Leaving out the expression between parentheses is equivalent to -\fBreturn(0)\fR. -As a non-portable extension, the parentheses may be left out. -.NH 2 -Print -.PP -The \fBprint\fR statement takes a list of comma-separated expressions. -Each expression in the list is evaluated and the computed -value is printed and assigned to the variable `last'. -No trailing newline is printed. -The expression may also be a string enclosed in double quotes. -Within these strings the following escape sequences may be used: -\ea -for bell (alert), -`\eb' -for backspace, -`\ef' -for formfeed, -`\en' -for newline, -`\er' -for carriage return, -`\et' -`for tab, -`\eq' -for double quote and -`\e\e' -for backslash. -Any other character following a backslash will be ignored. -Strings will not be assigned to `last'. -The \fBprint\fR statement is a non-portable extension. -.NH 2 -Quit -.PP -The \fBquit\fR statement stops execution of a BC program and returns -control to UNIX when it is first encountered. -Because it is not treated as an executable statement, -it cannot be used -in a function definition or in an -.ft B -if, for, -.ft -or -.ft B -while -.ft -statement. diff --git a/usr.bin/dc/USD.doc/dc b/usr.bin/dc/USD.doc/dc deleted file mode 100644 index 4caa0f4..0000000 --- a/usr.bin/dc/USD.doc/dc +++ /dev/null @@ -1,753 +0,0 @@ -.\" $FreeBSD$ -.\" $OpenBSD: dc,v 1.2 2003/09/22 19:08:27 otto Exp $ -.\" -.\" Copyright (C) Caldera International Inc. 2001-2002. -.\" All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code and documentation must retain the above -.\" copyright notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed or owned by Caldera -.\" International, Inc. -.\" 4. Neither the name of Caldera International, Inc. nor the names of other -.\" contributors may be used to endorse or promote products derived from -.\" this software without specific prior written permission. -.\" -.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA -.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES -.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. -.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT, -.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, -.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING -.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -.\" POSSIBILITY OF SUCH DAMAGE. -.\" -.\" @(#)dc 8.1 (Berkeley) 6/8/93 -.\" -.EH 'USD:5-%''DC \- An Interactive Desk Calculator' -.OH 'DC \- An Interactive Desk Calculator''USD:5-%' -.\".RP -.\" ....TM 75-1271-8 39199 39199-11 -.ND -.TL -DC \- An Interactive Desk Calculator -.AU "MH 2C-524" 3878 -Robert Morris -.AU -Lorinda Cherry -.AI -.\" .MH -.AB -DC is an interactive desk calculator program implemented -on the -.UX -time-sharing system to do arbitrary-precision -integer arithmetic. -It has provision for manipulating scaled fixed-point numbers and -for input and output in bases other than decimal. -.PP -The size of numbers that can be manipulated is limited -only by available core storage. -On typical implementations of -.UX , -the size of numbers that -can be handled varies from several hundred digits on the smallest -systems to several thousand on the largest. -.AE -.PP -.SH -.PP -.ft I -Editor's note: the description of the implementation details of DC in this -paper is only valid for the original version of DC. -The current version of DC uses a different approach. -.ft -.PP -DC is an arbitrary precision arithmetic package implemented -on the -.UX -time-sharing system -in the form of an interactive desk calculator. -It works like a stacking calculator using reverse Polish notation. -Ordinarily DC operates on decimal integers, but one may -specify an input base, output base, and a number of fractional -digits to be maintained. -.PP -A language called BC [1] has been developed which accepts -programs written in the familiar style of higher-level -programming languages and compiles output which is -interpreted by DC. -Some of the commands described below were designed -for the compiler interface and are not easy for a human user -to manipulate. -.PP -Numbers that are typed into DC are put on a push-down -stack. -DC commands work by taking the top number or two -off the stack, performing the desired operation, and pushing the result -on the stack. -If an argument is given, -input is taken from that file until its end, -then from the standard input. -.SH -SYNOPTIC DESCRIPTION -.PP -Here we describe the DC commands that are intended -for use by people. The additional commands that are -intended to be invoked by compiled output are -described in the detailed description. -.PP -Any number of commands are permitted on a line. -Blanks and new-line characters are ignored except within numbers -and in places where a register name is expected. -.PP -The following constructions are recognized: -.SH -number -.IP -The value of the number is pushed onto the main stack. -A number is an unbroken string of the digits 0-9 -and the capital letters A\-F which are treated as digits -with values 10\-15 respectively. -The number may be preceded by an underscore _ to input a -negative number. -Numbers may contain decimal points. -.SH -+ \- * % ^ -.IP -The -top two values on the stack are added -(\fB+\fP), -subtracted -(\fB\-\fP), -multiplied (\fB*\fP), -divided (\fB/\fP), -remaindered (\fB%\fP), -or exponentiated (^). -The two entries are popped off the stack; -the result is pushed on the stack in their place. -The result of a division is an integer truncated toward zero. -See the detailed description below for the treatment of -numbers with decimal points. -An exponent must not have any digits after the decimal point. -.SH -s\fIx\fP -.IP -The -top of the main stack is popped and stored into -a register named \fIx\fP, where \fIx\fP may be any character. -If -the -.ft B -s -.ft -is capitalized, -.ft I -x -.ft -is treated as a stack and the value is pushed onto it. -Any character, even blank or new-line, is a valid register name. -.SH -l\fIx\fP -.IP -The -value in register -.ft I -x -.ft -is pushed onto the stack. -The register -.ft I -x -.ft -is not altered. -If the -.ft B -l -.ft -is capitalized, -register -.ft I -x -.ft -is treated as a stack and its top value is popped onto the main stack. -.LP -All registers start with empty value which is treated as a zero -by the command \fBl\fP and is treated as an error by the command \fBL\fP. -.SH -d -.IP -The -top value on the stack is duplicated. -.SH -p -.IP -The top value on the stack is printed. -The top value remains unchanged. -.SH -f -.IP -All values on the stack and in registers are printed. -.SH -x -.IP -treats the top element of the stack as a character string, -removes it from the stack, and -executes it as a string of DC commands. -.SH -[ ... ] -.IP -puts the bracketed character string onto the top of the stack. -.SH -q -.IP -exits the program. -If executing a string, the recursion level is -popped by two. -If -.ft B -q -.ft -is capitalized, -the top value on the stack is popped and the string execution level is popped -by that value. -.SH -<\fIx\fP >\fIx\fP =\fIx\fP !<\fIx\fP !>\fIx\fP !=\fIx\fP -.IP -The -top two elements of the stack are popped and compared. -Register -.ft I -x -.ft -is executed if they obey the stated -relation. -Exclamation point is negation. -.SH -v -.IP -replaces the top element on the stack by its square root. -The square root of an integer is truncated to an integer. -For the treatment of numbers with decimal points, see -the detailed description below. -.SH -! -.IP -interprets the rest of the line as a -.UX -command. -Control returns to DC when the -.UX -command terminates. -.SH -c -.IP -All values on the stack are popped; the stack becomes empty. -.SH -i -.IP -The top value on the stack is popped and used as the -number radix for further input. -If \fBi\fP is capitalized, the value of -the input base is pushed onto the stack. -No mechanism has been provided for the input of arbitrary -numbers in bases less than 1 or greater than 16. -.SH -o -.IP -The top value on the stack is popped and used as the -number radix for further output. -If \fBo\fP is capitalized, the value of the output -base is pushed onto the stack. -.SH -k -.IP -The top of the stack is popped, and that value is used as -a scale factor -that influences the number of decimal places -that are maintained during multiplication, division, and exponentiation. -The scale factor must be greater than or equal to zero and -less than 100. -If \fBk\fP is capitalized, the value of the scale factor -is pushed onto the stack. -.SH -z -.IP -The value of the stack level is pushed onto the stack. -.SH -? -.IP -A line of input is taken from the input source (usually the console) -and executed. -.SH -DETAILED DESCRIPTION -.SH -Internal Representation of Numbers -.PP -Numbers are stored internally using a dynamic storage allocator. -Numbers are kept in the form of a string -of digits to the base 100 stored one digit per byte -(centennial digits). -The string is stored with the low-order digit at the -beginning of the string. -For example, the representation of 157 -is 57,1. -After any arithmetic operation on a number, care is taken -that all digits are in the range 0\-99 and that -the number has no leading zeros. -The number zero is represented by the empty string. -.PP -Negative numbers are represented in the 100's complement -notation, which is analogous to two's complement notation for binary -numbers. -The high order digit of a negative number is always \-1 -and all other digits are in the range 0\-99. -The digit preceding the high order \-1 digit is never a 99. -The representation of \-157 is 43,98,\-1. -We shall call this the canonical form of a number. -The advantage of this kind of representation of negative -numbers is ease of addition. When addition is performed digit -by digit, the result is formally correct. The result need only -be modified, if necessary, to put it into canonical form. -.PP -Because the largest valid digit is 99 and the byte can -hold numbers twice that large, addition can be carried out -and the handling of carries done later when -that is convenient, as it sometimes is. -.PP -An additional byte is stored with each number beyond -the high order digit to indicate the number of -assumed decimal digits after the decimal point. The representation -of .001 is 1,\fI3\fP -where the scale has been italicized to emphasize the fact that it -is not the high order digit. -The value of this extra byte is called the -.ft B -scale factor -.ft -of the number. -.SH -The Allocator -.PP -DC uses a dynamic string storage allocator -for all of its internal storage. -All reading and writing of numbers internally is done through -the allocator. -Associated with each string in the allocator is a four-word header containing pointers -to the beginning of the string, the end of the string, -the next place to write, and the next place to read. -Communication between the allocator and DC -is done via pointers to these headers. -.PP -The allocator initially has one large string on a list -of free strings. All headers except the one pointing -to this string are on a list of free headers. -Requests for strings are made by size. -The size of the string actually supplied is the next higher -power of 2. -When a request for a string is made, the allocator -first checks the free list to see if there is -a string of the desired size. -If none is found, the allocator finds the next larger free string and splits it repeatedly until -it has a string of the right size. -Left-over strings are put on the free list. -If there are no larger strings, -the allocator tries to coalesce smaller free strings into -larger ones. -Since all strings are the result -of splitting large strings, -each string has a neighbor that is next to it in core -and, if free, can be combined with it to make a string twice as long. -This is an implementation of the `buddy system' of allocation -described in [2]. -.PP -Failing to find a string of the proper length after coalescing, -the allocator asks the system for more space. -The amount of space on the system is the only limitation -on the size and number of strings in DC. -If at any time in the process of trying to allocate a string, the allocator runs out of -headers, it also asks the system for more space. -.PP -There are routines in the allocator for reading, writing, copying, rewinding, -forward-spacing, and backspacing strings. -All string manipulation is done using these routines. -.PP -The reading and writing routines -increment the read pointer or write pointer so that -the characters of a string are read or written in -succession by a series of read or write calls. -The write pointer is interpreted as the end of the -information-containing portion of a string and a call -to read beyond that point returns an end-of-string indication. -An attempt to write beyond the end of a string -causes the allocator to -allocate a larger space and then copy -the old string into the larger block. -.SH -Internal Arithmetic -.PP -All arithmetic operations are done on integers. -The operands (or operand) needed for the operation are popped -from the main stack and their scale factors stripped off. -Zeros are added or digits removed as necessary to get -a properly scaled result from the internal arithmetic routine. -For example, if the scale of the operands is different and decimal -alignment is required, as it is for -addition, zeros are appended to the operand with the smaller -scale. -After performing the required arithmetic operation, -the proper scale factor is appended to the end of the number before -it is pushed on the stack. -.PP -A register called \fBscale\fP plays a part -in the results of most arithmetic operations. -\fBscale\fP is the bound on the number of decimal places retained in -arithmetic computations. -\fBscale\fP may be set to the number on the top of the stack -truncated to an integer with the \fBk\fP command. -\fBK\fP may be used to push the value of \fBscale\fP on the stack. -\fBscale\fP must be greater than or equal to 0 and less than 100. -The descriptions of the individual arithmetic operations will -include the exact effect of \fBscale\fP on the computations. -.SH -Addition and Subtraction -.PP -The scales of the two numbers are compared and trailing -zeros are supplied to the number with the lower scale to give both -numbers the same scale. The number with the smaller scale is -multiplied by 10 if the difference of the scales is odd. -The scale of the result is then set to the larger of the scales -of the two operands. -.PP -Subtraction is performed by negating the number -to be subtracted and proceeding as in addition. -.PP -Finally, the addition is performed digit by digit from the -low order end of the number. The carries are propagated -in the usual way. -The resulting number is brought into canonical form, which may -require stripping of leading zeros, or for negative numbers -replacing the high-order configuration 99,\-1 by the digit \-1. -In any case, digits which are not in the range 0\-99 must -be brought into that range, propagating any carries or borrows -that result. -.SH -Multiplication -.PP -The scales are removed from the two operands and saved. -The operands are both made positive. -Then multiplication is performed in -a digit by digit manner that exactly mimics the hand method -of multiplying. -The first number is multiplied by each digit of the second -number, beginning with its low order digit. The intermediate -products are accumulated into a partial sum which becomes the -final product. -The product is put into the canonical form and its sign is -computed from the signs of the original operands. -.PP -The scale of the result is set equal to the sum -of the scales of the two operands. -If that scale is larger than the internal register -.ft B -scale -.ft -and also larger than both of the scales of the two operands, -then the scale of the result is set equal to the largest -of these three last quantities. -.SH -Division -.PP -The scales are removed from the two operands. -Zeros are appended or digits removed from the dividend to make -the scale of the result of the integer division equal to -the internal quantity -\fBscale\fP. -The signs are removed and saved. -.PP -Division is performed much as it would be done by hand. -The difference of the lengths of the two numbers -is computed. -If the divisor is longer than the dividend, -zero is returned. -Otherwise the top digit of the divisor is divided into the top -two digits of the dividend. -The result is used as the first (high-order) digit of the -quotient. -It may turn out be one unit too low, but if it is, the next -trial quotient will be larger than 99 and this will be -adjusted at the end of the process. -The trial digit is multiplied by the divisor and the result subtracted -from the dividend and the process is repeated to get -additional quotient digits until the remaining -dividend is smaller than the divisor. -At the end, the digits of the quotient are put into -the canonical form, with propagation of carry as needed. -The sign is set from the sign of the operands. -.SH -Remainder -.PP -The division routine is called and division is performed -exactly as described. The quantity returned is the remains of the -dividend at the end of the divide process. -Since division truncates toward zero, remainders have the same -sign as the dividend. -The scale of the remainder is set to -the maximum of the scale of the dividend and -the scale of the quotient plus the scale of the divisor. -.SH -Square Root -.PP -The scale is stripped from the operand. -Zeros are added if necessary to make the -integer result have a scale that is the larger of -the internal quantity -\fBscale\fP -and the scale of the operand. -.PP -The method used to compute sqrt(y) is Newton's method -with successive approximations by the rule -.EQ -x sub {n+1} ~=~ half ( x sub n + y over x sub n ) -.EN -The initial guess is found by taking the integer square root -of the top two digits. -.SH -Exponentiation -.PP -Only exponents with zero scale factor are handled. If the exponent is -zero, then the result is 1. If the exponent is negative, then -it is made positive and the base is divided into one. The scale -of the base is removed. -.PP -The integer exponent is viewed as a binary number. -The base is repeatedly squared and the result is -obtained as a product of those powers of the base that -correspond to the positions of the one-bits in the binary -representation of the exponent. -Enough digits of the result -are removed to make the scale of the result the same as if the -indicated multiplication had been performed. -.SH -Input Conversion and Base -.PP -Numbers are converted to the internal representation as they are read -in. -The scale stored with a number is simply the number of fractional digits input. -Negative numbers are indicated by preceding the number with a \fB\_\fP (an -underscore). -The hexadecimal digits A\-F correspond to the numbers 10\-15 regardless of input base. -The \fBi\fP command can be used to change the base of the input numbers. -This command pops the stack, truncates the resulting number to an integer, -and uses it as the input base for all further input. -The input base is initialized to 10 but may, for example be changed to -8 or 16 to do octal or hexadecimal to decimal conversions. -The command \fBI\fP will push the value of the input base on the stack. -.SH -Output Commands -.PP -The command \fBp\fP causes the top of the stack to be printed. -It does not remove the top of the stack. -All of the stack and internal registers can be output -by typing the command \fBf\fP. -The \fBo\fP command can be used to change the output base. -This command uses the top of the stack, truncated to an integer as -the base for all further output. -The output base in initialized to 10. -It will work correctly for any base. -The command \fBO\fP pushes the value of the output base on the stack. -.SH -Output Format and Base -.PP -The input and output bases only affect -the interpretation of numbers on input and output; they have no -effect on arithmetic computations. -Large numbers are output with 70 characters per line; -a \\ indicates a continued line. -All choices of input and output bases work correctly, although not all are -useful. -A particularly useful output base is 100000, which has the effect of -grouping digits in fives. -Bases of 8 and 16 can be used for decimal-octal or decimal-hexadecimal -conversions. -.SH -Internal Registers -.PP -Numbers or strings may be stored in internal registers or loaded on the stack -from registers with the commands \fBs\fP and \fBl\fP. -The command \fBs\fIx\fR pops the top of the stack and -stores the result in register \fBx\fP. -\fIx\fP can be any character. -\fBl\fIx\fR puts the contents of register \fBx\fP on the top of the stack. -The \fBl\fP command has no effect on the contents of register \fIx\fP. -The \fBs\fP command, however, is destructive. -.SH -Stack Commands -.PP -The command \fBc\fP clears the stack. -The command \fBd\fP pushes a duplicate of the number on the top of the stack -on the stack. -The command \fBz\fP pushes the stack size on the stack. -The command \fBX\fP replaces the number on the top of the stack -with its scale factor. -The command \fBZ\fP replaces the top of the stack -with its length. -.SH -Subroutine Definitions and Calls -.PP -Enclosing a string in \fB[ ]\fP pushes the ascii string on the stack. -The \fBq\fP command quits or in executing a string, pops the recursion levels by two. -.SH -Internal Registers \- Programming DC -.PP -The load and store -commands together with \fB[ ]\fP to store strings, \fBx\fP to execute -and the testing commands `<', `>', `=', `!<', `!>', `!=' can be used to program -DC. -The \fBx\fP command assumes the top of the stack is an string of DC commands -and executes it. -The testing commands compare the top two elements on the stack and if the relation holds, execute the register -that follows the relation. -For example, to print the numbers 0-9, -.DS -[lip1+ si li10>a]sa -0si lax -.DE -.SH -Push-Down Registers and Arrays -.PP -These commands were designed for used by a compiler, not by -people. -They involve push-down registers and arrays. -In addition to the stack that commands work on, DC can be thought -of as having individual stacks for each register. -These registers are operated on by the commands \fBS\fP and \fBL\fP. -\fBS\fIx\fR pushes the top value of the main stack onto the stack for -the register \fIx\fP. -\fBL\fIx\fR pops the stack for register \fIx\fP and puts the result on the main -stack. -The commands \fBs\fP and \fBl\fP also work on registers but not as push-down -stacks. -\fBl\fP doesn't effect the top of the -register stack, and \fBs\fP destroys what was there before. -.PP -The commands to work on arrays are \fB:\fP and \fB;\fP. -\fB:\fIx\fR pops the stack and uses this value as an index into -the array \fIx\fP. -The next element on the stack is stored at this index in \fIx\fP. -An index must be greater than or equal to 0 and -less than 2048. -\fB;\fIx\fR is the command to load the main stack from the array \fIx\fP. -The value on the top of the stack is the index -into the array \fIx\fP of the value to be loaded. -.SH -Miscellaneous Commands -.PP -The command \fB!\fP interprets the rest of the line as a -.UX -command and passes it to -.UX -to execute. -One other compiler command is \fBQ\fP. -This command uses the top of the stack as the number of levels of recursion to skip. -.SH -DESIGN CHOICES -.PP -The real reason for the use of a dynamic storage allocator was -that a general purpose program could be (and in fact has been) -used for a variety of other tasks. -The allocator has some value for input and for compiling (i.e. -the bracket [...] commands) where it cannot be known in advance -how long a string will be. -The result was that at a modest -cost in execution time, all considerations of string allocation -and sizes of strings were removed from the remainder of the program -and debugging was made easier. The allocation method -used wastes approximately 25% of available space. -.PP -The choice of 100 as a base for internal arithmetic -seemingly has no compelling advantage. Yet the base cannot -exceed 127 because of hardware limitations and at the cost -of 5% in space, debugging was made a great deal easier and -decimal output was made much faster. -.PP -The reason for a stack-type arithmetic design was -to permit all DC commands from addition to subroutine execution -to be implemented in essentially the same way. The result -was a considerable degree of logical separation of the final -program into modules with very little communication between -modules. -.PP -The rationale for the lack of interaction between the scale and the bases -was to provide an understandable means of proceeding after -a change of base or scale when numbers had already been entered. -An earlier implementation which had global notions of -scale and base did not work out well. -If the value of -.ft B -scale -.ft -were to be interpreted in the current -input or output base, -then a change of base or scale in the midst of a -computation would cause great confusion in the interpretation -of the results. -The current scheme has the advantage that the value of -the input and output bases -are only used for input and output, respectively, and they -are ignored in all other operations. -The value of -scale -is not used for any essential purpose by any part of the program -and it is used only to prevent the number of -decimal places resulting from the arithmetic operations from -growing beyond all bounds. -.PP -The design rationale for the choices for the scales of -the results of arithmetic were that in no case should -any significant digits be thrown away if, on appearances, the -user actually wanted them. Thus, if the user wants -to add the numbers 1.5 and 3.517, it seemed reasonable to give -him the result 5.017 without requiring him to unnecessarily -specify his rather obvious requirements for precision. -.PP -On the other hand, multiplication and exponentiation produce -results with many more digits than their operands and it -seemed reasonable to give as a minimum the number of decimal -places in the operands but not to give more than that -number of digits -unless the user asked for them by specifying a value for \fBscale\fP. -Square root can be handled in just the same way as multiplication. -The operation of division gives arbitrarily many decimal places -and there is simply no way to guess how many places the user -wants. -In this case only, the user must -specify a \fBscale\fP to get any decimal places at all. -.PP -The scale of remainder was chosen to make it possible -to recreate the dividend from the quotient and remainder. -This is easy to implement; no digits are thrown away. -.SH -References -.IP [1] -L. L. Cherry, R. Morris, -.ft I -BC \- An Arbitrary Precision Desk-Calculator Language. -.ft -.IP [2] -K. C. Knowlton, -.ft I -A Fast Storage Allocator, -.ft -Comm. ACM \fB8\fP, pp. 623-625 (Oct. 1965). diff --git a/usr.bin/gprof/PSD.doc/abstract.me b/usr.bin/gprof/PSD.doc/abstract.me deleted file mode 100644 index 28e8066..0000000 --- a/usr.bin/gprof/PSD.doc/abstract.me +++ /dev/null @@ -1,66 +0,0 @@ -.\" Copyright (c) 1982, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)abstract.me 8.1 (Berkeley) 6/8/93 -.\" -.sp 1 -\fB\s+2gprof: a Call Graph Execution Profiler\s-2\fP\** -.(f -\**This work was supported by grant MCS80-05144 -from the National Science Foundation. -.)f -.sp 1 -by -\fISusan L. Graham\fP -\fIPeter B. Kessler\fP -\fIMarshall K. McKusick\fP -.sp 1 -Computer Science Division -Electrical Engineering and Computer Science Department -University of California, Berkeley -Berkeley, California 94720 -.ce 0 -.sp 1 -.sp 0.5i -.sh 0 "Abstract" -.pp -Large complex programs are composed of many small routines -that implement abstractions for the routines that call them. -To be useful, an execution profiler must attribute -execution time in a way that is significant for the -logical structure of a program -as well as for its textual decomposition. -This data must then be displayed to the user -in a convenient and informative way. -The \fBgprof\fP profiler -accounts for the running time of called routines -in the running time of the routines that call them. -The design and use of this profiler is described. diff --git a/usr.bin/gprof/PSD.doc/gathering.me b/usr.bin/gprof/PSD.doc/gathering.me deleted file mode 100644 index 17130c3..0000000 --- a/usr.bin/gprof/PSD.doc/gathering.me +++ /dev/null @@ -1,231 +0,0 @@ -.\" Copyright (c) 1982, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)gathering.me 8.1 (Berkeley) 6/8/93 -.\" -.sh 1 "Gathering Profile Data" -.pp -Routine calls or statement executions can be measured by having a -compiler augment the code at strategic points. -The additions can be inline increments to counters [Knuth71] -[Satterthwaite72] [Joy79] or calls to -monitoring routines [Unix]. -The counter increment overhead is low, and is suitable for -profiling statements. -A call of the monitoring routine has an overhead comparable with a -call of a regular routine, and is therefore only suited -to profiling on a routine by routine basis. -However, the monitoring routine solution has certain advantages. -Whatever counters are needed by the monitoring routine can be -managed by the monitoring routine itself, rather than being -distributed around the code. -In particular, a monitoring routine can easily be called from separately -compiled programs. -In addition, different monitoring routines can be linked into the -program -being measured -to assemble different profiling data without having to -change the compiler or recompile the program. -We have exploited this approach; -our compilers for C, Fortran77, and Pascal can insert calls to a -monitoring routine in the prologue for each routine. -Use of the monitoring routine requires no planning on part of a -programmer other than to request that augmented routine -prologues be produced during compilation. -.pp -We are interested in gathering three pieces of information during -program execution: call counts and execution times for -each profiled routine, and the arcs of the dynamic call graph -traversed by this execution of the program. -By post-processing of this data we can build the dynamic call -graph for this execution of the program and propagate times along -the edges of this graph to attribute times for routines to the -routines that invoke them. -.pp -Gathering of the profiling information should not greatly -interfere with the running of the program. -Thus, the monitoring routine must not produce trace output each -time it is invoked. -The volume of data thus produced would be unmanageably large, -and the time required to record it would overwhelm the running -time of most programs. -Similarly, the monitoring routine can not do the analysis of -the profiling data (e.g. assembling the call graph, propagating -times around it, discovering cycles, etc.) during program -execution. -Our solution is to gather profiling data in memory during program -execution and to condense it to a file as the profiled -program exits. -This file is then processed by a separate program to produce the -listing of the profile data. -An advantage of this approach is that the profile data for -several executions of a program can be combined by the -post-processing to provide a profile of many -executions. -.pp -The execution time monitoring consists of three parts. -The first part allocates and initializes the runtime monitoring data -structures before the program begins execution. -The second part is the monitoring routine invoked from the -prologue of each profiled routine. -The third part condenses the data structures and writes them -to a file as the program terminates. -The monitoring routine is discussed in detail in the following sections. -.sh 2 "Execution Counts" -.pp -The \fBgprof\fP monitoring routine counts the number of times -each profiled routine is called. -The monitoring routine also records the arc in the call graph -that activated the profiled routine. -The count is associated with the arc in the call graph -rather than with the routine. -Call counts for routines can then be determined by summing the counts -on arcs directed into that routine. -In a machine-dependent fashion, the monitoring routine notes its -own return address. -This address is in the prologue of some profiled routine that is -the destination of an arc in the dynamic call graph. -The monitoring routine also discovers the return address for that -routine, thus identifying the call site, or source of the arc. -The source of the arc is in the \fIcaller\fP, and the destination is in -the \fIcallee\fP. -For example, if a routine A calls a routine B, A is the caller, -and B is the callee. -The prologue of B will include a call to the monitoring routine -that will note the arc from A to B and either initialize or -increment a counter for that arc. -.pp -One can not afford to have the monitoring routine output tracing -information as each arc is identified. -Therefore, the monitoring routine maintains a table of all the -arcs discovered, with counts of the numbers of times each is -traversed during execution. -This table is accessed once per routine call. -Access to it -must be as fast as possible so as not to overwhelm the time -required to execute the program. -.pp -Our solution is to access the table through a hash table. -We use the call site as the primary key with the callee -address being the secondary key. -Since each call site typically calls only one callee, we can -reduce (usually to one) the number of minor lookups based on the callee. -Another alternative would use the callee as the primary key and the -call site as the secondary key. -Such an organization has the advantage of associating callers with -callees, at the expense of longer lookups in the monitoring -routine. -We are fortunate to be running in a virtual memory environment, -and (for the sake of speed) were able to allocate enough space -for the primary hash table to allow a one-to-one mapping from -call site addresses to the primary hash table. -Thus our hash function is trivial to calculate and collisions -occur only for call sites that call multiple -destinations (e.g. functional parameters and functional variables). -A one level hash function using both call site and callee would -result in an unreasonably large hash table. -Further, the number of dynamic call sites and callees is not known during -execution of the profiled program. -.pp -Not all callers and callees can be identified by the monitoring -routine. -Routines that were compiled without the profiling augmentations -will not call the monitoring routine as part of their prologue, -and thus no arcs will be recorded whose destinations are in these -routines. -One need not profile all the routines in a program. -Routines that are not profiled run at full speed. -Certain routines, notably exception handlers, are invoked by -non-standard calling sequences. -Thus the monitoring routine may know the destination of an arc -(the callee), -but find it difficult or -impossible to determine the source of the arc (the caller). -Often in these cases the apparent source of the arc is not a call -site at all. -Such anomalous invocations are declared ``spontaneous''. -.sh 2 "Execution Times" -.pp -The execution times for routines can be gathered in at least two -ways. -One method measures the execution time of a routine by measuring -the elapsed time from routine entry to routine exit. -Unfortunately, time measurement is complicated on time-sharing -systems by the time-slicing of the program. -A second method samples the value of the program counter at some -interval, and infers execution time from the distribution of the -samples within the program. -This technique is particularly suited to time-sharing systems, -where the time-slicing can serve as the basis for sampling -the program counter. -Notice that, whereas the first method could provide exact timings, -the second is inherently a statistical approximation. -.pp -The sampling method need not require support from the operating -system: all that is needed is the ability to set and respond to -``alarm clock'' interrupts that run relative to program time. -It is imperative that the intervals be uniform since the -sampling of the program counter rather than the duration of the -interval is the basis of the distribution. -If sampling is done too often, the interruptions to sample the -program counter will overwhelm the running of the profiled program. -On the other hand, the program must run for enough sampled -intervals that the distribution of the samples accurately -represents the distribution of time for the execution of the -program. -As with routine call tracing, the monitoring routine can not -afford to output information for each program counter -sample. -In our computing environment, the operating system can provide a -histogram of the location of the program counter at the end of -each clock tick (1/60th of a second) in which a program runs. -The histogram is assembled in memory as the program runs. -This facility is enabled by our monitoring routine. -We have adjusted the granularity of the histogram so that -program counter values map one-to-one onto the histogram. -We make the simplifying assumption that all calls to a specific -routine require the same amount of time to execute. -This assumption may disguise that some calls -(or worse, some call sites) always invoke a routine -such that its execution is faster (or slower) -than the average time for that routine. -.pp -When the profiled program terminates, -the arc table and the histogram of -program counter samples is written to a file. -The arc table is condensed to consist of the source and destination -addresses of the arc and the count of the number of times the arc -was traversed by this execution of the program. -The recorded histogram consists of counters of the number of -times the program counter was found to be in each of the ranges covered -by the histogram. -The ranges themselves are summarized as a -lower and upper bound and a step size. diff --git a/usr.bin/gprof/PSD.doc/header.me b/usr.bin/gprof/PSD.doc/header.me deleted file mode 100644 index aef606d..0000000 --- a/usr.bin/gprof/PSD.doc/header.me +++ /dev/null @@ -1,38 +0,0 @@ -.\" Copyright (c) 1982, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)header.me 8.1 (Berkeley) 8/14/93 -.\" -.\"he 'gprof''Graham, Kessler, McKusick' -.\"fo 'Draft of \*(td''%' -.\"ls 2 -.eh 'PSD:18-%''gprof \*- a Call Graph Execution Profiler' -.oh 'gprof \*- A Call Graph Execution Profiler''PSD:18-%' diff --git a/usr.bin/gprof/PSD.doc/intro.me b/usr.bin/gprof/PSD.doc/intro.me deleted file mode 100644 index 3a872b2..0000000 --- a/usr.bin/gprof/PSD.doc/intro.me +++ /dev/null @@ -1,81 +0,0 @@ -.\" Copyright (c) 1982, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)intro.me 8.1 (Berkeley) 6/8/93 -.\" -.sh 1 "Programs to be Profiled" -.pp -Software research environments -normally include many large programs -both for production use and for experimental investigation. -These programs are typically modular, -in accordance with generally accepted principles -of good program design. -Often they consist of numerous small routines -that implement various abstractions. -Sometimes such large programs are written -by one programmer -who has understood the requirements for -these abstractions, and has programmed them -appropriately. -More frequently the program has -had multiple authors and has -evolved over time, changing the demands placed -on the implementation of the abstractions without -changing the implementation itself. -Finally, the program may be assembled from a library -of abstraction implementations -unexamined by the programmer. -.pp -Once a large program is executable, -it is often desirable to increase its speed, -especially if small portions of the program -are found to dominate its execution time. -The purpose of the \fBgprof\fP profiling tool is to -help the user evaluate alternative implementations -of abstractions. -We developed this tool in response to our efforts -to improve a code generator we were writing [Graham82]. -.pp -The \fBgprof\fP design takes advantage of the fact that the programs -to be measured are large, structured and hierarchical. -We provide a profile in which the execution time -for a set of routines that implement an -abstraction is collected and charged -to that abstraction. -The profile can be used to compare and assess the costs of -various implementations. -.pp -The profiler can be linked into a program without -special planning by the programmer. -The overhead for using \fBgprof\fP is low; -both in terms of added execution time and in the -volume of profiling information recorded. diff --git a/usr.bin/gprof/PSD.doc/postp.me b/usr.bin/gprof/PSD.doc/postp.me deleted file mode 100644 index d71fefb..0000000 --- a/usr.bin/gprof/PSD.doc/postp.me +++ /dev/null @@ -1,190 +0,0 @@ -.\" Copyright (c) 1982, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)postp.me 8.1 (Berkeley) 6/8/93 -.\" -.EQ -delim $$ -gsize 11 -.EN -.sh 1 "Post Processing" -.pp -Having gathered the arcs of the call graph and timing information -for an execution of the program, -we are interested in attributing the time for each routine to the -routines that call it. -We build a dynamic call graph with arcs from caller to callee, -and propagate time from descendants to ancestors -by topologically sorting the call graph. -Time propagation is performed from the leaves of the -call graph toward the roots, according to the order -assigned by a topological numbering algorithm. -The topological numbering ensures that -all edges in the graph go from higher numbered nodes to lower -numbered nodes. -An example is given in Figure 1. -If we propagate time from nodes in the -order assigned by the algorithm, -execution time can be propagated from descendants to ancestors -after a single traversal of each arc in the call graph. -Each parent receives some fraction of a child's time. -Thus time is charged to the -caller in addition to being charged to the callee. -.(z -.so postp1.pic -.ce 2 -Topological ordering -Figure 1. -.ce 0 -.)z -.pp -Let $C sub e$ be the number of calls to some routine, -$e$, and $C sub e sup r$ be the number of -calls from a caller $r$ to a callee $e$. -Since we are assuming each call to a routine takes the -average amount of time for all calls to that routine, -the caller is accountable for -$C sub e sup r / C sub e$ -of the time spent by the callee. -Let the $S sub e$ be the $selftime$ of a routine, $e$. -The selftime of a routine can be determined from the -timing information gathered during profiled program execution. -The total time, $T sub r$, we wish to account to a routine -$r$, is then given by the recurrence equation: -.EQ -T sub r ~ = ~ {S sub r} ~ + ~ - sum from {r ~ roman CALLS ~ e} - {T sub e times {{C sub e sup r} over {C sub e}}} -.EN -where $r ~ roman CALLS ~ e$ is a relation showing all routines -$e$ called by a routine $r$. -This relation is easily available from the call graph. -.pp -However, if the execution contains recursive calls, -the call graph has cycles that -cannot be topologically sorted. -In these cases, we discover strongly-connected -components in the call graph, -treat each such component as a single node, -and then sort the resulting graph. -We use a variation of Tarjan's strongly-connected -components algorithm -that discovers strongly-connected components as it is assigning -topological order numbers [Tarjan72]. -.pp -Time propagation within strongly connected -components is a problem. -For example, a self-recursive routine -(a trivial cycle in the call graph) -is accountable for all the time it -uses in all its recursive instantiations. -In our scheme, this time should be -shared among its call graph parents. -The arcs from a routine to itself are of interest, -but do not participate in time propagation. -Thus the simple equation for time propagation -does not work within strongly connected components. -Time is not propagated from one member of a cycle to another, -since, by definition, this involves propagating time from a routine -to itself. -In addition, children of one member of a cycle -must be considered children of all members of the cycle. -Similarly, parents of one member of the cycle must inherit -all members of the cycle as descendants. -It is for these reasons that we collapse connected components. -Our solution collects all members of a cycle together, -summing the time and call counts for all members. -All calls into the cycle are made to share the total -time of the cycle, and all descendants of the cycle -propagate time into the cycle as a whole. -Calls among the members of the cycle -do not propagate any time, -though they are listed in the call graph profile. -.pp -Figure 2 shows a modified version of the call graph of Figure 1, -in which the nodes labelled 3 and 7 in Figure 1 are mutually -recursive. -The topologically sorted graph after the cycle is collapsed is -given in Figure 3. -.(z -.so postp2.pic -.ce 2 -Cycle to be collapsed. -Figure 2. -.ce 0 -.)z -.(z -.so postp3.pic -.ce 2 -Topological numbering after cycle collapsing. -Figure 3. -.ce 0 -.)z -.pp -Since the technique described above only collects the -dynamic call graph, -and the program typically does not call every routine -on each execution, -different executions can introduce different cycles in the -dynamic call graph. -Since cycles often have a significant effect on time propagation, -it is desirable to incorporate the static call graph so that cycles -will have the same members regardless of how the program runs. -.pp -The static call graph can be constructed from the source text -of the program. -However, discovering the static call graph from the source text -would require two moderately difficult steps: -finding the source text for the program -(which may not be available), -and scanning and parsing that text, -which may be in any one of several languages. -.pp -In our programming system, -the static calling information is also contained in the -executable version of the program, -which we already have available, -and which is in language-independent form. -One can examine the instructions -in the object program, -looking for calls to routines, and note which -routines can be called. -This technique allows us to add arcs to those already in the -dynamic call graph. -If a statically discovered arc already exists in the dynamic call -graph, no action is required. -Statically discovered arcs that do not exist in the dynamic call -graph are added to the graph with a traversal count of zero. -Thus they are never responsible for any time propagation. -However, they may affect the structure of the graph. -Since they may complete strongly connected components, -the static call graph construction is -done before topological ordering. diff --git a/usr.bin/gprof/PSD.doc/postp1.pic b/usr.bin/gprof/PSD.doc/postp1.pic deleted file mode 100644 index 1446092..0000000 --- a/usr.bin/gprof/PSD.doc/postp1.pic +++ /dev/null @@ -1,54 +0,0 @@ -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)postp1.pic 8.1 (Berkeley) 6/8/93 -.\" -.PS -circle diam .3i "8" -circle diam .3i "9" at 1st circle + (2i,0i) -circle diam .3i "3" at 1st circle + (0.5i,-0.5i) -circle diam .3i "7" at 2nd circle - (0.5i, 0.5i) -circle diam .3i "2" at 1st circle - (0i,1i) -circle diam .3i "5" at 5th circle + (1i,0i) -circle diam .3i "6" at 2nd circle - (0i,1i) -circle diam .3i "1" at 3rd circle - (0i,1i) -circle diam .3i "4" at 4th circle - (0i,1i) -arrow from 1st circle to 3rd circle chop .15i chop .15i -arrow from 1st circle to 4th circle chop .15i chop .15i -arrow from 2nd circle to 4th circle chop .15i chop .15i -arrow from 3rd circle to 5th circle chop .15i chop .15i -arrow from 4th circle to 5th circle chop .15i chop .15i -arrow from 4th circle to 6th circle chop .15i chop .15i -arrow from 4th circle to 7th circle chop .15i chop .15i -arrow from 5th circle to 8th circle chop .15i chop .15i -arrow from 6th circle to 8th circle chop .15i chop .15i -arrow from 6th circle to 9th circle chop .15i chop .15i -.PE diff --git a/usr.bin/gprof/PSD.doc/postp2.pic b/usr.bin/gprof/PSD.doc/postp2.pic deleted file mode 100644 index 3b31736..0000000 --- a/usr.bin/gprof/PSD.doc/postp2.pic +++ /dev/null @@ -1,56 +0,0 @@ -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)postp2.pic 8.1 (Berkeley) 6/8/93 -.\" -.PS -circle diam .3i "\(ci" -circle diam .3i "\(ci" at 1st circle + (2i,0i) -circle diam .3i "\(bu" at 1st circle + (0.5i,-0.5i) -circle diam .3i "\(bu" at 2nd circle - (0.5i, 0.5i) -circle diam .3i "\(ci" at 1st circle - (0i,1i) -circle diam .3i "\(ci" at 5th circle + (1i,0i) -circle diam .3i "\(ci" at 2nd circle - (0i,1i) -circle diam .3i "\(ci" at 3rd circle - (0i,1i) -circle diam .3i "\(ci" at 4th circle - (0i,1i) -arrow from 1st circle to 3rd circle chop .15i chop .15i -arrow from 1st circle to 4th circle chop .15i chop .15i -arrow from 2nd circle to 4th circle chop .15i chop .15i -spline -> from 3rd circle right .5i up .075i then right .5i down .075i chop .15i chop .15i -spline -> from 4th circle left .5i down .075i then left .5i up .075i chop .15i chop .15i -arrow from 3rd circle to 5th circle chop .15i chop .15i -arrow from 4th circle to 5th circle chop .15i chop .15i -arrow from 4th circle to 6th circle chop .15i chop .15i -arrow from 4th circle to 7th circle chop .15i chop .15i -arrow from 5th circle to 8th circle chop .15i chop .15i -arrow from 6th circle to 8th circle chop .15i chop .15i -arrow from 6th circle to 9th circle chop .15i chop .15i -.PE diff --git a/usr.bin/gprof/PSD.doc/postp3.pic b/usr.bin/gprof/PSD.doc/postp3.pic deleted file mode 100644 index 65eb2a7..0000000 --- a/usr.bin/gprof/PSD.doc/postp3.pic +++ /dev/null @@ -1,51 +0,0 @@ -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)postp3.pic 8.1 (Berkeley) 6/8/93 -.\" -.PS -circle diam .3i "7" -circle diam .3i "8" at 1st circle + (2i,0i) -EL: ellipse wid 1i ht .3i "\fB6\fR\h'.7i'\fB6\fR" at 1st circle + (1i,-0.5i) -circle diam .3i "2" at 1st circle - (0i,1i) -circle diam .3i "4" at 3th circle + (1i,0i) -circle diam .3i "5" at 2nd circle - (0i,1i) -circle diam .3i "1" at 3rd circle + (0.5i,-0.5i) -circle diam .3i "3" at 5th circle - (0.5i,0.5i) -arrow from 1st circle to EL.nw chop .15i chop 0i -arrow from 2nd circle to EL.ne chop .15i chop 0i -arrow from EL.sw to 3rd circle chop 0i chop .15i -arrow from EL.s to 4th circle chop 0i chop .15i -arrow from EL.se to 5th circle chop 0i chop .15i -arrow from 3rd circle to 6th circle chop .15i chop .15i -arrow from 4th circle to 6th circle chop .15i chop .15i -arrow from 4th circle to 7th circle chop .15i chop .15i -.PE diff --git a/usr.bin/gprof/PSD.doc/pres1.pic b/usr.bin/gprof/PSD.doc/pres1.pic deleted file mode 100644 index 0c311a1..0000000 --- a/usr.bin/gprof/PSD.doc/pres1.pic +++ /dev/null @@ -1,56 +0,0 @@ -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)pres1.pic 8.1 (Berkeley) 6/8/93 -.\" -.PS -ellipse ht .3i wid .75i "\s-1CALLER1\s+1" -ellipse ht .3i wid .75i "\s-1CALLER2\s+1" at 1st ellipse + (2i,0i) -ellipse ht .3i wid .8i "\s-1EXAMPLE\s+1" at 1st ellipse + (1i,-.5i) -ellipse ht .3i wid .5i "\s-1SUB1\s+1" at 1st ellipse - (0i,1i) -ellipse ht .3i wid .5i "\s-1SUB2\s+1" at 3rd ellipse - (0i,.5i) -ellipse ht .3i wid .5i "\s-1SUB3\s+1" at 2nd ellipse - (0i,1i) -line <- from 1st ellipse up .5i left .5i chop .1875i -line <- from 1st ellipse up .5i right .5i chop .1875i -line <- from 2nd ellipse up .5i left .5i chop .1875i -line <- from 2nd ellipse up .5i right .5i chop .1875i -arrow from 1st ellipse to 3rd ellipse chop -arrow from 2nd ellipse to 3rd ellipse chop -arrow from 3rd ellipse to 4th ellipse chop -arrow from 3rd ellipse to 5th ellipse chop .15i chop .15i -arrow from 3rd ellipse to 6th ellipse chop -arrow from 4th ellipse down .5i left .5i chop .1875i -arrow from 4th ellipse down .5i right .5i chop .1875i -arrow from 5th ellipse down .5i left .5i chop .1875i -arrow from 5th ellipse down .5i right .5i chop .1875i -arrow from 6th ellipse down .5i left .5i chop .1875i -arrow from 6th ellipse down .5i right .5i chop .1875i -.PE diff --git a/usr.bin/gprof/PSD.doc/pres2.pic b/usr.bin/gprof/PSD.doc/pres2.pic deleted file mode 100644 index c3a4ea0..0000000 --- a/usr.bin/gprof/PSD.doc/pres2.pic +++ /dev/null @@ -1,52 +0,0 @@ -.\" Copyright (c) 1986, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)pres2.pic 8.1 (Berkeley) 6/8/93 -.\" -.PS -ellipse ht .3i wid .6i "\s-1CALC1\s+1" -ellipse ht .3i wid .6i "\s-1CALC2\s+1" at 1st ellipse + (.75i,0i) -ellipse ht .3i wid .6i "\s-1CALC3\s+1" at 1st ellipse + (1.5i,0i) -ellipse ht .3i wid .8i "\s-1FORMAT1\s+1" at 1st ellipse - (0i,.5i) -ellipse ht .3i wid .8i "\s-1FORMAT2\s+1" at 3rd ellipse - (0i,.5i) -ellipse ht .3i wid .75i "\s-1\"WRITE\"\s+1" at 5th ellipse - (.75i,.5i) -line <- from 1st ellipse up .5i left .4i chop .1825i -line <- from 1st ellipse up .5i right .4i chop .1825i -line <- from 2nd ellipse up .5i left .4i chop .1825i -line <- from 2nd ellipse up .5i right .4i chop .1825i -line <- from 3rd ellipse up .5i left .4i chop .1825i -line <- from 3rd ellipse up .5i right .4i chop .1825i -arrow from 1st ellipse to 4th ellipse chop .15i -arrow from 2nd ellipse to 5th ellipse chop -arrow from 3rd ellipse to 5th ellipse chop .15i -arrow from 4th ellipse to 6th ellipse chop -arrow from 5th ellipse to 6th ellipse chop -.PE diff --git a/usr.bin/gprof/PSD.doc/present.me b/usr.bin/gprof/PSD.doc/present.me deleted file mode 100644 index 1dd7f62..0000000 --- a/usr.bin/gprof/PSD.doc/present.me +++ /dev/null @@ -1,306 +0,0 @@ -.\" Copyright (c) 1982, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)present.me 8.1 (Berkeley) 6/8/93 -.\" -.sh 1 "Data Presentation" -.pp -The data is presented to the user in two different formats. -The first presentation simply lists the routines -without regard to the amount of time their descendants use. -The second presentation incorporates the call graph of the -program. -.sh 2 "The Flat Profile -.pp -The flat profile consists of a list of all the routines -that are called during execution of the program, -with the count of the number of times they are called -and the number of seconds of execution time for which they -are themselves accountable. -The routines are listed in decreasing order of execution time. -A list of the routines that are never called during execution of -the program is also available -to verify that nothing important is omitted by -this execution. -The flat profile gives a quick overview of the routines that are used, -and shows the routines that are themselves responsible -for large fractions of the execution time. -In practice, -this profile usually shows that no single function -is overwhelmingly responsible for -the total time of the program. -Notice that for this profile, -the individual times sum to the total execution time. -.sh 2 "The Call Graph Profile" -.sz 10 -.(z -.TS -box center; -c c c c c l l -c c c c c l l -c c c c c l l -l n n n c l l. - called/total \ \ parents -index %time self descendants called+self name index - called/total \ \ children -_ - 0.20 1.20 4/10 \ \ \s-1CALLER1\s+1 [7] - 0.30 1.80 6/10 \ \ \s-1CALLER2\s+1 [1] -[2] 41.5 0.50 3.00 10+4 \s-1EXAMPLE\s+1 [2] - 1.50 1.00 20/40 \ \ \s-1SUB1\s+1 <cycle1> [4] - 0.00 0.50 1/5 \ \ \s-1SUB2\s+1 [9] - 0.00 0.00 0/5 \ \ \s-1SUB3\s+1 [11] -.TE -.ce 2 -Profile entry for \s-1EXAMPLE\s+1. -Figure 4. -.)z -.pp -Ideally, we would like to print the call graph of the program, -but we are limited by the two-dimensional nature of our output -devices. -We cannot assume that a call graph is planar, -and even if it is, that we can print a planar version of it. -Instead, we choose to list each routine, -together with information about -the routines that are its direct parents and children. -This listing presents a window into the call graph. -Based on our experience, -both parent information and child information -is important, -and should be available without searching -through the output. -.pp -The major entries of the call graph profile are the entries from the -flat profile, augmented by the time propagated to each -routine from its descendants. -This profile is sorted by the sum of the time for the routine -itself plus the time inherited from its descendants. -The profile shows which of the higher level routines -spend large portions of the total execution time -in the routines that they call. -For each routine, we show the amount of time passed by each child -to the routine, which includes time for the child itself -and for the descendants of the child -(and thus the descendants of the routine). -We also show the percentage these times represent of the total time -accounted to the child. -Similarly, the parents of each routine are listed, -along with time, -and percentage of total routine time, -propagated to each one. -.pp -Cycles are handled as single entities. -The cycle as a whole is shown as though it were a single routine, -except that members of the cycle are listed in place of the children. -Although the number of calls of each member -from within the cycle are shown, -they do not affect time propagation. -When a child is a member of a cycle, -the time shown is the appropriate fraction of the time -for the whole cycle. -Self-recursive routines have their calls broken -down into calls from the outside and self-recursive calls. -Only the outside calls affect the propagation of time. -.pp -The following example is a typical fragment of a call graph. -.(b -.so pres1.pic -.)b -The entry in the call graph profile listing for this example is -shown in Figure 4. -.pp -The entry is for routine \s-1EXAMPLE\s+1, which has -the Caller routines as its parents, -and the Sub routines as its children. -The reader should keep in mind that all information -is given \fIwith respect to \s-1EXAMPLE\s+1\fP. -The index in the first column shows that \s-1EXAMPLE\s+1 -is the second entry in the profile listing. -The \s-1EXAMPLE\s+1 routine is called ten times, four times by \s-1CALLER1\s+1, -and six times by \s-1CALLER2\s+1. -Consequently 40% of \s-1EXAMPLE\s+1's time is propagated to \s-1CALLER1\s+1, -and 60% of \s-1EXAMPLE\s+1's time is propagated to \s-1CALLER2\s+1. -The self and descendant fields of the parents -show the amount of self and descendant time \s-1EXAMPLE\s+1 -propagates to them (but not the time used by -the parents directly). -Note that \s-1EXAMPLE\s+1 calls itself recursively four times. -The routine \s-1EXAMPLE\s+1 calls routine \s-1SUB1\s+1 twenty times, \s-1SUB2\s+1 once, -and never calls \s-1SUB3\s+1. -Since \s-1SUB2\s+1 is called a total of five times, -20% of its self and descendant time is propagated to \s-1EXAMPLE\s+1's -descendant time field. -Because \s-1SUB1\s+1 is a member of \fIcycle 1\fR, -the self and descendant times -and call count fraction -are those for the cycle as a whole. -Since cycle 1 is called a total of forty times -(not counting calls among members of the cycle), -it propagates 50% of the cycle's self and descendant -time to \s-1EXAMPLE\s+1's descendant time field. -Finally each name is followed by an index that shows -where on the listing to find the entry for that routine. -.sh 1 "Using the Profiles" -.pp -The profiler is a useful tool for improving -a set of routines that implement an abstraction. -It can be helpful in identifying poorly coded routines, -and in evaluating the new algorithms and code that replace them. -Taking full advantage of the profiler -requires a careful examination of the call graph profile, -and a thorough knowledge of the abstractions underlying -the program. -.pp -The easiest optimization that can be performed -is a small change -to a control construct or data structure that improves the -running time of the program. -An obvious starting point -is a routine that is called many times. -For example, suppose an output -routine is the only parent -of a routine that formats the data. -If this format routine is expanded inline in the -output routine, the overhead of a function call and -return can be saved for each datum that needs to be formatted. -.pp -The drawback to inline expansion is that the data abstractions -in the program may become less parameterized, -hence less clearly defined. -The profiling will also become less useful since the loss of -routines will make its output more granular. -For example, -if the symbol table functions ``lookup'', ``insert'', and ``delete'' -are all merged into a single parameterized routine, -it will be impossible to determine the costs -of any one of these individual functions from the profile. -.pp -Further potential for optimization lies in routines that -implement data abstractions whose total execution -time is long. -For example, a lookup routine might be called only a few -times, but use an inefficient linear search algorithm, -that might be replaced with a binary search. -Alternately, the discovery that a rehashing function is being -called excessively, can lead to a different -hash function or a larger hash table. -If the data abstraction function cannot easily be speeded up, -it may be advantageous to cache its results, -and eliminate the need to rerun -it for identical inputs. -These and other ideas for program improvement are discussed in -[Bentley81]. -.pp -This tool is best used in an iterative approach: -profiling the program, -eliminating one bottleneck, -then finding some other part of the program -that begins to dominate execution time. -For instance, we have used \fBgprof\fR on itself; -eliminating, rewriting, and inline expanding routines, -until reading -data files (hardly a target for optimization!) -represents the dominating factor in its execution time. -.pp -Certain types of programs are not easily analyzed by \fBgprof\fR. -They are typified by programs that exhibit a large degree of -recursion, such as recursive descent compilers. -The problem is that most of the major routines are grouped -into a single monolithic cycle. -As in the symbol table abstraction that is placed -in one routine, -it is impossible to distinguish which members of the cycle are -responsible for the execution time. -Unfortunately there are no easy modifications to these programs that -make them amenable to analysis. -.pp -A completely different use of the profiler is to analyze the control -flow of an unfamiliar program. -If you receive a program from another user that you need to modify -in some small way, -it is often unclear where the changes need to be made. -By running the program on an example and then using \fBgprof\fR, -you can get a view of the structure of the program. -.pp -Consider an example in which you need to change the output format -of the program. -For purposes of this example suppose that the call graph -of the output portion of the program has the following structure: -.(b -.so pres2.pic -.)b -Initially you look through the \fBgprof\fR -output for the system call ``\s-1WRITE\s+1''. -The format routine you will need to change is probably -among the parents of the ``\s-1WRITE\s+1'' procedure. -The next step is to look at the profile entry for each -of parents of ``\s-1WRITE\s+1'', -in this example either ``\s-1FORMAT1\s+1'' or ``\s-1FORMAT2\s+1'', -to determine which one to change. -Each format routine will have one or more parents, -in this example ``\s-1CALC1\s+1'', ``\s-1CALC2\s+1'', and ``\s-1CALC3\s+1''. -By inspecting the source code for each of these routines -you can determine which format routine generates the output that -you wish to modify. -Since the \fBgprof\fR entry shows all the -potential calls to the format routine you intend to change, -you can determine if your modifications will affect output that -should be left alone. -If you desire to change the output of ``\s-1CALC2\s+1'', but not ``\s-1CALC3\s+1'', -then formatting routine ``\s-1FORMAT2\s+1'' needs to be split -into two separate routines, -one of which implements the new format. -You can then retarget just the call by ``\s-1CALC2\s+1'' -that needs the new format. -It should be noted that the static call information is particularly -useful here since the test case you run probably will not -exercise the entire program. -.sh 1 "Conclusions" -.pp -We have created a profiler that aids in the evaluation -of modular programs. -For each routine in the program, -the profile shows the extent to which that routine -helps support various abstractions, -and how that routine uses other abstractions. -The profile accurately assesses the cost of routines -at all levels of the program decomposition. -The profiler is easily used, -and can be compiled into the program without any prior planning by -the programmer. -It adds only five to thirty percent execution overhead to the program -being profiled, -produces no additional output until after the program finishes, -and allows the program to be measured in its actual environment. -Finally, the profiler runs on a time-sharing system -using only the normal services provided by the operating system -and compilers. diff --git a/usr.bin/gprof/PSD.doc/profiling.me b/usr.bin/gprof/PSD.doc/profiling.me deleted file mode 100644 index 227aedf..0000000 --- a/usr.bin/gprof/PSD.doc/profiling.me +++ /dev/null @@ -1,115 +0,0 @@ -.\" Copyright (c) 1982, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)profiling.me 8.1 (Berkeley) 6/8/93 -.\" -.sh 1 "Types of Profiling" -.pp -There are several different uses for program profiles, -and each may require different information from the profiles, -or different presentation of the information. -We distinguish two broad categories of profiles: -those that present counts of statement or routine invocations, -and those that display timing information about statements -or routines. -Counts are typically presented in tabular form, -often in parallel with a listing of the source code. -Timing information could be similarly presented; -but more than one measure of time might be associated with each -statement or routine. -For example, -in the framework used by \fBgprof\fP -each profiled segment would display two times: -one for the time used by the segment itself, and another for the -time inherited from code segments it invokes. -.pp -Execution counts are used in many different contexts. -The exact number of times a routine or statement is activated -can be used to determine if an algorithm is performing as -expected. -Cursory inspection of such counters may show algorithms whose -complexity is unsuited to the task at hand. -Careful interpretation of counters can often suggest -improvements to acceptable algorithms. -Precise examination can uncover subtle errors in an -algorithm. -At this level, profiling counters are similar to -debugging statements whose purpose is to show the number of times -a piece of code is executed. -Another view of such counters is as boolean values. -One may be interested that a portion of code has executed at -all, for exhaustive testing, or to check that one implementation -of an abstraction completely replaces a previous one. -.pp -Execution counts are not necessarily proportional to the amount -of time required to execute the routine or statement. -Further, the execution time of a routine will not be the same for -all calls on the routine. -The criteria for establishing execution time -must be decided. -If a routine implements an abstraction by invoking other abstractions, -the time spent in the routine will not accurately reflect the -time required by the abstraction it implements. -Similarly, if an abstraction is implemented by several -routines the time required by the abstraction will be distributed -across those routines. -.pp -Given the execution time of individual routines, -\fBgprof\fP accounts to each routine the time spent -for it by the routines it invokes. -This accounting is done by assembling a \fIcall graph\fP with nodes that -are the routines of the program and directed arcs that represent -calls from call sites to routines. -We distinguish among three different call graphs for a program. -The \fIcomplete call graph\fP incorporates all routines and all -potential arcs, -including arcs that represent calls to functional parameters -or functional variables. -This graph contains the other two graphs as subgraphs. -The \fIstatic call graph\fP includes all routines and all possible arcs -that are not calls to functional parameters or variables. -The \fIdynamic call graph\fP includes only those routines and -arcs traversed by the profiled execution of the program. -This graph need not include all routines, nor need it include all -potential arcs between the routines it covers. -It may, however, include arcs to functional parameters or -variables that the static call graph may omit. -The static call graph can be determined from the (static) program text. -The dynamic call graph is determined only by profiling an -execution of the program. -The complete call graph for a monolithic program could be determined -by data flow analysis techniques. -The complete call graph for programs that change -during execution, by modifying themselves or dynamically loading -or overlaying code, may never be determinable. -Both the static call graph and the dynamic call graph are used -by \fBgprof\fP, but it does not search for the complete call -graph. diff --git a/usr.bin/gprof/PSD.doc/refs.me b/usr.bin/gprof/PSD.doc/refs.me deleted file mode 100644 index 580d080..0000000 --- a/usr.bin/gprof/PSD.doc/refs.me +++ /dev/null @@ -1,63 +0,0 @@ -.\" Copyright (c) 1982, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)refs.me 8.1 (Berkeley) 6/8/93 -.\" -.sh 1 "References" -.ls 1 -.ip [Bentley81] -Bentley, J. L., -``Writing Efficient Code'', -Department of Computer Science, -Carnegie-Mellon University, -Pittsburgh, Pennsylvania, -CMU-CS-81-116, 1981. -.ip [Graham82] -Graham, S. L., Henry, R. R., Schulman, R. A., -``An Experiment in Table Driven Code Generation'', -SIGPLAN '82 Symposium on Compiler Construction, -June, 1982. -.ip [Joy79] -Joy, W. N., Graham, S. L., Haley, C. B. ``Berkeley Pascal User's Manual'', -Version 1.1, Computer Science Division -University of California, Berkeley, CA. April 1979. -.ip [Knuth71] -Knuth, D. E. ``An empirical study of FORTRAN programs'', -Software - Practice and Experience, 1, 105-133. 1971 -.ip [Satterthwaite72] -Satterthwaite, E. ``Debugging Tools for High Level Languages'', -Software - Practice and Experience, 2, 197-217, 1972 -.ip [Tarjan72] -Tarjan, R. E., ``Depth first search and linear graph algorithm,'' -\fISIAM J. Computing\fP \fB1\fP:2, 146-160, 1972. -.ip [Unix] -Unix Programmer's Manual, ``\fBprof\fR command'', section 1, -Bell Laboratories, Murray Hill, NJ. January 1979. diff --git a/usr.bin/mail/USD.doc/mail0.nr b/usr.bin/mail/USD.doc/mail0.nr deleted file mode 100644 index e569a5f..0000000 --- a/usr.bin/mail/USD.doc/mail0.nr +++ /dev/null @@ -1,72 +0,0 @@ -.\" Copyright (c) 1980, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)mail0.nr 8.1 (Berkeley) 6/8/93 -.\" -.\" $FreeBSD$ -.\" -.eh 'USD:7-%''Mail Reference Manual' -.oh 'Mail Reference Manual''USD:7-%' -.if n \ -.nr fs .5v -.\".he 'Mail Reference Manual'\n(mo/\n(dy/\n(yr'%' -.tp -.sp 1.0i -.sz 12 -.rb -.(l C -MAIL REFERENCE MANUAL -.)l -.sz 10 -.sp 2 -.i -.(l C -Kurt Shoens -.)l -.r -.(l C -Revised by -.)l -.(l C -.i -Craig Leres\ \c -.r -and\ \c -.i -Mark Andrews -.)l -.r -.(l C -Version 5.5 - - -.)l -.pn 2 diff --git a/usr.bin/mail/USD.doc/mail1.nr b/usr.bin/mail/USD.doc/mail1.nr deleted file mode 100644 index 50e7883..0000000 --- a/usr.bin/mail/USD.doc/mail1.nr +++ /dev/null @@ -1,92 +0,0 @@ -.\" Copyright (c) 1980, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)mail1.nr 8.1 (Berkeley) 6/8/93 -.\" -.sh 1 Introduction -.pp -.i Mail -provides a simple and friendly environment for sending and receiving mail. -It divides incoming mail into -its constituent messages and allows the user to deal with them -in any order. In addition, it provides a set of -.i ed -\c -like commands for manipulating messages and sending mail. -.i Mail -offers the user simple editing capabilities to ease the composition -of outgoing messages, as well as providing the ability to define and send -to names which address groups of users. Finally, -.i Mail -is able to send and receive messages across such networks as the -ARPANET, UUCP, and Berkeley network. -.pp -This document describes how to use the -.i Mail -program to send and receive messages. The reader is not assumed to -be familiar with other message handling systems, but should be -familiar with the \s-2UNIX\s0\** -.(f -\** \s-1UNIX\s0 is a trademark of Bell Laboratories. -.)f -shell, the text editor, and some of the common \s-2UNIX\s0 commands. -.q "The \s-2UNIX\s0 Programmer's Manual," -.q "An Introduction to Csh," -and -.q "Text Editing with Ex and Vi" -can be consulted for more information on these topics. -.pp -Here is how messages are handled: -the mail system accepts incoming -.i messages -for you from other people -and collects them in a file, called your -.i "system mailbox" . -When you login, the system notifies you if there are any messages -waiting in your system mailbox. If you are a -.i csh -user, you will be notified when new mail arrives if you inform -the shell of the location of your mailbox. On version 7 systems, -your system mailbox is located in the directory /var/mail -in a file with your login name. If your login name is -.q sam, -then you can make -.i csh -notify you of new mail by including the following line in your .cshrc -file: -.(l -set mail=/var/mail/sam -.)l -When you read your mail using -.i Mail , -it reads your system mailbox and separates that file into the -individual messages that have been sent to you. You can then -read, reply to, delete, or save these messages. -Each message is marked with its author and the date they sent it. diff --git a/usr.bin/mail/USD.doc/mail2.nr b/usr.bin/mail/USD.doc/mail2.nr deleted file mode 100644 index 0419859..0000000 --- a/usr.bin/mail/USD.doc/mail2.nr +++ /dev/null @@ -1,617 +0,0 @@ -.\" Copyright (c) 1980, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)mail2.nr 8.1 (Berkeley) 6/8/93 -.\" -.bp -.sh 1 "Common usage" -.pp -The -.i Mail -command has two distinct usages, according to whether one -wants to send or receive mail. Sending mail is simple: to send a -message to a user whose login name is, say, -\*(lqroot,\*(rq -use the shell -command: -.(l -% Mail root -.)l -then type your message. When you reach the end of the message, type -an EOT (control\-d) at the beginning of a line, which will cause -.i Mail -to echo \*(lqEOT\*(rq and return you to the Shell. When the user you sent mail -to next logs in, he will receive the message: -.(l -You have mail. -.)l -to alert him to the existence of your message. -.pp -If, while you are composing the message -you decide that you do not wish to send it after all, you can -abort the letter with a \s-2RUBOUT\s0. Typing a single \s-2RUBOUT\s0 -causes -.i Mail -to print -.(l -(Interrupt -- one more to kill letter) -.)l -Typing a second -\s-2RUBOUT\s0 causes -.i Mail -to save your partial letter on the file -.q dead.letter -in your home directory and abort the letter. -Once you have -sent mail to someone, there is no way to undo the act, so be -careful. -.pp -The message your recipient reads will consist of the message you -typed, preceded by a line telling who sent the message (your login name) -and the date and time it -was sent. -.pp -If you want to send the same message to several other people, you can list -their login names on the command line. -Thus, -.(l -% Mail sam bob john -Tuition fees are due next Friday. Don't forget!! -<Control\-d> -EOT -% -.)l -will send the reminder to sam, bob, and john. -.pp -If, when you log in, you see the message, -.(l -You have mail. -.)l -you can read the mail by typing simply: -.(l -% Mail -.)l -.i Mail -will respond by typing its version number and date and then listing -the messages you have waiting. Then it will type a prompt and await -your command. The messages are assigned numbers starting with 1 \*- you -refer to the messages with these numbers. -.i Mail -keeps track of which messages are -.i new -(have been sent since you last read your mail) and -.i read -(have been read by you). New messages have an -.b N -next to them in the header listing and old, but unread messages have -a -.b U -next to them. -.i Mail -keeps track of new/old and read/unread messages by putting a -header field called -.q Status -into your messages. -.pp -To look at a specific message, use the -.b type -command, which may be abbreviated to simply -.b t . -For example, if you had the following messages: -.(l -N 1 root Wed Sep 21 09:21 "Tuition fees" -N 2 sam Tue Sep 20 22:55 -.)l -you could examine the first message by giving the command: -.(l -type 1 -.)l -which might cause -.i Mail -to respond with, for example: -.(l -Message 1: -From root Wed Sep 21 09:21:45 1978 -Subject: Tuition fees -Status: R - -Tuition fees are due next Wednesday. Don't forget!! - -.)l -Many -.i Mail -commands that operate on messages take a message number as an -argument like the -.b type -command. For these commands, there is a notion of a current -message. When you enter the -.i Mail -program, the current message is initially the first one. Thus, -you can often omit the message number and use, for example, -.(l -t -.)l -to type the current message. As a further shorthand, you can type a message -by simply giving its message number. Hence, -.(l -1 -.)l -would type the first message. -.pp -Frequently, it is useful to read the messages in your mailbox in order, -one after another. You can read the next message in -.i Mail -by simply typing a newline. As a special case, you can type a newline -as your first command to -.i Mail -to type the first message. -.pp -If, after typing a message, you wish to immediately send a reply, -you can do so with the -.b reply -command. -.b Reply , -like -.b type , -takes a message number as an argument. -.i Mail -then begins a message addressed to the user who sent you the message. -You may then type in your letter in reply, followed by a <control-d> -at the beginning of a line, as before. -.i Mail -will type EOT, then type the ampersand prompt to indicate its readiness -to accept another command. In our example, if, after typing the -first message, you wished to reply to it, you might give the command: -.(l -reply -.)l -.i Mail -responds by typing: -.(l -To: root -Subject: Re: Tuition fees -.)l -and waiting for you to enter your letter. -You are now in the message collection mode described at the beginning -of this section and -.i Mail -will gather up your message up to a control\-d. -Note that it copies the subject -header from the original message. This is useful in that correspondence -about a particular matter will tend to retain the same subject heading, -making it easy to recognize. If there are other header fields in -the message, the information found will also be used. -For example, if the letter had a -.q "To:" -header listing several recipients, -.i Mail -would arrange to send your replay to the same people as well. -Similarly, if the original message contained a -.q "Cc:" -(carbon copies to) field, -.i Mail -would send your reply to -.i those -users, too. -.i Mail -is careful, though, not too send the message to -.i you , -even if you appear in the -.q "To:" -or -.q "Cc:" -field, unless you ask to be included explicitly. See section 4 for more -details. -.pp -After typing in your letter, the dialog with -.i Mail -might look like the following: -.(l -reply -To: root -Subject: Tuition fees - -Thanks for the reminder -EOT -& -.)l -.pp -The -.b reply -command is especially useful for sustaining extended conversations -over the message system, with other -.q listening -users receiving copies of the conversation. The -.b reply -command can be abbreviated to -.b r . -.pp -Sometimes you will receive a message that has been sent to -several people and wish to reply -.i only -to the person who sent it. -.b Reply -with a capital -.b R -replies to a message, but sends a copy to the sender only. -.pp -If you wish, while reading your mail, to send a message to someone, -but not as a reply to one of your messages, you can send the message -directly with the -.b mail -command, which takes as arguments the names of the recipients you wish -to send to. For example, to send a message to -.q frank, -you would do: -.(l -mail frank -This is to confirm our meeting next Friday at 4. -EOT -& -.)l -The -.b mail -command can be abbreviated to -.b m . -.pp -Normally, each message you receive is saved in the file -.i mbox -in your login directory at the time you leave -.i Mail . -Often, -however, you will not want to save a particular message you -have received because it is only of passing interest. To avoid -saving a message in -.i mbox -you can delete it using the -.b delete -command. In our example, -.(l -delete 1 -.)l -will prevent -.i Mail -from saving message 1 (from root) in -.i mbox . -In addition to not saving deleted messages, -.i Mail -will not let -you type them, either. The effect is to make the message disappear -altogether, along with its number. The -.b delete -command can be abbreviated to simply -.b d . -.pp -Many features of -.i Mail -can be tailored to your liking with the -.b set -command. The -.b set -command has two forms, depending on whether you are setting -a -.i binary -option or a -.i valued -option. -Binary options are either on or off. For example, the -.q ask -option informs -.i Mail -that each time you send a message, you want it to prompt you for -a subject header, to be included in the message. -To set the -.q ask -option, you would type -.(l -set ask -.)l -.pp -Another useful -.i Mail -option is -.q hold. -Unless told otherwise, -.i Mail -moves the messages from your system mailbox to the file -.i mbox -in your home directory when you leave -.i Mail . -If you want -.i Mail -to keep your letters in the system mailbox instead, you can set the -.q hold -option. -.pp -Valued options are values which -.i Mail -uses to adapt to your tastes. For example, the -.q SHELL -option tells -.i Mail -which shell you like to use, and is specified by -.(l -set SHELL=/bin/csh -.)l -for example. Note that no spaces are allowed in -.q "SHELL=/bin/csh." -A complete list of the -.i Mail -options appears in section 5. -.pp -Another important valued option is -.q crt. -If you use a fast video terminal, you will find that when you -print long messages, they fly by too quickly for you to read them. -With the -.q crt -option, you can make -.i Mail -print any message larger than a given number of lines by sending -it through a paging program. This program is specified by the -valued option \fBPAGER\fP. -If \fBPAGER\fP is not set, a default paginator is used. -For example, most CRT users with 24-line screens should do: -.(l -set crt=24 -.)l -to paginate messages that will not fit on their screens. -In the default state, \fImore\fP (default paginator) prints a screenful of -information, then types --More--. Type a space to see the next screenful. -.pp -Another adaptation to user needs that -.i Mail -provides is that of -.i aliases . -An alias is simply a name which stands for one or more -real user names. -.i Mail -sent to an alias is really sent to the list of real users -associated with it. For example, an alias can be defined for the -members of a project, so that you can send mail to the whole project -by sending mail to just a single name. The -.b alias -command in -.i Mail -defines an alias. Suppose that the users in a project are -named Sam, Sally, Steve, and Susan. To define an alias called -.q project -for them, you would use the -.i Mail -command: -.(l -alias project sam sally steve susan -.)l -The -.b alias -command can also be used to provide a convenient name for someone -whose user name is inconvenient. For example, if a user named -.q "Bob Anderson" -had the login name -.q anderson," -you might want to use: -.(l -alias bob anderson -.)l -so that you could send mail to the shorter name, -.q bob. -.pp -While the -.b alias -and -.b set -commands allow you to customize -.i Mail , -they have the drawback that they must be retyped each time you enter -.i Mail . -To make them more convenient to use, -.i Mail -always looks for two files when it is invoked. It first reads -a system wide file -.q /etc/mail.rc, -then a user specific file, -.q .mailrc, -which is found in the user's home directory. -The system wide file -is maintained by the system administrator and -contains -.b set -commands that are applicable to all users of the system. -The -.q .mailrc -file is usually used by each user to set options the way he likes -and define individual aliases. -For example, my .mailrc file looks like this: -.(l -set ask nosave SHELL=/bin/csh -.)l -As you can see, it is possible to set many options in the -same -.b set -command. The -.q nosave -option is described in section 5. -.pp -Mail aliasing is implemented -at the system-wide level -by the mail delivery -system -.i sendmail . -These aliases are stored in the file /usr/lib/aliases and are -accessible to all users of the system. -The lines in /usr/lib/aliases are of -the form: -.(l -alias: name\*<1\*>, name\*<2\*>, name\*<3\*> -.)l -where -.i alias -is the mailing list name and the -.i name\*<i\*> -are the members of the list. Long lists can be continued onto the next -line by starting the next line with a space or tab. Remember that you -must execute the shell command -.i newaliases -after editing /usr/lib/aliases since the delivery system -uses an indexed file created by -.i newaliases . -.pp -We have seen that -.i Mail -can be invoked with command line arguments which are people -to send the message to, or with no arguments to read mail. -Specifying the -.rb \-f -flag on the command line causes -.i Mail -to read messages from a file other than your system mailbox. -For example, if you have a collection of messages in -the file -.q letters -you can use -.i Mail -to read them with: -.(l -% Mail \-f letters -.)l -You can use all -the -.i Mail -commands described in this document to examine, modify, or delete -messages from your -.q letters -file, which will be rewritten when you leave -.i Mail -with the -.b quit -command described below. -.pp -Since mail that you read is saved in the file -.i mbox -in your home directory by default, you can read -.i mbox -in your home directory by using simply -.(l -% Mail \-f -.)l -.pp -Normally, messages that you examine using the -.b type -command are saved in the file -.q mbox -in your home directory if you leave -.i Mail -with the -.b quit -command described below. -If you wish to retain a message in your system mailbox -you can use the -.b preserve -command to tell -.i Mail -to leave it there. -The -.b preserve -command accepts a list of message numbers, just like -.b type -and may be abbreviated to -.b pre . -.pp -Messages in your system mailbox that you do not examine are -normally retained in your system mailbox automatically. -If you wish to have such a message saved in -.i mbox -without reading it, you may use the -.b mbox -command to have them so saved. For example, -.(l -mbox 2 -.)l -in our example would cause the second message (from sam) -to be saved in -.i mbox -when the -.b quit -command is executed. -.b Mbox -is also the way to direct messages to your -.i mbox -file if you have set the -.q hold -option described above. -.b Mbox -can be abbreviated to -.b mb . -.pp -When you have perused all the messages of interest, you can leave -.i Mail -with the -.b quit -command, which saves the messages you have typed but not -deleted in the file -.i mbox -in your login directory. Deleted messages are discarded irretrievably, -and messages left untouched are preserved in your system mailbox so -that you will see them the next time you type: -.(l -% Mail -.)l -The -.b quit -command can be abbreviated to simply -.b q . -.pp -If you wish for some reason to leave -.i Mail -quickly without altering either your system mailbox or -.i mbox , -you can type the -.b x -command (short for -.b exit ), -which will immediately return you to the Shell without changing anything. -.pp -If, instead, you want to execute a Shell command without leaving -.i Mail , -you -can type the command preceded by an exclamation point, just as in the -text editor. Thus, for instance: -.(l -!date -.)l -will print the current date without leaving -.i Mail . -.pp -Finally, the -.b help -command is available to print out a brief summary of the -.i Mail -commands, using only the single character command abbreviations. diff --git a/usr.bin/mail/USD.doc/mail3.nr b/usr.bin/mail/USD.doc/mail3.nr deleted file mode 100644 index 8b133ef..0000000 --- a/usr.bin/mail/USD.doc/mail3.nr +++ /dev/null @@ -1,133 +0,0 @@ -.\" Copyright (c) 1980, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)mail3.nr 8.1 (Berkeley) 6/8/93 -.\" -.sh 1 "Maintaining folders" -.pp -.i Mail -includes a simple facility for maintaining groups of messages together -in folders. This section describes this facility. -.pp -To use the folder facility, you must tell -.i Mail -where you wish to keep your folders. Each folder of messages will -be a single file. For convenience, all of your folders are kept in -a single directory of your choosing. To tell -.i Mail -where your folder directory is, put a line of the form -.(l -set folder=letters -.)l -in your -.i .mailrc -file. If, as in the example above, your folder directory does not -begin with a `/,' -.i Mail -will assume that your folder directory is to be found starting from -your home directory. Thus, if your home directory is -.b /home/person -the above example told -.i Mail -to find your folder directory in -.b /home/person/letters . -.pp -Anywhere a file name is expected, you can use a folder name, preceded -with `+.' For example, to put a message into a folder with the -.b save -command, you can use: -.(l -save +classwork -.)l -to save the current message in the -.i classwork -folder. If the -.i classwork -folder does not yet exist, it will be created. Note that messages -which are saved with the -.b save -command are automatically removed from your system mailbox. -.pp -In order to make a copy of a message in a folder without causing -that message to be removed from your system mailbox, use the -.b copy -command, which is identical in all other respects to the -.b save -command. For example, -.(l -copy +classwork -.)l -copies the current message into the -.i classwork -folder and leaves a copy in your system mailbox. -.pp -The -.b folder -command -can be used to direct -.i Mail -to the contents of a different folder. -For example, -.(l -folder +classwork -.)l -directs -.i Mail -to read the contents of the -.i classwork -folder. All of the commands that you can use on your system -mailbox are also applicable to folders, including -.b type , -.b delete , -and -.b reply . -To inquire which folder you are currently editing, use simply: -.(l -folder -.)l -.pp -To list your current set of folders, use the -.b folders -command. -.pp -To start -.i Mail -reading one of your folders, you can use the -.b \-f -option described in section 2. For example: -.(l -% Mail \-f +classwork -.)l -will cause -.i Mail -to read your -.i classwork -folder without looking at your system mailbox. diff --git a/usr.bin/mail/USD.doc/mail4.nr b/usr.bin/mail/USD.doc/mail4.nr deleted file mode 100644 index 1a1e046..0000000 --- a/usr.bin/mail/USD.doc/mail4.nr +++ /dev/null @@ -1,437 +0,0 @@ -.\" Copyright (c) 1980, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)mail4.nr 8.1 (Berkeley) 6/8/93 -.\" -.bp -.sh 1 "More about sending mail" -.sh 2 "Tilde escapes" -.pp -While typing in a message to be sent to others, it is often -useful to be able to invoke the text editor on the partial message, -print the message, execute a shell command, or do some other -auxiliary function. -.i Mail -provides these capabilities through -.i "tilde escapes" , -which consist of a tilde (~) at the beginning of a line, followed by -a single character which indicates the function to be performed. For -example, to print the text of the message so far, use: -.(l -~p -.)l -which will print a line of dashes, the recipients of your message, and -the text of the message so far. -Since -.i Mail -requires two consecutive \s-2RUBOUT\s0's to abort a letter, you -can use a single \s-2RUBOUT\s0 to abort the output of ~p or any other -~ escape without killing your letter. -.pp -If you are dissatisfied with the message as -it stands, you can invoke the text editor on it using the escape -.(l -~e -.)l -which causes the message to be copied into a temporary file and an -instance of the editor to be spawned. After modifying the message to -your satisfaction, write it out and quit the editor. -.i Mail -will respond -by typing -.(l -(continue) -.)l -after which you may continue typing text which will be appended to your -message, or type <control-d> to end the message. -A standard text editor is provided by -.i Mail . -You can override this default by setting the valued option -.q EDITOR -to something else. For example, you might prefer: -.(l -set EDITOR=/usr/bin/ex -.)l -.pp -Many systems offer a screen editor as an alternative to the standard -text editor, such as the -.i vi -editor from UC Berkeley. -To use the screen, or -.i visual -editor, on your current message, you can use the escape, -.(l -~v -.)l -~v works like ~e, except that the screen editor is invoked instead. -A default screen editor is defined by -.i Mail . -If it does not suit you, you can set the valued option -.q VISUAL -to the path name of a different editor. -.pp -It is often useful to be able to include the contents of some -file in your message; the escape -.(l -~r filename -.)l -is provided for this purpose, and causes the named file to be appended -to your current message. -.i Mail -complains if the file doesn't exist -or can't be read. If the read is successful, the number of lines and -characters appended to your message is printed, after which you may continue -appending text. The filename may contain shell metacharacters like * and ? -which are expanded according to the conventions of your shell. -.pp -As a special case of ~r, the escape -.(l -~d -.)l -reads in the file -.q dead.letter -in your home directory. This is often useful since -.i Mail -copies the text -of your message there when you abort a message with \s-2RUBOUT\s0. -.pp -To save the current text of your message on a file you may use the -.(l -~w filename -.)l -escape. -.i Mail -will print out the number of lines and characters written -to the file, after which you may continue appending text to your message. -Shell metacharacters may be used in the filename, as in ~r and are expanded -with the conventions of your shell. -.pp -If you are sending mail from within -.i Mail's -command mode -you can read a message sent to you into the message -you are constructing with the escape: -.(l -~m 4 -.)l -which will read message 4 into the current message, shifted right by -one tab stop. You can name any non-deleted message, or list of messages. -Messages can also be forwarded without shifting by a tab stop with ~f. -This is the usual way to forward a message. -.pp -If, in the process of composing a message, you decide to add additional -people to the list of message recipients, you can do so with the escape -.(l -~t name1 name2 ... -.)l -You may name as few or many additional recipients as you wish. Note -that the users originally on the recipient list will still receive -the message; you cannot remove someone from the recipient -list with ~t. -.pp -If you wish, you can associate a subject with your message by using the -escape -.(l -~s Arbitrary string of text -.)l -which replaces any previous subject with -.q "Arbitrary string of text." -The subject, if given, is sent near the -top of the message prefixed with -.q "Subject:" -You can see what the message will look like by using ~p. -.pp -For political reasons, one occasionally prefers to list certain -people as recipients of carbon copies of a message rather than -direct recipients. The escape -.(l -~c name1 name2 ... -.)l -adds the named people to the -.q "Cc:" -list, similar to ~t. -Again, you can execute ~p to see what the message will look like. -.pp -The escape -.(l -~b name1 name2 ... -.)l -adds the named people to the -.q "Cc:" -list, but does not make the names visible in the -.q "Cc:" -line ("blind" carbon copy). -.pp -The recipients of the message together constitute the -.q "To:" -field, the subject the -.q "Subject:" -field, and the carbon copies the -.q "Cc:" -field. If you wish to edit these in ways impossible with the ~t, ~s, ~c -and ~b escapes, you can use the escape -.(l -~h -.)l -which prints -.q "To:" -followed by the current list of recipients and leaves the cursor -(or printhead) at the end of the line. If you type in ordinary -characters, they are appended to the end of the current list of -recipients. You can also use your erase character to erase back into -the list of recipients, or your kill character to erase them altogether. -Thus, for example, if your erase and kill characters are the standard -(on printing terminals) # and @ symbols, -.(l -~h -To: root kurt####bill -.)l -would change the initial recipients -.q "root kurt" -to -.q "root bill." -When you type a newline, -.i Mail -advances to the -.q "Subject:" -field, where the same rules apply. Another newline brings you to -the -.q "Cc:" -field, which may be edited in the same fashion. Another newline -brings you to the -.q "Bcc:" -("blind" carbon copy) field, which follows the same rules as the "Cc:" -field. Another newline -leaves you appending text to the end of your message. You can use -~p to print the current text of the header fields and the body -of the message. -.pp -To effect a temporary escape to the shell, the escape -.(l -~!command -.)l -is used, which executes -.i command -and returns you to mailing mode without altering the text of -your message. If you wish, instead, to filter the body of your -message through a shell command, then you can use -.(l -~|command -.)l -which pipes your message through the command and uses the output -as the new text of your message. If the command produces no output, -.i Mail -assumes that something is amiss and retains the old version -of your message. A frequently-used filter is the command -.i fmt , -designed to format outgoing mail. -.pp -To effect a temporary escape to -.i Mail -command mode instead, you can use the -.(l -~:\fIMail command\fP -.)l -escape. This is especially useful for retyping the message you are -replying to, using, for example: -.(l -~:t -.)l -It is also useful for setting options and modifying aliases. -.pp -If you wish abort the current message, you can use the escape -.(l -~q -.)l -This will terminate the current message and return you to the -shell (or \fIMail\fP if you were using the \fBmail\fP command). -If the \fBsave\fP option is set, the message will be copied -to the file -.q dead.letter -in your home directory. -.pp -If you wish (for some reason) to send a message that contains -a line beginning with a tilde, you must double it. Thus, for example, -.(l -~~This line begins with a tilde. -.)l -sends the line -.(l -~This line begins with a tilde. -.)l -.pp -Finally, the escape -.(l -~? -.)l -prints out a brief summary of the available tilde escapes. -.pp -On some terminals (particularly ones with no lower case) -tilde's are difficult to type. -.i Mail -allows you to change the escape character with the -.q escape -option. For example, I set -.(l -set escape=] -.)l -and use a right bracket instead of a tilde. If I ever need to -send a line beginning with right bracket, I double it, just as for ~. -Changing the escape character removes the special meaning of ~. -.sh 2 "Network access" -.pp -This section describes how to send mail to people on other machines. -Recall that sending to a plain login name sends mail to that person -on your machine. If your machine is directly (or sometimes, even, -indirectly) connected to the Arpanet, you can send messages to people -on the Arpanet using a name of the form -.(l -name@host.domain -.)l -where -.i name -is the login name of the person you're trying to reach, -.i host -is the name of the machine on the Arpanet, -and -.i domain -is the higher-level scope within which the hostname is known, e.g. EDU (for educational -institutions), COM (for commercial entities), GOV (for governmental agencies), -ARPA for many other things, BITNET or CSNET for those networks. -.pp -If your recipient logs in on a machine connected to yours by -UUCP (the Bell Laboratories supplied network that communicates -over telephone lines), sending mail can be a bit more complicated. -You must know the list of machines through which your message must -travel to arrive at his site. So, if his machine is directly connected -to yours, you can send mail to him using the syntax: -.(l -host!name -.)l -where, again, -.i host -is the name of the machine and -.i name -is the login name. -If your message must go through an intermediary machine first, you -must use the syntax: -.(l -intermediary!host!name -.)l -and so on. It is actually a feature of UUCP that the map of all -the systems in the network is not known anywhere (except where people -decide to write it down for convenience). Talk to your system administrator -about good ways to get places; the -.i uuname -command will tell you systems whose names are recognized, but not which -ones are frequently called or well-connected. -.pp -When you use the -.b reply -command to respond to a letter, there is a problem of figuring out the -names of the users in the -.q "To:" -and -.q "Cc:" -lists -.i "relative to the current machine" . -If the original letter was sent to you by someone on the local machine, -then this problem does not exist, but if the message came from a remote -machine, the problem must be dealt with. -.i Mail -uses a heuristic to build the correct name for each user relative -to the local machine. So, when you -.b reply -to remote mail, the names in the -.q "To:" -and -.q "Cc:" -lists may change somewhat. -.sh 2 "Special recipients" -.pp -As described previously, you can send mail to either user names or -.b alias -names. It is also possible to send messages directly to files or to -programs, using special conventions. If a recipient name has a -`/' in it or begins with a `+', it is assumed to be the -path name of a file into which -to send the message. If the file already exists, the message is -appended to the end of the file. If you want to name a file in -your current directory (ie, one for which a `/' would not usually -be needed) you can precede the name with `./' -So, to send mail to the file -.q memo -in the current directory, you can give the command: -.(l -% Mail ./memo -.)l -If the name begins with a `+,' it is expanded into the full path name -of the folder name in your folder directory. -This ability to send mail to files can be used for a variety of -purposes, such as maintaining a journal and keeping a record of -mail sent to a certain group of users. The second example can be -done automatically by including the full pathname of the record -file in the -.b alias -command for the group. Using our previous -.b alias -example, you might give the command: -.(l -alias project sam sally steve susan /usr/project/mail_record -.)l -Then, all mail sent to "project" would be saved on the file -.q /usr/project/mail_record -as well as being sent to the members of the project. This file -can be examined using -.i "Mail \-f" . -.pp -It is sometimes useful to send mail directly to a program, for -example one might write a project billboard program and want to access -it using -.i Mail . -To send messages to the billboard program, one can send mail -to the special name `|billboard' for example. -.i Mail -treats recipient names that begin with a `|' as a program to send -the mail to. An -.b alias -can be set up to reference a `|' prefaced name if desired. -.i Caveats : -the shell treats `|' specially, so it must be quoted on the command -line. Also, the `| program' must be presented as a single argument to -mail. The safest course is to surround the entire name with double -quotes. This also applies to usage in the -.b alias -command. For example, if we wanted to alias `rmsgs' to `rmsgs \-s' -we would need to say: -.(l -alias rmsgs "| rmsgs -s" -.)l diff --git a/usr.bin/mail/USD.doc/mail5.nr b/usr.bin/mail/USD.doc/mail5.nr deleted file mode 100644 index 10e707c..0000000 --- a/usr.bin/mail/USD.doc/mail5.nr +++ /dev/null @@ -1,1042 +0,0 @@ -.\" Copyright (c) 1980, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)mail5.nr 8.1 (Berkeley) 6/8/93 -.\" $FreeBSD$ -.\" -.bp -.sh 1 "Additional features" -.pp -This section describes some additional commands useful for -reading your mail, setting options, and handling lists of messages. -.sh 2 "Message lists" -.pp -Several -.i Mail -commands accept a list of messages as an argument. -Along with -.b type -and -.b delete , -described in section 2, -there is the -.b from -command, which prints the message headers associated with the -message list passed to it. -The -.b from -command is particularly useful in conjunction with some of the -message list features described below. -.pp -A -.i "message list" -consists of a list of message numbers, ranges, and names, -separated by spaces or tabs. Message numbers may be either -decimal numbers, which directly specify messages, or one of the -special characters -.q \(ua -.q "." -or -.q "$" -to specify the first relevant, current, or last -relevant message, respectively. -.i Relevant -here means, for most commands -.q "not deleted" -and -.q "deleted" -for the -.b undelete -command. -.pp -A range of messages consists of two message numbers (of the form -described in the previous paragraph) separated by a dash. -Thus, to print the first four messages, use -.(l -type 1\-4 -.)l -and to print all the messages from the current message to the last -message, use -.(l -type .\-$ -.)l -.pp -A -.i name -is a user name. The user names given in the message list are -collected together and each message selected by other means -is checked to make sure it was sent by one of the named users. -If the message consists entirely of user names, then every -message sent by one of those users that is -.i relevant -(in the sense described earlier) -is selected. Thus, to print every message sent to you by -.q root, -do -.(l -type root -.)l -.pp -As a shorthand notation, you can specify simply -.q * -to get every -.i relevant -(same sense) -message. Thus, -.(l -type * -.)l -prints all undeleted messages, -.(l -delete * -.)l -deletes all undeleted messages, and -.(l -undelete * -.)l -undeletes all deleted messages. -.pp -You can search for the presence of a word in subject lines with -.b / . -For example, to print the headers of all messages that contain the -word -.q PASCAL, -do: -.(l -from /pascal -.)l -Note that subject searching ignores upper/lower case differences. -.sh 2 "List of commands" -.pp -This section describes all the -.i Mail -commands available when -receiving mail. -.ip "\fB\-\fP\ \ " -The -.rb \- -command goes to the previous message and prints it. The -.rb \- -command may be given a decimal number -.i n -as an argument, in which case the -.i n th -previous message is gone to and printed. -.ip "\fB?\fP\ \ " -Prints a brief summary of commands. -.ip "\fB!\fP\ \ " -Used to preface a command to be executed by the shell. -.ip "\fBPrint\fP\ \ " -Like -.b print , -but also print out ignored header fields. See also -\fBprint\fP, \fBignore\fP and \fBretain\fP. -\fBPrint\fP can be abbreviated to \fBP\fP. -.ip "\fBReply\fP or \fBRespond\fP\ \ " -Note the capital \fBR\fP in the name. -Frame a reply to a one or more messages. -The reply (or replies if you are using this on multiple messages) -will be sent ONLY to the person who sent you the message -(respectively, the set of people who sent the messages you are -replying to). -You can -add people using the \fB~t\fP, \fB~c\fP and \fB~b\fP -tilde escapes. The subject in your reply is formed by prefacing the -subject in the original message with -.q "Re:" -unless it already began thus. -If the original message included a -.q "reply-to" -header field, the reply will go -.i only -to the recipient named by -.q "reply-to." -You type in your message using the same conventions available to you -through the -.b mail -command. -The -.b Reply -command is especially useful for replying to messages that were sent -to enormous distribution groups when you really just want to -send a message to the originator. Use it often. -\fBReply\fP (and \fBRespond\fP) can be abbreviated to \fBR\fP. -.ip "\fBType\fP\ \ " -Identical to the -.b Print -command. -\fBType\fP can be abbreviated to \fBT\fP. -.ip "\fBalias\fP\ \ " -Define a name to stand for a set of other names. -This is used when you want to send messages to a certain -group of people and want to avoid retyping their names. -For example -.(l -alias project john sue willie kathryn -.)l -creates an alias -.i project -which expands to the four people John, Sue, Willie, and Kathryn. -If no arguments are given, all currently-defined aliases are printed. -If one argument is given, that alias is printed (if it exists). -\fBAlias\fP can be abbreviated to \fBa\fP. -.ip "\fBalternates\fP\ \ " -If you have accounts on several machines, you may find it convenient -to use the /usr/lib/aliases on all the machines except one to direct -your mail to a single account. -The -.b alternates -command is used to inform -.i Mail -that each of these other addresses is really -.i you . -.i Alternates -takes a list of user names and remembers that they are all actually you. -When you -.b reply -to messages that were sent to one of these alternate names, -.i Mail -will not bother to send a copy of the message to this other address (which -would simply be directed back to you by the alias mechanism). -If -.i alternates -is given no argument, it lists the current set of alternate names. -.b Alternates -is usually used in the .mailrc file. -\fBAlternates\fP can be abbreviated to \fBalt\fP. -.ip "\fBchdir\fP\ \ " -The -.b chdir -command allows you to change your current directory. -.b Chdir -takes a single argument, which is taken to be the pathname of -the directory to change to. If no argument is given, -.b chdir -changes to your home directory. -\fBChdir\fP can be abbreviated to \fBc\fP. -.ip "\fBcopy\fP\ \ " -The -.b copy -command does the same thing that -.b save -does, except that it does not mark the messages it is used on -for deletion when you quit. -\fBCopy\fP can be abbreviated to \fBco\fP. -.ip "\fBdelete\fP\ \ " -Deletes a list of messages. Deleted messages can be reclaimed -with the -.b undelete -command. -\fBDelete\fP can be abbreviated to \fBd\fP. -.ip "\fBdp\fP or \fBdt\fP\ \ " -These -commands delete the current message and print the next message. -They are useful for quickly reading and disposing of mail. -If there is no next message, \fImail\fP says ``at EOF.'' -.ip "\fBedit\fP\ \ " -To edit individual messages using the text editor, the -.b edit -command is provided. The -.b edit -command takes a list of messages as described under the -.b type -command and processes each by writing it into the file -Message\c -.i x -where -.i x -is the message number being edited and executing the text editor on it. -When you have edited the message to your satisfaction, write the message -out and quit, upon which -.i Mail -will read the message back and remove the file. -.b Edit -can be abbreviated to -.b e . -.ip "\fBelse\fP\ \ " -Marks the end of the then-part of an -.b if -statement and the beginning of the -part to take effect if the condition of the -.b if -statement is false. -.ip "\fBendif\fP\ \ " -Marks the end of an -.b if -statement. -.ip "\fBexit\fP or \fBxit\fP\ \ " -Leave -.i Mail -without updating the system mailbox or the file your were reading. -Thus, if you accidentally delete several messages, you can use -.b exit -to avoid scrambling your mailbox. -\fBExit\fP can be abbreviated to \fBex\fP or \fBx\fP. -.ip "\fBfile\fP\ \ " -The same as -.b folder . -\fBFile\fP can be abbreviated to \fBfi\fP. -.ip "\fBfolders\fP\ \ " -List the names of the folders in your folder directory. -.ip "\fBfolder\fP\ \ " -The -.b folder -command switches to a new mail file or folder. With no arguments, it -tells you which file you are currently reading. If you give -it an argument, it will write out changes (such as deletions) -you have made in the current file and read the new file. -Some special conventions are recognized for the name: -.(b -.TS -center; -c c -l a. -Name Meaning -_ -# Previous file read -% Your system mailbox -%name \fIName\fP's system mailbox -& Your ~/mbox file -+folder A file in your folder directory -.TE -.)b -\fBFolder\fP can be abbreviated to \fBfo\fP. -.ip "\fBfrom\fP\ \ " -The -.b from -command takes a list of messages and prints out the header lines for each one; -hence -.(l -from joe -.)l -is the easy way to display all the message headers from \*(lqjoe.\*(rq -\fBFrom\fP can be abbreviated to \fBf\fP. -.ip "\fBheaders\fP\ \ " -When you start up -.i Mail -to read your mail, it lists the message headers that you have. -These headers tell you who each message is from, when they were -received, how many lines and characters each message is, and the -.q "Subject:" -header field of each message, if present. In addition, -.i Mail -tags the message header of each message that has been the object -of the -.b preserve -command with a -.q P. -Messages that have been -.b saved -or -.b written -are flagged with a -.q *. -Finally, -.b deleted -messages are not printed at all. If you wish to reprint the current -list of message headers, you can do so with the -.b headers -command. The -.b headers -command (and thus the initial header listing) -only lists the first so many message headers. -The number of headers listed depends on the speed of your -terminal. -This can be overridden by specifying the number of headers you -want with the -.i window -option. -.i Mail -maintains a notion of the current -.q window -into your messages for the purposes of printing headers. -Use the -.b z -command to move forward and back a window. -You can move -.i Mail's -notion of the current window directly to a particular message by -using, for example, -.(l -headers 40 -.)l -to move -.i Mail's -attention to the messages around message 40. -If a ``+'' argument is given, then the next screenful of message headers is -printed, and if a ``\-'' argument is given, the previous screenful of message -headers is printed. -\fBHeaders\fP can be abbreviated to \fBh\fP. -.ip "\fBhelp\fP\ \ " -Print a brief and usually out of date help message about the commands -in -.i Mail . -The -.i man -page for -.i mail -is usually more up-to-date than either the help message or this manual. -It is also a synonym for \fB?\fP. -.ip "\fBhold\fP\ \ " -Arrange to hold a list of messages in the system mailbox, instead -of moving them to the file -.i mbox -in your home directory. If you set the binary option -.i hold , -this will happen by default. -It does not override the \fBdelete\fP command. -\fBHold\fP can be abbreviated to \fBho\fP. -.ip "\fBif\fP\ \ " -Commands in your -.q .mailrc -file can be executed conditionally depending on whether you are -sending or receiving mail with the -.b if -command. For example, you can do: -.(l -if receive - \fIcommands\fP... -endif -.)l -An -.b else -form is also available: -.(l -if send - \fIcommands\fP... -else - \fIcommands\fP... -endif -.)l -Note that the only allowed conditions are -.b receive -and -.b send . -.ip "\fBignore\fP \ \ " -.b N.B.: -.i Ignore -has been superseded by -.i retain. -.br -Add the list of header fields named to the -.i "ignore list" . -Header fields in the ignore list are not printed on your -terminal when you print a message. This allows you to suppress -printing of certain machine-generated header fields, such as -.i Via -which are not usually of interest. The -.b Type -and -.b Print -commands can be used to print a message in its entirety, including -ignored fields. -If -.b ignore -is executed with no arguments, it lists the current set of ignored fields. -.ip "\fBlist\fP\ \ " -List the valid -.i Mail -commands. -\fBList\fP can be abbreviated to \fBl\fP. -.\".ip \fBlocal\fP -.\"Define a list of local names for this host. This command is useful -.\"when the host is known by more than one name. Names in the list -.\"may be qualified be the domain of the host. The first name on the local -.\"list is the -.\".i distinguished -.\"name of the host. -.\"The names on the local list are used by -.\".i Mail -.\"to decide which addresses are local to the host. -.\"For example: -.\".(l -.\"local ucbarpa.BERKELEY.ARPA arpa.BERKELEY.ARPA \\ -.\" arpavax.BERKELEY.ARPA r.BERKELEY.ARPA \\ -.\" ucb-arpa.ARPA -.\".)l -.\"From this list we see that -.\".i "fred@ucbarpa.BERKELEY.ARPA", -.\".i "harold@arpa.BERKELEY", -.\"and -.\".i "larry@r" -.\"are all addresses of users on the local host. -.\"The -.\".b local -.\"command is usually not used be general users since it is designed for -.\"local configuration; it is usually found in the file /etc/mail.rc. -.ip "\fBmail\fP\ \ " -Send mail to one or more people. If you have the -.i ask -option set, -.i Mail -will prompt you for a subject to your message. Then you -can type in your message, using tilde escapes as described in -section 4 to edit, print, or modify your message. To signal your -satisfaction with the message and send it, type control-d at the -beginning of a line, or a . alone on a line if you set the option -.i dot . -To abort the message, type two interrupt characters (\s-2RUBOUT\s0 -by default) in a row or use the -.b ~q -escape. -The \fBmail\fP command can be abbreviated to \fBm\fP. -.ip "\fBmbox\fP\ \ " -Indicate that a list of messages be sent to -.i mbox -in your home directory when you quit. This is the default -action for messages if you do -.i not -have the -.i hold -option set. -.ip "\fBnext\fP or \fB+\fP\ \ " -The -.b next -command goes to the next message and types it. If given a message list, -.b next -goes to the first such message and types it. Thus, -.(l -next root -.)l -goes to the next message sent by -.q root -and types it. The -.b next -command can be abbreviated to simply a newline, which means that one -can go to and type a message by simply giving its message number or -one of the magic characters -.q "^" -.q "." -or -.q "$". -Thus, -.(l -\&. -.)l -prints the current message and -.(l -4 -.)l -prints message 4, as described previously. -\fBNext\fP can be abbreviated to \fBn\fP. -.ip "\fBpreserve\fP\ \ " -Same as -.b hold . -Cause a list of messages to be held in your system mailbox when you quit. -\fBPreserve\fP can be abbreviated to \fBpre\fP. -.ip "\fBprint\fP\ \ " -Print the specified messages. If the -.b crt -variable is set, messages longer than the number of lines it indicates -are paged through the command specified by the \fBPAGER\fP variable. -The \fBprint\fP command can be abbreviated to \fBp\fP. -.ip "\fBquit\fP\ \ " -Terminates the session, saving all undeleted, unsaved and unwritten messages -in the user's \fImbox\fP file in their login directory -(messages marked as having been read), preserving all -messages marked with \fBhold\fP or \fBpreserve\fP or never referenced -in their system mailbox. -Any messages that were deleted, saved, written or saved to \fImbox\fP are -removed from their system mailbox. -If new mail has arrived during the session, the message -``You have new mail'' is given. If given while editing a mailbox file -with the \fB\-f\fP flag, then the edit file is rewritten. -A return to the Shell is effected, unless the rewrite of edit file fails, -in which case the user can escape with the \fBexit\fP command. -\fBQuit\fP can be abbreviated to \fBq\fP. -.ip "\fBreply\fP or \fBrespond\fP\ \ " -Frame a reply to a single message. -The reply will be sent to the -person who sent you the message (to which you are replying), plus all -the people who received the original message, except you. You can -add people using the \fB~t\fP, \fB~c\fP and \fB~b\fP -tilde escapes. The subject in your reply is formed by prefacing the -subject in the original message with -.q "Re:" -unless it already began thus. -If the original message included a -.q "reply-to" -header field, the reply will go -.i only -to the recipient named by -.q "reply-to." -You type in your message using the same conventions available to you -through the -.b mail -command. -The \fBreply\fP (and \fBrespond\fP) command can be abbreviated to \fBr\fP. -.ip "\fBretain\fP\ \ " -Add the list of header fields named to the \fIretained list\fP. -Only the header fields in the retain list -are shown on your terminal when you print a message. -All other header fields are suppressed. -The -.b Type -and -.b Print -commands can be used to print a message in its entirety. -If -.b retain -is executed with no arguments, it lists the current set of -retained fields. -.ip "\fBsave\fP\ \ " -It is often useful to be able to save messages on related topics -in a file. The -.b save -command gives you the ability to do this. The -.b save -command takes as an argument a list of message numbers, followed by -the name of the file in which to save the messages. The messages -are appended to the named file, thus allowing one to keep several -messages in the file, stored in the order they were put there. -The filename in quotes, followed by the line -count and character count is echoed on the user's terminal. -An example of the -.b save -command relative to our running example is: -.(l -s 1 2 tuitionmail -.)l -.b Saved -messages are not automatically saved in -.i mbox -at quit time, nor are they selected by the -.b next -command described above, unless explicitly specified. -\fBSave\fP can be abbreviated to \fBs\fP. -.ip "\fBset\fP\ \ " -Set an option or give an option a value. Used to customize -.i Mail . -Section 5.3 contains a list of the options. Options can be -.i binary , -in which case they are -.i on -or -.i off , -or -.i valued . -To set a binary option -.i option -.i on , -do -.(l -set option -.)l -To give the valued option -.i option -the value -.i value , -do -.(l -set option=value -.)l -There must be no space before or after the ``='' sign. -If no arguments are given, all variable values are printed. -Several options can be specified in a single -.b set -command. -\fBSet\fP can be abbreviated to \fBse\fP. -.ip "\fBshell\fP\ \ " -The -.b shell -command allows you to -escape to the shell. -.b Shell -invokes an interactive shell and allows you to type commands to it. -When you leave the shell, you will return to -.i Mail . -The shell used is a default assumed by -.i Mail ; -you can override this default by setting the valued option -.q SHELL, -eg: -.(l -set SHELL=/bin/csh -.)l -\fBShell\fP can be abbreviated to \fBsh\fP. -.ip "\fBsize\fP\ \ " -Takes a message list and prints out the size in characters of each -message. -.ip "\fBsource\fP\ \ " -The -.b source -command reads -.i mail -commands from a file. It is useful when you are trying to fix your -.q .mailrc -file and you need to re-read it. -\fBSource\fP can be abbreviated to \fBso\fP. -.ip "\fBtop\fP\ \ " -The -.b top -command takes a message list and prints the first five lines -of each addressed message. -If you wish, you can change the number of lines that -.b top -prints out by setting the valued option -.q "toplines." -On a CRT terminal, -.(l -set toplines=10 -.)l -might be preferred. -\fBTop\fP can be abbreviated to \fBto\fP. -.ip "\fBtype\fP\ \ " -Same as \fBprint\fP. -Takes a message list and types out each message on the terminal. -The \fBtype\fP command can be abbreviated to \fBt\fP. -.ip "\fBundelete\fP \ \" -Takes a message list and marks each message as \fInot\fP -being deleted. -\fBUndelete\fP can be abbreviated to \fBu\fP. -.ip "\fBunread\fP\ \ " -Takes a message list and marks each message as -.i not -having been read. -\fBUnread\fP can be abbreviated to \fBU\fP. -.ip "\fBunset\fP\ \ " -Takes a list of option names and discards their remembered values; -the inverse of \fBset\fP . -.ip "\fBvisual\fP\ \ " -It is often useful to be able to invoke one of two editors, -based on the type of terminal one is using. To invoke -a display oriented editor, you can use the -.b visual -command. The operation of the -.b visual -command is otherwise identical to that of the -.b edit -command. -.ne 2v+\n(psu -.sp \n(psu -Both the -.b edit -and -.b visual -commands assume some default text editors. These default editors -can be overridden by the valued options -.q EDITOR -and -.q VISUAL -for the standard and screen editors. You might want to do: -.(l -set EDITOR=/usr/bin/ex VISUAL=/usr/bin/vi -.)l -\fBVisual\fP can be abbreviated to \fBv\fP. -.ip "\fBwrite\fP\ \ " -The -.b save -command always writes the entire message, including the headers, -into the file. If you want to write just the message itself, you -can use the -.b write -command. The -.b write -command has the same syntax as the -.b save -command, and can be abbreviated to simply -.b w . -Thus, we could write the second message by doing: -.(l -w 2 file.c -.)l -As suggested by this example, the -.b write -command is useful for such tasks as sending and receiving -source program text over the message system. -The filename in quotes, followed by the line -count and character count is echoed on the user's terminal. -.ip "\fBz\fP\ \ " -.i Mail -presents message headers in windowfuls as described under -the -.b headers -command. -You can move -.i Mail's -attention forward to the next window by giving the -.(l -z+ -.)l -command. Analogously, you can move to the previous window with: -.(l -z\- -.)l -.sh 2 "Custom options" -.pp -Throughout this manual, we have seen examples of binary and valued options. -This section describes each of the options in alphabetical order, including -some that you have not seen yet. -To avoid confusion, please note that the options are either -all lower case letters or all upper case letters. When I start a sentence -such as: -.q "Ask" -causes -.i Mail -to prompt you for a subject header, -I am only capitalizing -.q ask -as a courtesy to English. -.ip "\fBEDITOR\fP\ \ " -The valued option -.q EDITOR -defines the pathname of the text editor to be used in the -.b edit -command and ~e. If not defined, a standard editor is used. -.ip "\fBPAGER\fP\ \ " -Pathname of the program to use for paginating output when -it exceeds \fIcrt\fP lines. -A default paginator is used if this option is not defined. -.ip "\fBSHELL\fP\ \ " -The valued option -.q SHELL -gives the path name of your shell. This shell is used for the -.b ! -command and ~! escape. In addition, this shell expands -file names with shell metacharacters like * and ? in them. -.ip "\fBVISUAL\fP\ \ " -The valued option -.q VISUAL -defines the pathname of the screen editor to be used in the -.b visual -command -and ~v escape. A standard screen editor is used if you do not define one. -.ip "\fBappend\fP\ \ " -The -.q append -option is binary and -causes messages saved in -.i mbox -to be appended to the end rather than prepended. -Normally, \fIMail\fP will put messages in \fImbox\fP -in the same order that the system puts messages in your system mailbox. -By setting -.q append, -you are requesting that -.i mbox -be appended to regardless. It is in any event quicker to append. -.ip "\fBask\fP\ \ " -.q "Ask" -is a binary option which -causes -.i Mail -to prompt you for the subject of each message you send. -If you respond with simply a newline, no subject field will be sent. -.ip "\fBaskcc\fP\ \ " -.q Askcc -is a binary option which -causes you to be prompted for additional carbon copy recipients at the -end of each message. Responding with a newline shows your -satisfaction with the current list. -.ip "\fBautoprint\fP\ \ " -.q Autoprint -is a binary option which -causes the -.b delete -command to behave like -.b dp -\*- thus, after deleting a message, the next one will be typed -automatically. This is useful when quickly scanning and deleting -messages in your mailbox. -.ip "\fBcrt\fP \ \ " -The valued option -.q crt -is used as a threshold to determine how long a message must -be before -.b PAGER -is used to read it. -.ip "\fBdebug\fP \ \ " -The binary option -.q debug -causes debugging information to be displayed. Use of this -option is the same as using the \fB\-d\fP command line flag. -.ip "\fBdot\fP\ \ " -.q Dot -is a binary option which, if set, causes -.i Mail -to interpret a period alone on a line as the terminator -of the message you are sending. -.ip "\fBescape\fP\ \ " -To allow you to change the escape character used when sending -mail, you can set the valued option -.q escape. -Only the first character of the -.q escape -option is used, and it must be doubled if it is to appear as -the first character of a line of your message. If you change your escape -character, then ~ loses all its special meaning, and need no longer be doubled -at the beginning of a line. -.ip "\fBfolder\fP\ \ " -The name of the directory to use for storing folders of messages. -If this name begins with a `/' -.i Mail -considers it to be an absolute pathname; otherwise, the folder directory -is found relative to your home directory. -.ip "\fBhold\fP\ \ " -The binary option -.q hold -causes messages that have been read but not manually dealt with -to be held in the system mailbox. This prevents such messages from -being automatically swept into your \fImbox\fP file. -.ip "\fBignore\fP\ \ " -The binary option -.q ignore -causes \s-2RUBOUT\s0 characters from your terminal to be ignored and echoed -as @'s while you are sending mail. \s-2RUBOUT\s0 characters retain their -original meaning in -.i Mail -command mode. -Setting the -.q ignore -option is equivalent to supplying the -.b \-i -flag on the command line as described in section 6. -.ip "\fBignoreeof\fP\ \ " -An option related to -.q dot -is -.q ignoreeof -which makes -.i Mail -refuse to accept a control\-d as the end of a message. -.q Ignoreeof -also applies to -.i Mail -command mode. -.ip "\fBkeep\fP\ \ " -The -.q keep -option causes -.i Mail -to truncate your system mailbox instead of deleting it when it -is empty. This is useful if you elect to protect your mailbox, which -you would do with the shell command: -.(l -chmod 600 /var/mail/yourname -.)l -where -.i yourname -is your login name. If you do not do this, anyone can probably read -your mail, although people usually don't. -.ip "\fBkeepsave\fP\ \ " -When you -.b save -a message, -.i Mail -usually discards it when you -.b quit . -To retain all saved messages, set the -.q keepsave -option. -.ip "\fBmetoo\fP\ \ " -When sending mail to an alias, -.i Mail -makes sure that if you are included in the alias, that mail will not -be sent to you. This is useful if a single alias is being used by -all members of the group. If however, you wish to receive a copy of -all the messages you send to the alias, you can set the binary option -.q metoo. -.ip "\fBnoheader\fP\ \ " -The binary option -.q noheader -suppresses the printing of the version and headers when -.i Mail -is first invoked. Setting this option is the same as using -.b \-N -on the command line. -.ip "\fBnosave\fP\ \ " -Normally, -when you abort a message with two \s-2RUBOUTs\s0, -.i Mail -copies the partial letter to the file -.q dead.letter -in your home directory. Setting the binary option -.q nosave -prevents this. -.ip "\fBReplyall\fP\ \ " -Reverses the sense of -.i reply -and -.i Reply -commands. -.ip "\fBquiet\fP\ \ " -The binary option -.q quiet -suppresses the printing of the version when -.i Mail -is first invoked, -as well as printing the for example -.q "Message 4:" -from the -.b type -command. -.ip "\fBrecord\fP\ \ " -If you love to keep records, then the -valued option -.q record -can be set to the name of a file to save your outgoing mail. -Each new message you send is appended to the end of the file. -.ip "\fBscreen\fP\ \ " -When -.i Mail -initially prints the message headers, it determines the number to -print by looking at the speed of your terminal. The faster your -terminal, the more it prints. -The valued option -.q screen -overrides this calculation and -specifies how many message headers you want printed. -This number is also used for scrolling with the -.b z -command. -.ip "\fBsendmail\fP\ \ " -To use an alternate mail delivery system, set the -.q sendmail -option to the full pathname of the program to use. Note: this is not -for everyone! Most people should use the default delivery system. -.ip "\fBtoplines\fP\ \ " -The valued option -.q toplines -defines the number of lines that the -.q top -command will print out instead of the default five lines. -.ip "\fBverbose\fP\ \ " -The binary option "verbose" causes -.i Mail -to invoke sendmail with the -.b \-v -flag, which causes it to go into verbose mode and announce expansion -of aliases, etc. Setting the "verbose" option is equivalent to -invoking -.i Mail -with the -.b \-v -flag as described in section 6. diff --git a/usr.bin/mail/USD.doc/mail6.nr b/usr.bin/mail/USD.doc/mail6.nr deleted file mode 100644 index 0465a94..0000000 --- a/usr.bin/mail/USD.doc/mail6.nr +++ /dev/null @@ -1,125 +0,0 @@ -.\" Copyright (c) 1980, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)mail6.nr 8.1 (Berkeley) 6/8/93 -.\" -.bp -.sh 1 "Command line options" -.pp -This section describes command line options for -.i Mail -and what they are used for. -.ip \-N -Suppress the initial printing of headers. -.ip \-d -Turn on debugging information. Not of general interest. -.ip "\-f file\ \ " -Show the messages in -.i file -instead of your system mailbox. If -.i file -is omitted, -.i Mail -reads -.i mbox -in your home directory. -.ip \-i -Ignore tty interrupt signals. Useful on noisy phone lines, which -generate spurious RUBOUT or DELETE characters. It's usually -more effective to change your interrupt character to control\-c, -for which see the -.i stty -shell command. -.ip \-n -Inhibit reading of /etc/mail.rc. Not generally useful, since -/etc/mail.rc is usually empty. -.ip "\-s string" -Used for sending mail. -.i String -is used as the subject of the message being composed. If -.i string -contains blanks, you must surround it with quote marks. -.ip "\-u name" -Read -.i names's -mail instead of your own. Unwitting others often neglect to protect -their mailboxes, but discretion is advised. Essentially, -.b "\-u user" -is a shorthand way of doing -.b "\-f /var/mail/user". -.ip "\-v" -Use the -.b \-v -flag when invoking sendmail. This feature may also be enabled -by setting the the option "verbose". -.pp -The following command line flags are also recognized, but are -intended for use by programs invoking -.i Mail -and not for people. -.ip "\-T file" -Arrange to print on -.i file -the contents of the -.i article-id -fields of all messages that were either read or deleted. -.b \-T -is for the -.i readnews -program and should NOT be used for reading your mail. -.ip "\-h number" -Pass on hop count information. -.i Mail -will take the number, increment it, and pass it with -.b \-h -to the mail delivery system. -.b \-h -only has effect when sending mail and is used for network mail -forwarding. -.ip "\-r name" -Used for network mail forwarding: interpret -.i name -as the sender of the message. The -.i name -and -.b \-r -are simply sent along to the mail delivery system. Also, -.i Mail -will wait for the message to be sent and return the exit status. -Also restricts formatting of message. -.pp -Note that -.b \-h -and -.b \-r , -which are for network mail forwarding, are not used in practice -since mail forwarding is now handled separately. They may -disappear soon. diff --git a/usr.bin/mail/USD.doc/mail7.nr b/usr.bin/mail/USD.doc/mail7.nr deleted file mode 100644 index 0b2590b..0000000 --- a/usr.bin/mail/USD.doc/mail7.nr +++ /dev/null @@ -1,107 +0,0 @@ -.\" Copyright (c) 1980, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)mail7.nr 8.1 (Berkeley) 6/8/93 -.\" -.sh 1 "Format of messages" -.pp -This section describes the format of messages. -Messages begin with a -.i from -line, which consists of the word -.q From -followed by a user name, followed by anything, followed by -a date in the format returned by the -.i ctime -library routine described in section 3 of the Unix Programmer's -Manual. A possible -.i ctime -format date is: -.(l -Tue Dec 1 10:58:23 1981 -.)l -The -.i ctime -date may be optionally followed by a single space and a -time zone indication, which -should be three capital letters, such as PDT. -.pp -Following the -.i from -line are zero or more -.i "header field" -lines. -Each header field line is of the form: -.(l -name: information -.)l -.i Name -can be anything, but only certain header fields are recognized as -having any meaning. The recognized header fields are: -.i article-id , -.i bcc , -.i cc , -.i from , -.i reply-to , -.i sender , -.i subject , -and -.i to . -Other header fields are also significant to other systems; see, -for example, the current Arpanet message standard for much more -information on this topic. -A header field can be continued onto following lines by making the -first character on the following line a space or tab character. -.pp -If any headers are present, they must be followed by a blank line. -The part that follows is called the -.i body -of the message, and must be ASCII text, not containing null characters. -Each line in the message body must be no longer than 512 characters and -terminated with an ASCII newline character. -If binary data must be passed through the mail system, it is suggested -that this data be encoded in a system which encodes six bits into -a printable character (i.e.: uuencode). -For example, one could use the upper and lower case letters, the digits, -and the characters comma and period to make up the 64 characters. -Then, one can send a 16-bit binary number -as three characters. These characters should be packed into lines, -preferably lines about 70 characters long as long lines are transmitted -more efficiently. -.pp -The message delivery system always adds a blank line to the end of -each message. This blank line must not be deleted. -.pp -The UUCP message delivery system sometimes adds a blank line to -the end of a message each time it is forwarded through a machine. -.pp -It should be noted that some network transport protocols enforce -limits to the lengths of messages. diff --git a/usr.bin/mail/USD.doc/mail8.nr b/usr.bin/mail/USD.doc/mail8.nr deleted file mode 100644 index b09afbd..0000000 --- a/usr.bin/mail/USD.doc/mail8.nr +++ /dev/null @@ -1,75 +0,0 @@ -.\" Copyright (c) 1980, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)mail8.nr 8.1 (Berkeley) 6/8/93 -.\" -.bp -.sh 1 "Glossary" -.pp -This section contains the definitions of a few phrases -peculiar to -.i Mail . -.ip "\fIalias\fP" -An alternative name for a person or list of people. -.ip "\fIflag\fP" -An option, given on the command line of -.i Mail , -prefaced with a \-. For example, -.b \-f -is a flag. -.ip "\fIheader field\fP" -At the beginning of a message, a line which contains information -that is part of the structure of the message. Popular header fields -include -.i to , -.i cc , -and -.i subject . -.ip "\fImail\ \ \fP" -A collection of messages. Often used in the phrase, -.q "Have you read your mail?" -.ip "\fImailbox\fP" -The place where your mail is stored, typically in the directory -/var/mail. -.ip "\fImessage\fP" -A single letter from someone, initially stored in your -.i mailbox . -.ip "\fImessage list\fP" -A string used in -.i Mail -command mode to describe a sequence of messages. -.ip "\fIoption\fP" -A piece of special purpose information used to tailor -.i Mail -to your taste. -Options are specified with the -.b set -command. diff --git a/usr.bin/mail/USD.doc/mail9.nr b/usr.bin/mail/USD.doc/mail9.nr deleted file mode 100644 index 271548e..0000000 --- a/usr.bin/mail/USD.doc/mail9.nr +++ /dev/null @@ -1,203 +0,0 @@ -.\" Copyright (c) 1980, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)mail9.nr 8.1 (Berkeley) 6/8/93 -.\" -.bp -.sh 1 "Summary of commands, options, and escapes" -.pp -This section gives a quick summary of the -.i Mail -commands, binary and valued options, and tilde escapes. -.pp -The following table describes the commands: -.TS -center ; -c ci -lb l. -Command Description -_ -+ Same as \fBnext\fP -- Back up to previous message -? Print brief summary of \fIMail\fP commands -! Single command escape to shell -Print Type message with ignored fields -Reply Reply to author of message only -Respond Same as \fBReply\fP -Type Type message with ignored fields -alias Define an alias as a set of user names -alternates List other names you are known by -chdir Change working directory, home by default -copy Copy a message to a file or folder -delete Delete a list of messages -dp Same as \fBdt\fP -dt Delete current message, type next message -edit Edit a list of messages -else Start of else part of conditional; see \fBif\fP -endif End of conditional statement; see \fBif\fP -exit Leave mail without changing anything -file Interrogate/change current mail file -folder Same as \fBfile\fP -folders List the folders in your folder directory -from List headers of a list of messages -headers List current window of messages -help Same as \fB?\fP -hold Same as \fBpreserve\fP -if Conditional execution of \fIMail\fP commands -ignore Set/examine list of ignored header fields -list List valid \fIMail\fP commands -local List other names for the local host -mail Send mail to specified names -mbox Arrange to save a list of messages in \fImbox\fP -next Go to next message and type it -preserve Arrange to leave list of messages in system mailbox -print Print messages -quit Leave \fIMail\fP; update system mailbox, \fImbox\fP as appropriate -reply Compose a reply to a message -respond Same as \fBreply\fP -retain Supersedes \fBignore\fP -save Append messages, headers included, on a file -set Set binary or valued options -shell Invoke an interactive shell -size Prints out size of message list -source Read \fImail\fP commands from a file -top Print first so many (5 by default) lines of list of messages -type Same as \fBprint\fP -undelete Undelete list of messages -unread Marks list of messages as not been read -unset Undo the operation of a \fBset\fP -visual Invoke visual editor on a list of messages -write Append messages to a file, don't include headers -xit Same as \fBexit\fP -z Scroll to next/previous screenful of headers -.TE -.bp -.(b -.pp -The following table describes the options. Each option is -shown as being either a binary or valued option. -.TS -center; -c ci ci -l ci l. -Option Type Description -_ -EDITOR valued Pathname of editor for ~e and \fBedit\fP -PAGER valued Pathname of paginator for \fBPrint\fP, \fBprint\fP, \fBType\fP and \fBtype\fP -SHELL valued Pathname of shell for \fBshell\fP, ~! and \fB!\fP -VISUAL valued Pathname of screen editor for ~v, \fBvisual\fP -append binary Always append messages to end of \fImbox\fP -ask binary Prompt user for Subject: field when sending -askcc binary Prompt user for additional Cc's at end of message -autoprint binary Print next message after \fBdelete\fP -crt valued Minimum number of lines before using \fBPAGER\fP -debug binary Print out debugging information -dot binary Accept . alone on line to terminate message input -escape valued Escape character to be used instead of\ \ ~ -folder valued Directory to store folders in -hold binary Hold messages in system mailbox by default -ignore binary Ignore \s-2RUBOUT\s0 while sending mail -ignoreeof binary Don't terminate letters/command input with \fB\(uaD\fP -keep binary Don't unlink system mailbox when empty -keepsave binary Don't delete \fBsave\fPd messages by default -metoo binary Include sending user in aliases -noheader binary Suppress initial printing of version and headers -nosave binary Don't save partial letter in \fIdead.letter\fP -quiet binary Suppress printing of \fIMail\fP version and message numbers -record valued File to save all outgoing mail in -screen valued Size of window of message headers for \fBz\fP, etc. -sendmail valued Choose alternate mail delivery system -toplines valued Number of lines to print in \fBtop\fP -verbose binary Invoke sendmail with the \fB\-v\fP flag -.TE -.)b -.(b -.pp -The following table summarizes the tilde escapes available -while sending mail. -.TS -center; -c ci ci -l li l. -Escape Arguments Description -_ -~! command Execute shell command -~b name ... Add names to "blind" Cc: list -~c name ... Add names to Cc: field -~d Read \fIdead.letter\fP into message -~e Invoke text editor on partial message -~f messages Read named messages -~h Edit the header fields -~m messages Read named messages, right shift by tab -~p Print message entered so far -~q Abort entry of letter; like \s-2RUBOUT\s0 -~r filename Read file into message -~s string Set Subject: field to \fIstring\fP -~t name ... Add names to To: field -~v Invoke screen editor on message -~w filename Write message on file -~| command Pipe message through \fIcommand\fP -~: Mail command Execute a \fIMail\fP command -~~ string Quote a ~ in front of \fIstring\fP -.TE -.)b -.(b -.pp -The following table shows the command line flags that -.i Mail -accepts: -.TS -center; -c c -l a. -Flag Description -_ -\-N Suppress the initial printing of headers -\-T \fIfile\fP Article-id's of read/deleted messages to \fIfile\fP -\-d Turn on debugging -\-f \fIfile\fP Show messages in \fIfile\fP or \fI~/mbox\fP -\-h \fInumber\fP Pass on hop count for mail forwarding -\-i Ignore tty interrupt signals -\-n Inhibit reading of /etc/mail.rc -\-r \fIname\fP Pass on \fIname\fP for mail forwarding -\-s \fIstring\fP Use \fIstring\fP as subject in outgoing mail -\-u \fIname\fP Read \fIname's\fP mail instead of your own -\-v Invoke sendmail with the \fB\-v\fP flag -.TE -.)b -.lp -Notes: -.b \-T , -.b \-d , -.b \-h , -and -.b \-r -are not for human use. diff --git a/usr.bin/mail/USD.doc/maila.nr b/usr.bin/mail/USD.doc/maila.nr deleted file mode 100644 index 84b01fe..0000000 --- a/usr.bin/mail/USD.doc/maila.nr +++ /dev/null @@ -1,33 +0,0 @@ -.\" Copyright (c) 1980, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)maila.nr 8.1 (Berkeley) 6/8/93 -.\" diff --git a/usr.bin/make/PSD.doc/stubs b/usr.bin/make/PSD.doc/stubs deleted file mode 100644 index 39d8def..0000000 --- a/usr.bin/make/PSD.doc/stubs +++ /dev/null @@ -1,9 +0,0 @@ -.\" $FreeBSD$ -.\" -.de Ix -.. -.de Rd -.. -.de Rm -.. -.if n .ftr CR R diff --git a/usr.bin/make/PSD.doc/tutorial.ms b/usr.bin/make/PSD.doc/tutorial.ms deleted file mode 100644 index 320d5df..0000000 --- a/usr.bin/make/PSD.doc/tutorial.ms +++ /dev/null @@ -1,3747 +0,0 @@ -.\" Copyright (c) 1988, 1989 by Adam de Boor -.\" Copyright (c) 1989 by Berkeley Softworks -.\" Copyright (c) 1988, 1989, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" This code is derived from software contributed to Berkeley by -.\" Adam de Boor. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)tutorial.ms 8.1 (Berkeley) 8/18/93 -.\" $FreeBSD$ -.\" -.EH 'PSD:12-%''PMake \*- A Tutorial' -.OH 'PMake \*- A Tutorial''PSD:12-%' -.\" xH is a macro to provide numbered headers that are automatically stuffed -.\" into a table-of-contents, properly indented, etc. If the first argument -.\" is numeric, it is taken as the depth for numbering (as for .NH), else -.\" the default (1) is assumed. -.\" -.\" @P The initial paragraph distance. -.\" @Q The piece of section number to increment (or 0 if none given) -.\" @R Section header. -.\" @S Indent for toc entry -.\" @T Argument to NH (can't use @Q b/c giving 0 to NH resets the counter) -.de xH -.NH \\$1 -\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9 -.nr PD .1v -.XS \\n% -.ta 0.6i -\\*(SN \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9 -.XE -.nr PD .3v -.. -.ig -.\" CW is used to place a string in fixed-width or switch to a -.\" fixed-width font. -.\" C is a typewriter font for a laserwriter. Use something else if -.\" you don't have one... -.de CW -.ie !\\n(.$ .ft S -.el \&\\$3\fS\\$1\fP\\$2 -.. -.\" Anything I put in a display I want to be in fixed-width -.am DS -.CW -.. -.\" The stuff in .No produces a little stop sign in the left margin -.\" that says NOTE in it. Unfortunately, it does cause a break, but -.\" hey. Can't have everything. In case you're wondering how I came -.\" up with such weird commands, they came from running grn on a -.\" gremlin file... -.de No -.br -.ne 0.5i -.po -0.5i -.br -.mk -.nr g3 \\n(.f -.nr g4 \\n(.s -.ig ft -.sp -1 -.\" .st cf -\D's -1u'\D't 5u' -.sp -1 -\h'50u'\D'l 71u 0u'\D'l 50u 50u'\D'l 0u 71u'\D'l -50u 50u'\D'l -71u 0u'\D'l -50u -50u'\D'l 0u -71u'\D'l 50u -50u' -.sp -1 -\D't 3u' -.sp -1 -.sp 7u -\h'53u'\D'p 14 68u 0u 46u 46u 0u 68u -46u 46u -68u 0u -47u -46u 0u -68u 47u -46u' -.sp -1 -.ft R -.ps 6 -.nr g8 \\n(.d -.ds g9 "NOTE -.sp 74u -\h'85u'\v'0.85n'\h-\w\\*(g9u/2u\&\\*(g9 -.sp |\\n(g8u -.sp 166u -.ig br -\D't 3u'\D's -1u' -.br -.po -.rt -.ft \\n(g3 -.ps \\n(g4 -.. -.de Bp -.ie !\\n(.$ .IP \(bu 2 -.el .IP "\&" 2 -.. -.po +.3i -.TL -PMake \*- A Tutorial -.AU -Adam de Boor -.AI -Berkeley Softworks -2150 Shattuck Ave, Penthouse -Berkeley, CA 94704 -adam@bsw.uu.net -\&...!uunet!bsw!adam -.FS -Permission to use, copy, modify, and distribute this software and its -documentation for any purpose and without fee is hereby granted, -provided that the above copyright notice appears in all copies. -The University of California, Berkeley Softworks, and Adam de Boor make no -representations about the suitability of this software for any -purpose. It is provided "as is" without express or implied warranty. -.FE -.PP -.xH 1 Introduction -.LP -PMake is a program for creating other programs, or anything else you -can think of for it to do. The basic idea behind PMake is that, for -any given system, be it a program or a document or whatever, there -will be some files that depend on the state of other files (on when -they were last modified). PMake takes these dependencies, which you -must specify, and uses them to build whatever it is you want it to -build. -.LP -PMake is almost fully-compatible with Make, with which you may already -be familiar. PMake's most important feature is its ability to run -several different jobs at once, making the creation of systems -considerably faster. It also has a great deal more functionality than -Make. Throughout the text, whenever something is mentioned that is an -important difference between PMake and Make (i.e. something that will -cause a makefile to fail if you don't do something about it), or is -simply important, it will be flagged with a little sign in the left -margin, like this: -.No -.LP -This tutorial is divided into three main sections corresponding to basic, -intermediate and advanced PMake usage. If you already know Make well, -you will only need to skim chapter 2 (there are some aspects of -PMake that I consider basic to its use that didn't exist in Make). -Things in chapter 3 make life much easier, while those in chapter 4 -are strictly for those who know what they are doing. Chapter 5 has -definitions for the jargon I use and chapter 6 contains possible -solutions to the problems presented throughout the tutorial. -.xH 1 The Basics of PMake -.LP -PMake takes as input a file that tells a) which files depend on which -other files to be complete and b) what to do about files that are -``out-of-date.'' This file is known as a ``makefile'' and is usually -.Ix 0 def makefile -kept in the top-most directory of the system to be built. While you -can call the makefile anything you want, PMake will look for -.CW Makefile -and -.CW makefile -(in that order) in the current directory if you don't tell it -otherwise. -.Ix 0 def makefile default -To specify a different makefile, use the -.B \-f -flag (e.g. -.CW "pmake -f program.mk" ''). `` -.Ix 0 ref flags -f -.Ix 0 ref makefile other -.LP -A makefile has four different types of lines in it: -.RS -.IP \(bu 2 -File dependency specifications -.IP \(bu 2 -Creation commands -.IP \(bu 2 -Variable assignments -.IP \(bu 2 -Comments, include statements and conditional directives -.RE -.LP -Any line may be continued over multiple lines by ending it with a -backslash. -.Ix 0 def "continuation line" -The backslash, following newline and any initial whitespace -on the following line are compressed into a single space before the -input line is examined by PMake. -.xH 2 Dependency Lines -.LP -As mentioned in the introduction, in any system, there are -dependencies between the files that make up the system. For instance, -in a program made up of several C source files and one header file, -the C files will need to be re-compiled should the header file be -changed. For a document of several chapters and one macro file, the -chapters will need to be reprocessed if any of the macros changes. -.Ix 0 def "dependency" -These are dependencies and are specified by means of dependency lines in -the makefile. -.LP -.Ix 0 def "dependency line" -On a dependency line, there are targets and sources, separated by a -one- or two-character operator. -The targets ``depend'' on the sources and are usually created from -them. -.Ix 0 def target -.Ix 0 def source -.Ix 0 ref operator -Any number of targets and sources may be specified on a dependency line. -All the targets in the line are made to depend on all the sources. -Targets and sources need not be actual files, but every source must be -either an actual file or another target in the makefile. -If you run out of room, use a backslash at the end of the line to continue onto -the next one. -.LP -Any file may be a target and any file may be a source, but the -relationship between the two (or however many) is determined by the -``operator'' that separates them. -.Ix 0 def operator -Three types of operators exist: one specifies that the datedness of a -target is determined by the state of its sources, while another -specifies other files (the sources) that need to be dealt with before -the target can be re-created. The third operator is very similar to -the first, with the additional condition that the target is -out-of-date if it has no sources. These operations are represented by -the colon, the exclamation point and the double-colon, respectively, and are -mutually exclusive. Their exact semantics are as follows: -.IP ":" -.Ix 0 def operator colon -.Ix 0 def : -If a colon is used, a target on the line is considered to be -``out-of-date'' (and in need of creation) if -.RS -.IP \(bu 2 -any of the sources has been modified more recently than the target, or -.IP \(bu 2 -the target doesn't exist. -.RE -.Ix 0 def out-of-date -.IP "\&" -Under this operation, steps will be taken to re-create the target only -if it is found to be out-of-date by using these two rules. -.IP "!" -.Ix 0 def operator force -.Ix 0 def ! -If an exclamation point is used, the target will always be re-created, -but this will not happen until all of its sources have been examined -and re-created, if necessary. -.IP "::" -.Ix 0 def operator double-colon -.Ix 0 def :: -If a double-colon is used, a target is out-of-date if: -.RS -.IP \(bu 2 -any of the sources has been modified more recently than the target, or -.IP \(bu 2 -the target doesn't exist, or -.IP \(bu 2 -the target has no sources. -.RE -.IP "\&" -If the target is out-of-date according to these rules, it will be re-created. -This operator also does something else to the targets, but I'll go -into that in the next section (``Shell Commands''). -.LP -Enough words, now for an example. Take that C program I mentioned -earlier. Say there are three C files -.CW a.c , ( -.CW b.c -and -.CW c.c ) -each of which -includes the file -.CW defs.h . -The dependencies between the files could then be expressed as follows: -.DS -program : a.o b.o c.o -a.o b.o c.o : defs.h -a.o : a.c -b.o : b.c -c.o : c.c -.DE -.LP -You may be wondering at this point, where -.CW a.o , -.CW b.o -and -.CW c.o -came in and why -.I they -depend on -.CW defs.h -and the C files don't. The reason is quite simple: -.CW program -cannot be made by linking together .c files \*- it must be -made from .o files. Likewise, if you change -.CW defs.h , -it isn't the .c files that need to be re-created, it's the .o files. -If you think of dependencies in these terms \*- which files (targets) -need to be created from which files (sources) \*- you should have no problems. -.LP -An important thing to notice about the above example, is that all the -\&.o files appear as targets on more than one line. This is perfectly -all right: the target is made to depend on all the sources mentioned -on all the dependency lines. E.g. -.CW a.o -depends on both -.CW defs.h -and -.CW a.c . -.Ix 0 ref dependency -.No -.LP -The order of the dependency lines in the makefile is -important: the first target on the first dependency line in the -makefile will be the one that gets made if you don't say otherwise. -That's why -.CW program -comes first in the example makefile, above. -.LP -Both targets and sources may contain the standard C-Shell wildcard -characters -.CW { , ( -.CW } , -.CW * , -.CW ? , -.CW [ , -and -.CW ] ), -but the non-curly-brace ones may only appear in the final component -(the file portion) of the target or source. The characters mean the -following things: -.IP \fB{}\fP -These enclose a comma-separated list of options and cause the pattern -to be expanded once for each element of the list. Each expansion -contains a different element. For example, -.CW src/{whiffle,beep,fish}.c -expands to the three words -.CW src/whiffle.c , -.CW src/beep.c , -and -.CW src/fish.c . -These braces may be nested and, unlike the other wildcard characters, -the resulting words need not be actual files. All other wildcard -characters are expanded using the files that exist when PMake is -started. -.IP \fB*\fP -This matches zero or more characters of any sort. -.CW src/*.c -will expand to the same three words as above as long as -.CW src -contains those three files (and no other files that end in -.CW .c ). -.IP \fB?\fP -Matches any single character. -.IP \fB[]\fP -This is known as a character class and contains either a list of -single characters, or a series of character ranges -.CW a-z , ( -for example means all characters between a and z), or both. It matches -any single character contained in the list. E.g. -.CW [A-Za-z] -will match all letters, while -.CW [0123456789] -will match all numbers. -.xH 2 Shell Commands -.LP -``Isn't that nice,'' you say to yourself, ``but how are files -actually `re-created,' as he likes to spell it?'' -The re-creation is accomplished by commands you place in the makefile. -These commands are passed to the Bourne shell (better known as -``/bin/sh'') to be executed and are -.Ix 0 ref shell -.Ix 0 ref re-creation -.Ix 0 ref update -expected to do what's necessary to update the target file (PMake -doesn't actually check to see if the target was created. It just -assumes it's there). -.Ix 0 ref target -.LP -Shell commands in a makefile look a lot like shell commands you would -type at a terminal, with one important exception: each command in a -makefile -.I must -be preceded by at least one tab. -.LP -Each target has associated with it a shell script made up of -one or more of these shell commands. The creation script for a target -should immediately follow the dependency line for that target. While -any given target may appear on more than one dependency line, only one -of these dependency lines may be followed by a creation script, unless -the `::' operator was used on the dependency line. -.Ix 0 ref operator double-colon -.Ix 0 ref :: -.No -.LP -If the double-colon was used, each dependency line for the target -may be followed by a shell script. That script will only be executed -if the target on the associated dependency line is out-of-date with -respect to the sources on that line, according to the rules I gave -earlier. -I'll give you a good example of this later on. -.LP -To expand on the earlier makefile, you might add commands as follows: -.DS -program : a.o b.o c.o - cc a.o b.o c.o \-o program -a.o b.o c.o : defs.h -a.o : a.c - cc \-c a.c -b.o : b.c - cc \-c b.c -c.o : c.c - cc \-c c.c -.DE -.LP -Something you should remember when writing a makefile is, the -commands will be executed if the -.I target -on the dependency line is out-of-date, not the sources. -.Ix 0 ref target -.Ix 0 ref source -.Ix 0 ref out-of-date -In this example, the command -.CW "cc \-c a.c" '' `` -will be executed if -.CW a.o -is out-of-date. Because of the `:' operator, -.Ix 0 ref : -.Ix 0 ref operator colon -this means that should -.CW a.c -.I or -.CW defs.h -have been modified more recently than -.CW a.o , -the command will be executed -.CW a.o "\&" ( -will be considered out-of-date). -.Ix 0 ref out-of-date -.LP -Remember how I said the only difference between a makefile shell -command and a regular shell command was the leading tab? I lied. There -is another way in which makefile commands differ from regular ones. -The first two characters after the initial whitespace are treated -specially. -If they are any combination of `@' and `\-', they cause PMake to do -different things. -.LP -In most cases, shell commands are printed before they're -actually executed. This is to keep you informed of what's going on. If -an `@' appears, however, this echoing is suppressed. In the case of an -.CW echo -command, say -.CW "echo Linking index" ,'' `` -it would be -rather silly to see -.DS -echo Linking index -Linking index -.DE -.LP -so PMake allows you to place an `@' before the command -.CW "@echo Linking index" '') (`` -to prevent the command from being printed. -.LP -The other special character is the `\-'. In case you didn't know, -shell commands finish with a certain ``exit status.'' This status is -made available by the operating system to whatever program invoked the -command. Normally this status will be 0 if everything went ok and -non-zero if something went wrong. For this reason, PMake will consider -an error to have occurred if one of the shells it invokes returns a non-zero -status. When it detects an error, PMake's usual action is to abort -whatever it's doing and exit with a non-zero status itself (any other -targets that were being created will continue being made, but nothing -new will be started. PMake will exit after the last job finishes). -This behavior can be altered, however, by placing a `\-' at the front -of a command -.CW "\-mv index index.old" ''), (`` -certain command-line arguments, -or doing other things, to be detailed later. In such -a case, the non-zero status is simply ignored and PMake keeps chugging -along. -.No -.LP -Because all the commands are given to a single shell to execute, such -things as setting shell variables, changing directories, etc., last -beyond the command in which they are found. This also allows shell -compound commands (like -.CW for -loops) to be entered in a natural manner. -Since this could cause problems for some makefiles that depend on -each command being executed by a single shell, PMake has a -.B \-B -.Ix 0 ref compatibility -.Ix 0 ref flags -B -flag (it stands for backwards-compatible) that forces each command to -be given to a separate shell. It also does several other things, all -of which I discourage since they are now old-fashioned.\|.\|.\|. -.No -.LP -A target's shell script is fed to the shell on its (the shell's) input stream. -This means that any commands, such as -.CW ci -that need to get input from the terminal won't work right \*- they'll -get the shell's input, something they probably won't find to their -liking. A simple way around this is to give a command like this: -.DS -ci $(SRCS) < /dev/tty -.DE -This would force the program's input to come from the terminal. If you -can't do this for some reason, your only other alternative is to use -PMake in its fullest compatibility mode. See -.B Compatibility -in chapter 4. -.Ix 0 ref compatibility -.LP -.xH 2 Variables -.LP -PMake, like Make before it, has the ability to save text in variables -to be recalled later at your convenience. Variables in PMake are used -much like variables in the shell and, by tradition, consist of -all upper-case letters (you don't -.I have -to use all upper-case letters. -In fact there's nothing to stop you from calling a variable -.CW @^&$%$ . -Just tradition). Variables are assigned-to using lines of the form -.Ix 0 def variable assignment -.DS -VARIABLE = value -.DE -.Ix 0 def variable assignment -appended-to by -.DS -VARIABLE += value -.DE -.Ix 0 def variable appending -.Ix 0 def variable assignment appended -.Ix 0 def += -conditionally assigned-to (if the variable isn't already defined) by -.DS -VARIABLE ?= value -.DE -.Ix 0 def variable assignment conditional -.Ix 0 def ?= -and assigned-to with expansion (i.e. the value is expanded (see below) -before being assigned to the variable\*-useful for placing a value at -the beginning of a variable, or other things) by -.DS -VARIABLE := value -.DE -.Ix 0 def variable assignment expanded -.Ix 0 def := -.LP -Any whitespace before -.I value -is stripped off. When appending, a space is placed between the old -value and the stuff being appended. -.LP -The final way a variable may be assigned to is using -.DS -VARIABLE != shell-command -.DE -.Ix 0 def variable assignment shell-output -.Ix 0 def != -In this case, -.I shell-command -has all its variables expanded (see below) and is passed off to a -shell to execute. The output of the shell is then placed in the -variable. Any newlines (other than the final one) are replaced by -spaces before the assignment is made. This is typically used to find -the current directory via a line like: -.DS -CWD != pwd -.DE -.LP -.B Note: -this is intended to be used to execute commands that produce small amounts -of output (e.g. ``pwd''). The implementation is less than intelligent and will -likely freeze if you execute something that produces thousands of -bytes of output (8 Kb is the limit on many UNIX systems). -.LP -The value of a variable may be retrieved by enclosing the variable -name in parentheses or curly braces and preceding the whole thing -with a dollar sign. -.LP -For example, to set the variable CFLAGS to the string -.CW "\-I/sprite/src/lib/libc \-O" ,'' `` -you would place a line -.DS -CFLAGS = \-I/sprite/src/lib/libc \-O -.DE -in the makefile and use the word -.CW "$(CFLAGS)" -wherever you would like the string -.CW "\-I/sprite/src/lib/libc \-O" -to appear. This is called variable expansion. -.Ix 0 def variable expansion -.No -.LP -Unlike Make, PMake will not expand a variable unless it knows -the variable exists. E.g. if you have a -.CW "${i}" -in a shell command and you have not assigned a value to the variable -.CW i -(the empty string is considered a value, by the way), where Make would have -substituted the empty string, PMake will leave the -.CW "${i}" -alone. -To keep PMake from substituting for a variable it knows, precede the -dollar sign with another dollar sign. -(e.g. to pass -.CW "${HOME}" -to the shell, use -.CW "$${HOME}" ). -This causes PMake, in effect, to expand the -.CW $ -macro, which expands to a single -.CW $ . -For compatibility, Make's style of variable expansion will be used -if you invoke PMake with any of the compatibility flags (\c -.B \-V , -.B \-B -or -.B \-M . -The -.B \-V -flag alters just the variable expansion). -.Ix 0 ref flags -V -.Ix 0 ref flags -B -.Ix 0 ref flags -M -.Ix 0 ref compatibility -.LP -.Ix 0 ref variable expansion -There are two different times at which variable expansion occurs: -When parsing a dependency line, the expansion occurs immediately -upon reading the line. If any variable used on a dependency line is -undefined, PMake will print a message and exit. -Variables in shell commands are expanded when the command is -executed. -Variables used inside another variable are expanded whenever the outer -variable is expanded (the expansion of an inner variable has no effect -on the outer variable. I.e. if the outer variable is used on a dependency -line and in a shell command, and the inner variable changes value -between when the dependency line is read and the shell command is -executed, two different values will be substituted for the outer -variable). -.Ix 0 def variable types -.LP -Variables come in four flavors, though they are all expanded the same -and all look about the same. They are (in order of expanding scope): -.RS -.IP \(bu 2 -Local variables. -.Ix 0 ref variable local -.IP \(bu 2 -Command-line variables. -.Ix 0 ref variable command-line -.IP \(bu 2 -Global variables. -.Ix 0 ref variable global -.IP \(bu 2 -Environment variables. -.Ix 0 ref variable environment -.RE -.LP -The classification of variables doesn't matter much, except that the -classes are searched from the top (local) to the bottom (environment) -when looking up a variable. The first one found wins. -.xH 3 Local Variables -.LP -.Ix 0 def variable local -Each target can have as many as seven local variables. These are -variables that are only ``visible'' within that target's shell script -and contain such things as the target's name, all of its sources (from -all its dependency lines), those sources that were out-of-date, etc. -Four local variables are defined for all targets. They are: -.RS -.IP ".TARGET" -.Ix 0 def variable local .TARGET -.Ix 0 def .TARGET -The name of the target. -.IP ".OODATE" -.Ix 0 def variable local .OODATE -.Ix 0 def .OODATE -The list of the sources for the target that were considered out-of-date. -The order in the list is not guaranteed to be the same as the order in -which the dependencies were given. -.IP ".ALLSRC" -.Ix 0 def variable local .ALLSRC -.Ix 0 def .ALLSRC -The list of all sources for this target in the order in which they -were given. -.IP ".PREFIX" -.Ix 0 def variable local .PREFIX -.Ix 0 def .PREFIX -The target without its suffix and without any leading path. E.g. for -the target -.CW ../../lib/compat/fsRead.c , -this variable would contain -.CW fsRead . -.RE -.LP -Three other local variables are set only for certain targets under -special circumstances. These are the ``.IMPSRC,'' -.Ix 0 ref variable local .IMPSRC -.Ix 0 ref .IMPSRC -``.ARCHIVE,'' -.Ix 0 ref variable local .ARCHIVE -.Ix 0 ref .ARCHIVE -and ``.MEMBER'' -.Ix 0 ref variable local .MEMBER -.Ix 0 ref .MEMBER -variables. When they are set and how they are used is described later. -.LP -Four of these variables may be used in sources as well as in shell -scripts. -.Ix 0 def "dynamic source" -.Ix 0 def source dynamic -These are ``.TARGET'', ``.PREFIX'', ``.ARCHIVE'' and ``.MEMBER''. The -variables in the sources are expanded once for each target on the -dependency line, providing what is known as a ``dynamic source,'' -.Rd 0 -allowing you to specify several dependency lines at once. For example, -.DS -$(OBJS) : $(.PREFIX).c -.DE -will create a dependency between each object file and its -corresponding C source file. -.xH 3 Command-line Variables -.LP -.Ix 0 def variable command-line -Command-line variables are set when PMake is first invoked by giving a -variable assignment as one of the arguments. For example, -.DS -pmake "CFLAGS = -I/sprite/src/lib/libc -O" -.DE -would make -.CW CFLAGS -be a command-line variable with the given value. Any assignments to -.CW CFLAGS -in the makefile will have no effect, because once it -is set, there is (almost) nothing you can do to change a command-line -variable (the search order, you see). Command-line variables may be -set using any of the four assignment operators, though only -.CW = -and -.CW ?= -behave as you would expect them to, mostly because assignments to -command-line variables are performed before the makefile is read, thus -the values set in the makefile are unavailable at the time. -.CW += -.Ix 0 ref += -.Ix 0 ref variable assignment appended -is the same as -.CW = , -because the old value of the variable is sought only in the scope in -which the assignment is taking place (for reasons of efficiency that I -won't get into here). -.CW := -and -.CW ?= -.Ix 0 ref := -.Ix 0 ref ?= -.Ix 0 ref variable assignment expanded -.Ix 0 ref variable assignment conditional -will work if the only variables used are in the environment. -.CW != -is sort of pointless to use from the command line, since the same -effect can no doubt be accomplished using the shell's own command -substitution mechanisms (backquotes and all that). -.xH 3 Global Variables -.LP -.Ix 0 def variable global -Global variables are those set or appended-to in the makefile. -There are two classes of global variables: those you set and those PMake sets. -As I said before, the ones you set can have any name you want them to have, -except they may not contain a colon or an exclamation point. -The variables PMake sets (almost) always begin with a -period and always contain upper-case letters, only. The variables are -as follows: -.RS -.IP .PMAKE -.Ix 0 def variable global .PMAKE -.Ix 0 def .PMAKE -.Ix 0 def variable global MAKE -.Ix 0 def MAKE -The name by which PMake was invoked is stored in this variable. For -compatibility, the name is also stored in the MAKE variable. -.IP .MAKEFLAGS -.Ix 0 def variable global .MAKEFLAGS -.Ix 0 def .MAKEFLAGS variable -.Ix 0 def variable global MFLAGS -.Ix 0 def MFLAGS -All the relevant flags with which PMake was invoked. This does not -include such things as -.B \-f -or variable assignments. Again for compatibility, this value is stored -in the MFLAGS variable as well. -.RE -.LP -Two other variables, ``.INCLUDES'' and ``.LIBS,'' are covered in the -section on special targets in chapter 3. -.Ix 0 ref variable global .INCLUDES -.Ix 0 ref variable global .LIBS -.LP -Global variables may be deleted using lines of the form: -.Ix 0 def #undef -.Ix 0 def variable deletion -.DS -#undef \fIvariable\fP -.DE -The -.CW # ' ` -must be the first character on the line. Note that this may only be -done on global variables. -.xH 3 Environment Variables -.LP -.Ix 0 def variable environment -Environment variables are passed by the shell that invoked PMake and -are given by PMake to each shell it invokes. They are expanded like -any other variable, but they cannot be altered in any way. -.LP -One special environment variable, -.CW PMAKE , -.Ix 0 def variable environment PMAKE -is examined by PMake for command-line flags, variable assignments, -etc., it should always use. This variable is examined before the -actual arguments to PMake are. In addition, all flags given to PMake, -either through the -.CW PMAKE -variable or on the command line, are placed in this environment -variable and exported to each shell PMake executes. Thus recursive -invocations of PMake automatically receive the same flags as the -top-most one. -.LP -Using all these variables, you can compress the sample makefile even more: -.DS -OBJS = a.o b.o c.o -program : $(OBJS) - cc $(.ALLSRC) \-o $(.TARGET) -$(OBJS) : defs.h -a.o : a.c - cc \-c a.c -b.o : b.c - cc \-c b.c -c.o : c.c - cc \-c c.c -.DE -.Ix 0 ref variable local .ALLSRC -.Ix 0 ref .ALLSRC -.Ix 0 ref variable local .TARGET -.Ix 0 ref .TARGET -.Rd 3 -.xH 2 Comments -.LP -.Ix 0 def comments -Comments in a makefile start with a `#' character and extend to the -end of the line. They may appear -anywhere you want them, except in a shell command (though the shell -will treat it as a comment, too). If, for some reason, you need to use the `#' -in a variable or on a dependency line, put a backslash in front of it. -PMake will compress the two into a single `#' (Note: this isn't true -if PMake is operating in full-compatibility mode). -.Ix 0 ref flags -M -.Ix 0 ref compatibility -.xH 2 Parallelism -.No -.LP -PMake was specifically designed to re-create several targets at once, -when possible. You do not have to do anything special to cause this to -happen (unless PMake was configured to not act in parallel, in which -case you will have to make use of the -.B \-L -and -.B \-J -flags (see below)), -.Ix 0 ref flags -L -.Ix 0 ref flags -J -but you do have to be careful at times. -.LP -There are several problems you are likely to encounter. One is -that some makefiles (and programs) are written in such a way that it is -impossible for two targets to be made at once. The program -.CW xstr , -for example, -always modifies the files -.CW strings -and -.CW x.c . -There is no way to change it. Thus you cannot run two of them at once -without something being trashed. Similarly, if you have commands -in the makefile that always send output to the same file, you will not -be able to make more than one target at once unless you change the -file you use. You can, for instance, add a -.CW $$$$ -to the end of the file name to tack on the process ID of the shell -executing the command (each -.CW $$ -expands to a single -.CW $ , -thus giving you the shell variable -.CW $$ ). -Since only one shell is used for all the -commands, you'll get the same file name for each command in the -script. -.LP -The other problem comes from improperly-specified dependencies that -worked in Make because of its sequential, depth-first way of examining -them. While I don't want to go into depth on how PMake -works (look in chapter 4 if you're interested), I will warn you that -files in two different ``levels'' of the dependency tree may be -examined in a different order in PMake than they were in Make. For -example, given the makefile -.DS -a : b c -b : d -.DE -PMake will examine the targets in the order -.CW c , -.CW d , -.CW b , -.CW a . -If the makefile's author expected PMake to abort before making -.CW c -if an error occurred while making -.CW b , -or if -.CW b -needed to exist before -.CW c -was made, -s/he will be sorely disappointed. The dependencies are -incomplete, since in both these cases, -.CW c -would depend on -.CW b . -So watch out. -.LP -Another problem you may face is that, while PMake is set up to handle the -output from multiple jobs in a graceful fashion, the same is not so for input. -It has no way to regulate input to different jobs, -so if you use the redirection from -.CW /dev/tty -I mentioned earlier, you must be careful not to run two of the jobs at once. -.xH 2 Writing and Debugging a Makefile -.LP -Now you know most of what's in a makefile, what do you do next? There -are two choices: (1) use one of the uncommonly-available makefile -generators or (2) write your own makefile (I leave out the third choice of -ignoring PMake and doing everything by hand as being beyond the bounds -of common sense). -.LP -When faced with the writing of a makefile, it is usually best to start -from first principles: just what -.I are -you trying to do? What do you want the makefile finally to produce? -.LP -To begin with a somewhat traditional example, let's say you need to -write a makefile to create a program, -.CW expr , -that takes standard infix expressions and converts them to prefix form (for -no readily apparent reason). You've got three source files, in C, that -make up the program: -.CW main.c , -.CW parse.c , -and -.CW output.c . -Harking back to my pithy advice about dependency lines, you write the -first line of the file: -.DS -expr : main.o parse.o output.o -.DE -because you remember -.CW expr -is made from -.CW .o -files, not -.CW .c -files. Similarly for the -.CW .o -files you produce the lines: -.DS -main.o : main.c -parse.o : parse.c -output.o : output.c -main.o parse.o output.o : defs.h -.DE -.LP -Great. You've now got the dependencies specified. What you need now is -commands. These commands, remember, must produce the target on the -dependency line, usually by using the sources you've listed. -You remember about local variables? Good, so it should come -to you as no surprise when you write -.DS -expr : main.o parse.o output.o - cc -o $(.TARGET) $(.ALLSRC) -.DE -Why use the variables? If your program grows to produce postfix -expressions too (which, of course, requires a name change or two), it -is one fewer place you have to change the file. You cannot do this for -the object files, however, because they depend on their corresponding -source files -.I and -.CW defs.h , -thus if you said -.DS - cc -c $(.ALLSRC) -.DE -you'd get (for -.CW main.o ): -.DS - cc -c main.c defs.h -.DE -which is wrong. So you round out the makefile with these lines: -.DS -main.o : main.c - cc -c main.c -parse.o : parse.c - cc -c parse.c -output.o : output.c - cc -c output.c -.DE -.LP -The makefile is now complete and will, in fact, create the program you -want it to without unnecessary compilations or excessive typing on -your part. There are two things wrong with it, however (aside from it -being altogether too long, something I'll address in chapter 3): -.IP 1) -The string -.CW "main.o parse.o output.o" '' `` -is repeated twice, necessitating two changes when you add postfix -(you were planning on that, weren't you?). This is in direct violation -of de Boor's First Rule of writing makefiles: -.QP -.I -Anything that needs to be written more than once -should be placed in a variable. -.IP "\&" -I cannot emphasize this enough as being very important to the -maintenance of a makefile and its program. -.IP 2) -There is no way to alter the way compilations are performed short of -editing the makefile and making the change in all places. This is evil -and violates de Boor's Second Rule, which follows directly from the -first: -.QP -.I -Any flags or programs used inside a makefile should be placed in a variable so -they may be changed, temporarily or permanently, with the greatest ease. -.LP -The makefile should more properly read: -.DS -OBJS = main.o parse.o output.o -expr : $(OBJS) - $(CC) $(CFLAGS) -o $(.TARGET) $(.ALLSRC) -main.o : main.c - $(CC) $(CFLAGS) -c main.c -parse.o : parse.c - $(CC) $(CFLAGS) -c parse.c -output.o : output.c - $(CC) $(CFLAGS) -c output.c -$(OBJS) : defs.h -.DE -Alternatively, if you like the idea of dynamic sources mentioned in -section 2.3.1, -.Rm 0 2.3.1 -.Rd 4 -.Ix 0 ref "dynamic source" -.Ix 0 ref source dynamic -you could write it like this: -.DS -OBJS = main.o parse.o output.o -expr : $(OBJS) - $(CC) $(CFLAGS) -o $(.TARGET) $(.ALLSRC) -$(OBJS) : $(.PREFIX).c defs.h - $(CC) $(CFLAGS) -c $(.PREFIX).c -.DE -These two rules and examples lead to de Boor's First Corollary: -.QP -.I -Variables are your friends. -.LP -Once you've written the makefile comes the sometimes-difficult task of -.Ix 0 ref debugging -making sure the darn thing works. Your most helpful tool to make sure -the makefile is at least syntactically correct is the -.B \-n -.Ix 0 ref flags -n -flag, which allows you to see if PMake will choke on the makefile. The -second thing the -.B \-n -flag lets you do is see what PMake would do without it actually doing -it, thus you can make sure the right commands would be executed were -you to give PMake its head. -.LP -When you find your makefile isn't behaving as you hoped, the first -question that comes to mind (after ``What time is it, anyway?'') is -``Why not?'' In answering this, two flags will serve you well: -.CW "-d m" '' `` -.Ix 0 ref flags -d -and -.CW "-p 2" .'' `` -.Ix 0 ref flags -p -The first causes PMake to tell you as it examines each target in the -makefile and indicate why it is deciding whatever it is deciding. You -can then use the information printed for other targets to see where -you went wrong. The -.CW "-p 2" '' `` -flag makes PMake print out its internal state when it is done, -allowing you to see that you forgot to make that one chapter depend on -that file of macros you just got a new version of. The output from -.CW "-p 2" '' `` -is intended to resemble closely a real makefile, but with additional -information provided and with variables expanded in those commands -PMake actually printed or executed. -.LP -Something to be especially careful about is circular dependencies. -.Ix 0 def dependency circular -E.g. -.DS -a : b -b : c d -d : a -.DE -In this case, because of how PMake works, -.CW c -is the only thing PMake will examine, because -.CW d -and -.CW a -will effectively fall off the edge of the universe, making it -impossible to examine -.CW b -(or them, for that matter). -PMake will tell you (if run in its normal mode) all the targets -involved in any cycle it looked at (i.e. if you have two cycles in the -graph (naughty, naughty), but only try to make a target in one of -them, PMake will only tell you about that one. You'll have to try to -make the other to find the second cycle). When run as Make, it will -only print the first target in the cycle. -.xH 2 Invoking PMake -.LP -.Ix 0 ref flags -.Ix 0 ref arguments -.Ix 0 ref usage -PMake comes with a wide variety of flags to choose from. -They may appear in any order, interspersed with command-line variable -assignments and targets to create. -The flags are as follows: -.IP "\fB\-d\fP \fIwhat\fP" -.Ix 0 def flags -d -.Ix 0 ref debugging -This causes PMake to spew out debugging information that -may prove useful to you. If you can't -figure out why PMake is doing what it's doing, you might try using -this flag. The -.I what -parameter is a string of single characters that tell PMake what -aspects you are interested in. Most of what I describe will make -little sense to you, unless you've dealt with Make before. Just -remember where this table is and come back to it as you read on. -The characters and the information they produce are as follows: -.RS -.IP a -Archive searching and caching. -.IP c -Conditional evaluation. -.IP d -The searching and caching of directories. -.IP j -Various snippets of information related to the running of the multiple -shells. Not particularly interesting. -.IP m -The making of each target: what target is being examined; when it was -last modified; whether it is out-of-date; etc. -.IP p -Makefile parsing. -.IP r -Remote execution. -.IP s -The application of suffix-transformation rules. (See chapter 3) -.IP t -The maintenance of the list of targets. -.IP v -Variable assignment. -.RE -.IP "\&" -Of these all, the -.CW m -and -.CW s -letters will be most useful to you. -If the -.B \-d -is the final argument or the argument from which it would get these -key letters (see below for a note about which argument would be used) -begins with a -.B \- , -all of these debugging flags will be set, resulting in massive amounts -of output. -.IP "\fB\-f\fP \fImakefile\fP" -.Ix 0 def flags -f -Specify a makefile to read different from the standard makefiles -.CW Makefile "\&" ( -or -.CW makefile ). -.Ix 0 ref makefile default -.Ix 0 ref makefile other -If -.I makefile -is ``\-'', PMake uses the standard input. This is useful for making -quick and dirty makefiles.\|.\|. -.Ix 0 ref makefile "quick and dirty" -.IP \fB\-h\fP -.Ix 0 def flags -h -Prints out a summary of the various flags PMake accepts. It can also -be used to find out what level of concurrency was compiled into the -version of PMake you are using (look at -.B \-J -and -.B \-L ) -and various other information on how PMake was configured. -.Ix 0 ref configuration -.Ix 0 ref makefilesystem -.IP \fB\-i\fP -.Ix 0 def flags -i -If you give this flag, PMake will ignore non-zero status returned -by any of its shells. It's like placing a `\-' before all the commands -in the makefile. -.IP \fB\-k\fP -.Ix 0 def flags -k -This is similar to -.B \-i -in that it allows PMake to continue when it sees an error, but unlike -.B \-i , -where PMake continues blithely as if nothing went wrong, -.B \-k -causes it to recognize the error and only continue work on those -things that don't depend on the target, either directly or indirectly (through -depending on something that depends on it), whose creation returned the error. -The `k' is for ``keep going''.\|.\|. -.Ix 0 ref target -.IP \fB\-l\fP -.Ix 0 def flags -l -PMake has the ability to lock a directory against other -people executing it in the same directory (by means of a file called -``LOCK.make'' that it creates and checks for in the directory). This -is a Good Thing because two people doing the same thing in the same place -can be disastrous for the final product (too many cooks and all that). -Whether this locking is the default is up to your system -administrator. If locking is on, -.B \-l -will turn it off, and vice versa. Note that this locking will not -prevent \fIyou\fP from invoking PMake twice in the same place \*- if -you own the lock file, PMake will warn you about it but continue to execute. -.IP "\fB\-m\fP \fIdirectory\fP" -.Ix 0 def flags -m -Tells PMake another place to search for included makefiles via the <...> -style. Several -.B \-m -options can be given to form a search path. If this construct is used the -default system makefile search path is completely overridden. -To be explained in chapter 3, section 3.2. -.Rm 2 3.2 -.IP \fB\-n\fP -.Ix 0 def flags -n -This flag tells PMake not to execute the commands needed to update the -out-of-date targets in the makefile. Rather, PMake will simply print -the commands it would have executed and exit. This is particularly -useful for checking the correctness of a makefile. If PMake doesn't do -what you expect it to, it's a good chance the makefile is wrong. -.IP "\fB\-p\fP \fInumber\fP" -.Ix 0 def flags -p -.Ix 0 ref debugging -This causes PMake to print its input in a reasonable form, though -not necessarily one that would make immediate sense to anyone but me. The -.I number -is a bitwise-or of 1 and 2 where 1 means it should print the input -before doing any processing and 2 says it should print it after -everything has been re-created. Thus -.CW "\-p 3" -would print it twice\*-once before processing and once after (you -might find the difference between the two interesting). This is mostly -useful to me, but you may find it informative in some bizarre circumstances. -.IP \fB\-q\fP -.Ix 0 def flags -q -If you give PMake this flag, it will not try to re-create anything. It -will just see if anything is out-of-date and exit non-zero if so. -.IP \fB\-r\fP -.Ix 0 def flags -r -When PMake starts up, it reads a default makefile that tells it what -sort of system it's on and gives it some idea of what to do if you -don't tell it anything. I'll tell you about it in chapter 3. If you -give this flag, PMake won't read the default makefile. -.IP \fB\-s\fP -.Ix 0 def flags -s -This causes PMake to not print commands before they're executed. It -is the equivalent of putting an `@' before every command in the -makefile. -.IP \fB\-t\fP -.Ix 0 def flags -t -Rather than try to re-create a target, PMake will simply ``touch'' it -so as to make it appear up-to-date. If the target didn't exist before, -it will when PMake finishes, but if the target did exist, it will -appear to have been updated. -.IP \fB\-v\fP -.Ix 0 def flags -v -This is a mixed-compatibility flag intended to mimic the System V -version of Make. It is the same as giving -.B \-B , -and -.B \-V -as well as turning off directory locking. Targets can still be created -in parallel, however. This is the mode PMake will enter if it is -invoked either as -.CW smake '' `` -or -.CW vmake ''. `` -.IP \fB\-x\fP -.Ix 0 def flags -x -This tells PMake it's ok to export jobs to other machines, if they're -available. It is used when running in Make mode, as exporting in this -mode tends to make things run slower than if the commands were just -executed locally. -.IP \fB\-B\fP -.Ix 0 ref compatibility -.Ix 0 def flags -B -Forces PMake to be as backwards-compatible with Make as possible while -still being itself. -This includes: -.RS -.IP \(bu 2 -Executing one shell per shell command -.IP \(bu 2 -Expanding anything that looks even vaguely like a variable, with the -empty string replacing any variable PMake doesn't know. -.IP \(bu 2 -Refusing to allow you to escape a `#' with a backslash. -.IP \(bu 2 -Permitting undefined variables on dependency lines and conditionals -(see below). Normally this causes PMake to abort. -.RE -.IP \fB\-C\fP -.Ix 0 def flags -C -This nullifies any and all compatibility mode flags you may have given -or implied up to the time the -.B \-C -is encountered. It is useful mostly in a makefile that you wrote for PMake -to avoid bad things happening when someone runs PMake as -.CW make '' `` -or has things set in the environment that tell it to be compatible. -.B \-C -is -.I not -placed in the -.CW PMAKE -environment variable or the -.CW .MAKEFLAGS -or -.CW MFLAGS -global variables. -.Ix 0 ref variable environment PMAKE -.Ix 0 ref variable global .MAKEFLAGS -.Ix 0 ref variable global MFLAGS -.Ix 0 ref .MAKEFLAGS variable -.Ix 0 ref MFLAGS -.IP "\fB\-D\fP \fIvariable\fP" -.Ix 0 def flags -D -Allows you to define a variable to have -.CW 1 '' `` -as its value. The variable is a global variable, not a command-line -variable. This is useful mostly for people who are used to the C -compiler arguments and those using conditionals, which I'll get into -in section 4.3 -.Rm 1 4.3 -.IP "\fB\-I\fP \fIdirectory\fP" -.Ix 0 def flags -I -Tells PMake another place to search for included makefiles. Yet -another thing to be explained in chapter 3 (section 3.2, to be -precise). -.Rm 2 3.2 -.IP "\fB\-J\fP \fInumber\fP" -.Ix 0 def flags -J -Gives the absolute maximum number of targets to create at once on both -local and remote machines. -.IP "\fB\-L\fP \fInumber\fP" -.Ix 0 def flags -L -This specifies the maximum number of targets to create on the local -machine at once. This may be 0, though you should be wary of doing -this, as PMake may hang until a remote machine becomes available, if -one is not available when it is started. -.IP \fB\-M\fP -.Ix 0 ref compatibility -.Ix 0 def flags -M -This is the flag that provides absolute, complete, full compatibility -with Make. It still allows you to use all but a few of the features of -PMake, but it is non-parallel. This is the mode PMake enters if you -call it -.CW make .'' `` -.IP \fB\-P\fP -.Ix 0 def flags -P -.Ix 0 ref "output control" -When creating targets in parallel, several shells are executing at -once, each wanting to write its own two cent's-worth to the screen. -This output must be captured by PMake in some way in order to prevent -the screen from being filled with garbage even more indecipherable -than you usually see. PMake has two ways of doing this, one of which -provides for much cleaner output and a clear separation between the -output of different jobs, the other of which provides a more immediate -response so one can tell what is really happening. The former is done -by notifying you when the creation of a target starts, capturing the -output and transferring it to the screen all at once when the job -finishes. The latter is done by catching the output of the shell (and -its children) and buffering it until an entire line is received, then -printing that line preceded by an indication of which job produced -the output. Since I prefer this second method, it is the one used by -default. The first method will be used if you give the -.B \-P -flag to PMake. -.IP \fB\-V\fP -.Ix 0 def flags -V -As mentioned before, the -.B \-V -flag tells PMake to use Make's style of expanding variables, -substituting the empty string for any variable it doesn't know. -.IP \fB\-W\fP -.Ix 0 def flags -W -There are several times when PMake will print a message at you that is -only a warning, i.e. it can continue to work in spite of your having -done something silly (such as forgotten a leading tab for a shell -command). Sometimes you are well aware of silly things you have done -and would like PMake to stop bothering you. This flag tells it to shut -up about anything non-fatal. -.IP \fB\-X\fP -.Ix 0 def flags -X -This flag causes PMake to not attempt to export any jobs to another -machine. -.LP -Several flags may follow a single `\-'. Those flags that require -arguments take them from successive parameters. E.g. -.DS -pmake -fDnI server.mk DEBUG /chip2/X/server/include -.DE -will cause PMake to read -.CW server.mk -as the input makefile, define the variable -.CW DEBUG -as a global variable and look for included makefiles in the directory -.CW /chip2/X/server/include . -.xH 2 Summary -.LP -A makefile is made of four types of lines: -.RS -.IP \(bu 2 -Dependency lines -.IP \(bu 2 -Creation commands -.IP \(bu 2 -Variable assignments -.IP \(bu 2 -Comments, include statements and conditional directives -.RE -.LP -A dependency line is a list of one or more targets, an operator -.CW : ', (` -.CW :: ', ` -or -.CW ! '), ` -and a list of zero or more sources. Sources may contain wildcards and -certain local variables. -.LP -A creation command is a regular shell command preceded by a tab. In -addition, if the first two characters after the tab (and other -whitespace) are a combination of -.CW @ ' ` -or -.CW - ', ` -PMake will cause the command to not be printed (if the character is -.CW @ ') ` -or errors from it to be ignored (if -.CW - '). ` -A blank line, dependency line or variable assignment terminates a -creation script. There may be only one creation script for each target -with a -.CW : ' ` -or -.CW ! ' ` -operator. -.LP -Variables are places to store text. They may be unconditionally -assigned-to using the -.CW = ' ` -.Ix 0 ref = -.Ix 0 ref variable assignment -operator, appended-to using the -.CW += ' ` -.Ix 0 ref += -.Ix 0 ref variable assignment appended -operator, conditionally (if the variable is undefined) assigned-to -with the -.CW ?= ' ` -.Ix 0 ref ?= -.Ix 0 ref variable assignment conditional -operator, and assigned-to with variable expansion with the -.CW := ' ` -.Ix 0 ref := -.Ix 0 ref variable assignment expanded -operator. The output of a shell command may be assigned to a variable -using the -.CW != ' ` -.Ix 0 ref != -.Ix 0 ref variable assignment shell-output -operator. Variables may be expanded (their value inserted) by enclosing -their name in parentheses or curly braces, preceded by a dollar sign. -A dollar sign may be escaped with another dollar sign. Variables are -not expanded if PMake doesn't know about them. There are seven local -variables: -.CW .TARGET , -.CW .ALLSRC , -.CW .OODATE , -.CW .PREFIX , -.CW .IMPSRC , -.CW .ARCHIVE , -and -.CW .MEMBER . -Four of them -.CW .TARGET , ( -.CW .PREFIX , -.CW .ARCHIVE , -and -.CW .MEMBER ) -may be used to specify ``dynamic sources.'' -.Ix 0 ref "dynamic source" -.Ix 0 ref source dynamic -Variables are good. Know them. Love them. Live them. -.LP -Debugging of makefiles is best accomplished using the -.B \-n , -.B "\-d m" , -and -.B "\-p 2" -flags. -.xH 2 Exercises -.ce -\s+4\fBTBA\fP\s0 -.xH 1 Short-cuts and Other Nice Things -.LP -Based on what I've told you so far, you may have gotten the impression -that PMake is just a way of storing away commands and making sure you -don't forget to compile something. Good. That's just what it is. -However, the ways I've described have been inelegant, at best, and -painful, at worst. -This chapter contains things that make the -writing of makefiles easier and the makefiles themselves shorter and -easier to modify (and, occasionally, simpler). In this chapter, I -assume you are somewhat more -familiar with Sprite (or UNIX, if that's what you're using) than I did -in chapter 2, just so you're on your toes. -So without further ado... -.xH 2 Transformation Rules -.LP -As you know, a file's name consists of two parts: a base name, which -gives some hint as to the contents of the file, and a suffix, which -usually indicates the format of the file. -Over the years, as -.UX -has developed, -naming conventions, with regard to suffixes, have also developed that have -become almost as incontrovertible as Law. E.g. a file ending in -.CW .c -is assumed to contain C source code; one with a -.CW .o -suffix is assumed to be a compiled, relocatable object file that may -be linked into any program; a file with a -.CW .ms -suffix is usually a text file to be processed by Troff with the \-ms -macro package, and so on. -One of the best aspects of both Make and PMake comes from their -understanding of how the suffix of a file pertains to its contents and -their ability to do things with a file based solely on its suffix. This -ability comes from something known as a transformation rule. A -transformation rule specifies how to change a file with one suffix -into a file with another suffix. -.LP -A transformation rule looks much like a dependency line, except the -target is made of two known suffixes stuck together. Suffixes are made -known to PMake by placing them as sources on a dependency line whose -target is the special target -.CW .SUFFIXES . -E.g. -.DS -\&.SUFFIXES : .o .c -\&.c.o : - $(CC) $(CFLAGS) -c $(.IMPSRC) -.DE -The creation script attached to the target is used to transform a file with -the first suffix (in this case, -.CW .c ) -into a file with the second suffix (here, -.CW .o ). -In addition, the target inherits whatever attributes have been applied -to the transformation rule. -The simple rule given above says that to transform a C source file -into an object file, you compile it using -.CW cc -with the -.CW \-c -flag. -This rule is taken straight from the system makefile. Many -transformation rules (and suffixes) are defined there, and I refer you -to it for more examples (type -.CW "pmake -h" '' `` -to find out where it is). -.LP -There are several things to note about the transformation rule given -above: -.RS -.IP 1) -The -.CW .IMPSRC -variable. -.Ix 0 def variable local .IMPSRC -.Ix 0 def .IMPSRC -This variable is set to the ``implied source'' (the file from which -the target is being created; the one with the first suffix), which, in this -case, is the .c file. -.IP 2) -The -.CW CFLAGS -variable. Almost all of the transformation rules in the system -makefile are set up using variables that you can alter in your -makefile to tailor the rule to your needs. In this case, if you want -all your C files to be compiled with the -.B \-g -flag, to provide information for -.CW dbx , -you would set the -.CW CFLAGS -variable to contain -.CW -g -.CW "CFLAGS = -g" '') (`` -and PMake would take care of the rest. -.RE -.LP -To give you a quick example, the makefile in 2.3.4 -.Rm 3 2.3.4 -could be changed to this: -.DS -OBJS = a.o b.o c.o -program : $(OBJS) - $(CC) -o $(.TARGET) $(.ALLSRC) -$(OBJS) : defs.h -.DE -The transformation rule I gave above takes the place of the 6 lines\** -.FS -This is also somewhat cleaner, I think, than the dynamic source -solution presented in 2.6 -.FE -.Rm 4 2.6 -.DS -a.o : a.c - cc -c a.c -b.o : b.c - cc -c b.c -c.o : c.c - cc -c c.c -.DE -.LP -Now you may be wondering about the dependency between the -.CW .o -and -.CW .c -files \*- it's not mentioned anywhere in the new makefile. This is -because it isn't needed: one of the effects of applying a -transformation rule is the target comes to depend on the implied -source. That's why it's called the implied -.I source . -.LP -For a more detailed example. Say you have a makefile like this: -.DS -a.out : a.o b.o - $(CC) $(.ALLSRC) -.DE -and a directory set up like this: -.DS -total 4 --rw-rw-r-- 1 deboor 34 Sep 7 00:43 Makefile --rw-rw-r-- 1 deboor 119 Oct 3 19:39 a.c --rw-rw-r-- 1 deboor 201 Sep 7 00:43 a.o --rw-rw-r-- 1 deboor 69 Sep 7 00:43 b.c -.DE -While just typing -.CW pmake '' `` -will do the right thing, it's much more informative to type -.CW "pmake -d s" ''. `` -This will show you what PMake is up to as it processes the files. In -this case, PMake prints the following: -.DS -Suff_FindDeps (a.out) - using existing source a.o - applying .o -> .out to "a.o" -Suff_FindDeps (a.o) - trying a.c...got it - applying .c -> .o to "a.c" -Suff_FindDeps (b.o) - trying b.c...got it - applying .c -> .o to "b.c" -Suff_FindDeps (a.c) - trying a.y...not there - trying a.l...not there - trying a.c,v...not there - trying a.y,v...not there - trying a.l,v...not there -Suff_FindDeps (b.c) - trying b.y...not there - trying b.l...not there - trying b.c,v...not there - trying b.y,v...not there - trying b.l,v...not there ---- a.o --- -cc -c a.c ---- b.o --- -cc -c b.c ---- a.out --- -cc a.o b.o -.DE -.LP -.CW Suff_FindDeps -is the name of a function in PMake that is called to check for implied -sources for a target using transformation rules. -The transformations it tries are, naturally -enough, limited to the ones that have been defined (a transformation -may be defined multiple times, by the way, but only the most recent -one will be used). You will notice, however, that there is a definite -order to the suffixes that are tried. This order is set by the -relative positions of the suffixes on the -.CW .SUFFIXES -line \*- the earlier a suffix appears, the earlier it is checked as -the source of a transformation. Once a suffix has been defined, the -only way to change its position in the pecking order is to remove all -the suffixes (by having a -.CW .SUFFIXES -dependency line with no sources) and redefine them in the order you -want. (Previously-defined transformation rules will be automatically -redefined as the suffixes they involve are re-entered.) -.LP -Another way to affect the search order is to make the dependency -explicit. In the above example, -.CW a.out -depends on -.CW a.o -and -.CW b.o . -Since a transformation exists from -.CW .o -to -.CW .out , -PMake uses that, as indicated by the -.CW "using existing source a.o" '' `` -message. -.LP -The search for a transformation starts from the suffix of the target -and continues through all the defined transformations, in the order -dictated by the suffix ranking, until an existing file with the same -base (the target name minus the suffix and any leading directories) is -found. At that point, one or more transformation rules will have been -found to change the one existing file into the target. -.LP -For example, ignoring what's in the system makefile for now, say you -have a makefile like this: -.DS -\&.SUFFIXES : .out .o .c .y .l -\&.l.c : - lex $(.IMPSRC) - mv lex.yy.c $(.TARGET) -\&.y.c : - yacc $(.IMPSRC) - mv y.tab.c $(.TARGET) -\&.c.o : - cc -c $(.IMPSRC) -\&.o.out : - cc -o $(.TARGET) $(.IMPSRC) -.DE -and the single file -.CW jive.l . -If you were to type -.CW "pmake -rd ms jive.out" ,'' `` -you would get the following output for -.CW jive.out : -.DS -Suff_FindDeps (jive.out) - trying jive.o...not there - trying jive.c...not there - trying jive.y...not there - trying jive.l...got it - applying .l -> .c to "jive.l" - applying .c -> .o to "jive.c" - applying .o -> .out to "jive.o" -.DE -and this is why: PMake starts with the target -.CW jive.out , -figures out its suffix -.CW .out ) ( -and looks for things it can transform to a -.CW .out -file. In this case, it only finds -.CW .o , -so it looks for the file -.CW jive.o . -It fails to find it, so it looks for transformations into a -.CW .o -file. Again it has only one choice: -.CW .c . -So it looks for -.CW jive.c -and, as you know, fails to find it. At this point it has two choices: -it can create the -.CW .c -file from either a -.CW .y -file or a -.CW .l -file. Since -.CW .y -came first on the -.CW .SUFFIXES -line, it checks for -.CW jive.y -first, but can't find it, so it looks for -.CW jive.l -and, lo and behold, there it is. -At this point, it has defined a transformation path as follows: -.CW .l -\(-> -.CW .c -\(-> -.CW .o -\(-> -.CW .out -and applies the transformation rules accordingly. For completeness, -and to give you a better idea of what PMake actually did with this -three-step transformation, this is what PMake printed for the rest of -the process: -.DS -Suff_FindDeps (jive.o) - using existing source jive.c - applying .c -> .o to "jive.c" -Suff_FindDeps (jive.c) - using existing source jive.l - applying .l -> .c to "jive.l" -Suff_FindDeps (jive.l) -Examining jive.l...modified 17:16:01 Oct 4, 1987...up-to-date -Examining jive.c...non-existent...out-of-date ---- jive.c --- -lex jive.l -\&.\|.\|. meaningless lex output deleted .\|.\|. -mv lex.yy.c jive.c -Examining jive.o...non-existent...out-of-date ---- jive.o --- -cc -c jive.c -Examining jive.out...non-existent...out-of-date ---- jive.out --- -cc -o jive.out jive.o -.DE -.LP -One final question remains: what does PMake do with targets that have -no known suffix? PMake simply pretends it actually has a known suffix -and searches for transformations accordingly. -The suffix it chooses is the source for the -.CW .NULL -.Ix 0 ref .NULL -target mentioned later. In the system makefile, -.CW .out -is chosen as the ``null suffix'' -.Ix 0 def suffix null -.Ix 0 def "null suffix" -because most people use PMake to create programs. You are, however, -free and welcome to change it to a suffix of your own choosing. -The null suffix is ignored, however, when PMake is in compatibility -mode (see chapter 4). -.xH 2 Including Other Makefiles -.Ix 0 def makefile inclusion -.Rd 2 -.LP -Just as for programs, it is often useful to extract certain parts of a -makefile into another file and just include it in other makefiles -somehow. Many compilers allow you say something like -.DS -#include "defs.h" -.DE -to include the contents of -.CW defs.h -in the source file. PMake allows you to do the same thing for -makefiles, with the added ability to use variables in the filenames. -An include directive in a makefile looks either like this: -.DS -#include <file> -.DE -or this -.DS -#include "file" -.DE -The difference between the two is where PMake searches for the file: -the first way, PMake will look for -the file only in the system makefile directory (or directories) -(to find out what that directory is, give PMake the -.B \-h -flag). -.Ix 0 ref flags -h -The system makefile directory search path can be overridden via the -.B \-m -option. -.Ix 0 ref flags -m -For files in double-quotes, the search is more complex: -.RS -.IP 1) -The directory of the makefile that's including the file. -.IP 2) -The current directory (the one in which you invoked PMake). -.IP 3) -The directories given by you using -.B \-I -flags, in the order in which you gave them. -.IP 4) -Directories given by -.CW .PATH -dependency lines (see chapter 4). -.IP 5) -The system makefile directory. -.RE -.LP -in that order. -.LP -You are free to use PMake variables in the filename\*-PMake will -expand them before searching for the file. You must specify the -searching method with either angle brackets or double-quotes -.I outside -of a variable expansion. I.e. the following -.DS -SYSTEM = <command.mk> - -#include $(SYSTEM) -.DE -won't work. -.xH 2 Saving Commands -.LP -.Ix 0 def ... -There may come a time when you will want to save certain commands to -be executed when everything else is done. For instance: you're -making several different libraries at one time and you want to create the -members in parallel. Problem is, -.CW ranlib -is another one of those programs that can't be run more than once in -the same directory at the same time (each one creates a file called -.CW __.SYMDEF -into which it stuffs information for the linker to use. Two of them -running at once will overwrite each other's file and the result will -be garbage for both parties). You might want a way to save the ranlib -commands til the end so they can be run one after the other, thus -keeping them from trashing each other's file. PMake allows you to do -this by inserting an ellipsis (``.\|.\|.'') as a command between -commands to be run at once and those to be run later. -.LP -So for the -.CW ranlib -case above, you might do this: -.Rd 5 -.DS -lib1.a : $(LIB1OBJS) - rm -f $(.TARGET) - ar cr $(.TARGET) $(.ALLSRC) - ... - ranlib $(.TARGET) - -lib2.a : $(LIB2OBJS) - rm -f $(.TARGET) - ar cr $(.TARGET) $(.ALLSRC) - ... - ranlib $(.TARGET) -.DE -.Ix 0 ref variable local .TARGET -.Ix 0 ref variable local .ALLSRC -This would save both -.DS -ranlib $(.TARGET) -.DE -commands until the end, when they would run one after the other -(using the correct value for the -.CW .TARGET -variable, of course). -.LP -Commands saved in this manner are only executed if PMake manages to -re-create everything without an error. -.xH 2 Target Attributes -.LP -PMake allows you to give attributes to targets by means of special -sources. Like everything else PMake uses, these sources begin with a -period and are made up of all upper-case letters. There are various -reasons for using them, and I will try to give examples for most of -them. Others you'll have to find uses for yourself. Think of it as ``an -exercise for the reader.'' By placing one (or more) of these as a source on a -dependency line, you are ``marking the target(s) with that -attribute.'' That's just the way I phrase it, so you know. -.LP -Any attributes given as sources for a transformation rule are applied -to the target of the transformation rule when the rule is applied. -.Ix 0 def attributes -.Ix 0 ref source -.Ix 0 ref target -.nr pw 12 -.IP .DONTCARE \n(pw -.Ix 0 def attributes .DONTCARE -.Ix 0 def .DONTCARE -If a target is marked with this attribute and PMake can't figure out -how to create it, it will ignore this fact and assume the file isn't -really needed or actually exists and PMake just can't find it. This may prove -wrong, but the error will be noted later on, not when PMake tries to create -the target so marked. This attribute also prevents PMake from -attempting to touch the target if it is given the -.B \-t -flag. -.Ix 0 ref flags -t -.IP .EXEC \n(pw -.Ix 0 def attributes .EXEC -.Ix 0 def .EXEC -This attribute causes its shell script to be executed while having no -effect on targets that depend on it. This makes the target into a sort -of subroutine. An example. Say you have some LISP files that need to -be compiled and loaded into a LISP process. To do this, you echo LISP -commands into a file and execute a LISP with this file as its input -when everything's done. Say also that you have to load other files -from another system before you can compile your files and further, -that you don't want to go through the loading and dumping unless one -of -.I your -files has changed. Your makefile might look a little bit -like this (remember, this is an educational example, and don't worry -about the -.CW COMPILE -rule, all will soon become clear, grasshopper): -.DS -system : init a.fasl b.fasl c.fasl - for i in $(.ALLSRC); - do - echo -n '(load "' >> input - echo -n ${i} >> input - echo '")' >> input - done - echo '(dump "$(.TARGET)")' >> input - lisp < input - -a.fasl : a.l init COMPILE -b.fasl : b.l init COMPILE -c.fasl : c.l init COMPILE -COMPILE : .USE - echo '(compile "$(.ALLSRC)")' >> input -init : .EXEC - echo '(load-system)' > input -.DE -.Ix 0 ref .USE -.Ix 0 ref attributes .USE -.Ix 0 ref variable local .ALLSRC -.IP "\&" -.CW .EXEC -sources, don't appear in the local variables of targets that depend on -them (nor are they touched if PMake is given the -.B \-t -flag). -.Ix 0 ref flags -t -Note that all the rules, not just that for -.CW system , -include -.CW init -as a source. This is because none of the other targets can be made -until -.CW init -has been made, thus they depend on it. -.IP .EXPORT \n(pw -.Ix 0 def attributes .EXPORT -.Ix 0 def .EXPORT -This is used to mark those targets whose creation should be sent to -another machine if at all possible. This may be used by some -exportation schemes if the exportation is expensive. You should ask -your system administrator if it is necessary. -.IP .EXPORTSAME \n(pw -.Ix 0 def attributes .EXPORTSAME -.Ix 0 def .EXPORTSAME -Tells the export system that the job should be exported to a machine -of the same architecture as the current one. Certain operations (e.g. -running text through -.CW nroff ) -can be performed the same on any architecture (CPU and -operating system type), while others (e.g. compiling a program with -.CW cc ) -must be performed on a machine with the same architecture. Not all -export systems will support this attribute. -.IP .IGNORE \n(pw -.Ix 0 def attributes .IGNORE -.Ix 0 def .IGNORE attribute -Giving a target the -.CW .IGNORE -attribute causes PMake to ignore errors from any of the target's commands, as -if they all had `\-' before them. -.IP .INVISIBLE \n(pw -.Ix 0 def attributes .INVISIBLE -.Ix 0 def .INVISIBLE -This allows you to specify one target as a source for another without -the one affecting the other's local variables. Useful if, say, you -have a makefile that creates two programs, one of which is used to -create the other, so it must exist before the other is created. You -could say -.DS -prog1 : $(PROG1OBJS) prog2 MAKEINSTALL -prog2 : $(PROG2OBJS) .INVISIBLE MAKEINSTALL -.DE -where -.CW MAKEINSTALL -is some complex .USE rule (see below) that depends on the -.Ix 0 ref .USE -.CW .ALLSRC -variable containing the right things. Without the -.CW .INVISIBLE -attribute for -.CW prog2 , -the -.CW MAKEINSTALL -rule couldn't be applied. This is not as useful as it should be, and -the semantics may change (or the whole thing go away) in the -not-too-distant future. -.IP .JOIN \n(pw -.Ix 0 def attributes .JOIN -.Ix 0 def .JOIN -This is another way to avoid performing some operations in parallel -while permitting everything else to be done so. Specifically it -forces the target's shell script to be executed only if one or more of the -sources was out-of-date. In addition, the target's name, -in both its -.CW .TARGET -variable and all the local variables of any target that depends on it, -is replaced by the value of its -.CW .ALLSRC -variable. -As an example, suppose you have a program that has four libraries that -compile in the same directory along with, and at the same time as, the -program. You again have the problem with -.CW ranlib -that I mentioned earlier, only this time it's more severe: you -can't just put the ranlib off to the end since the program -will need those libraries before it can be re-created. You can do -something like this: -.DS -program : $(OBJS) libraries - cc -o $(.TARGET) $(.ALLSRC) - -libraries : lib1.a lib2.a lib3.a lib4.a .JOIN - ranlib $(.OODATE) -.DE -.Ix 0 ref variable local .TARGET -.Ix 0 ref variable local .ALLSRC -.Ix 0 ref variable local .OODATE -.Ix 0 ref .TARGET -.Ix 0 ref .ALLSRC -.Ix 0 ref .OODATE -In this case, PMake will re-create the -.CW $(OBJS) -as necessary, along with -.CW lib1.a , -.CW lib2.a , -.CW lib3.a -and -.CW lib4.a . -It will then execute -.CW ranlib -on any library that was changed and set -.CW program 's -.CW .ALLSRC -variable to contain what's in -.CW $(OBJS) -followed by -.CW "lib1.a lib2.a lib3.a lib4.a" .'' `` -In case you're wondering, it's called -.CW .JOIN -because it joins together different threads of the ``input graph'' at -the target marked with the attribute. -Another aspect of the .JOIN attribute is it keeps the target from -being created if the -.B \-t -flag was given. -.Ix 0 ref flags -t -.IP .MAKE \n(pw -.Ix 0 def attributes .MAKE -.Ix 0 def .MAKE -The -.CW .MAKE -attribute marks its target as being a recursive invocation of PMake. -This forces PMake to execute the script associated with the target (if -it's out-of-date) even if you gave the -.B \-n -or -.B \-t -flag. By doing this, you can start at the top of a system and type -.DS -pmake -n -.DE -and have it descend the directory tree (if your makefiles are set up -correctly), printing what it would have executed if you hadn't -included the -.B \-n -flag. -.IP .NOEXPORT \n(pw -.Ix 0 def attributes .NOEXPORT -.Ix 0 def .NOEXPORT attribute -If possible, PMake will attempt to export the creation of all targets to -another machine (this depends on how PMake was configured). Sometimes, -the creation is so simple, it is pointless to send it to another -machine. If you give the target the -.CW .NOEXPORT -attribute, it will be run locally, even if you've given PMake the -.B "\-L 0" -flag. -.IP .NOTMAIN \n(pw -.Ix 0 def attributes .NOTMAIN -.Ix 0 def .NOTMAIN -Normally, if you do not specify a target to make in any other way, -PMake will take the first target on the first dependency line of a -makefile as the target to create. That target is known as the ``Main -Target'' and is labeled as such if you print the dependencies out -using the -.B \-p -flag. -.Ix 0 ref flags -p -Giving a target this attribute tells PMake that the target is -definitely -.I not -the Main Target. -This allows you to place targets in an included makefile and -have PMake create something else by default. -.IP .PRECIOUS \n(pw -.Ix 0 def attributes .PRECIOUS -.Ix 0 def .PRECIOUS attribute -When PMake is interrupted (you type control-C at the keyboard), it -will attempt to clean up after itself by removing any half-made -targets. If a target has the -.CW .PRECIOUS -attribute, however, PMake will leave it alone. An additional side -effect of the `::' operator is to mark the targets as -.CW .PRECIOUS . -.Ix 0 ref operator double-colon -.Ix 0 ref :: -.IP .SILENT \n(pw -.Ix 0 def attributes .SILENT -.Ix 0 def .SILENT attribute -Marking a target with this attribute keeps its commands from being -printed when they're executed, just as if they had an `@' in front of them. -.IP .USE \n(pw -.Ix 0 def attributes .USE -.Ix 0 def .USE -By giving a target this attribute, you turn it into PMake's equivalent -of a macro. When the target is used as a source for another target, -the other target acquires the commands, sources and attributes (except -.CW .USE ) -of the source. -If the target already has commands, the -.CW .USE -target's commands are added to the end. If more than one .USE-marked -source is given to a target, the rules are applied sequentially. -.IP "\&" \n(pw -The typical .USE rule (as I call them) will use the sources of the -target to which it is applied (as stored in the -.CW .ALLSRC -variable for the target) as its ``arguments,'' if you will. -For example, you probably noticed that the commands for creating -.CW lib1.a -and -.CW lib2.a -in the example in section 3.3 -.Rm 5 3.3 -were exactly the same. You can use the -.CW .USE -attribute to eliminate the repetition, like so: -.DS -lib1.a : $(LIB1OBJS) MAKELIB -lib2.a : $(LIB2OBJS) MAKELIB - -MAKELIB : .USE - rm -f $(.TARGET) - ar cr $(.TARGET) $(.ALLSRC) - ... - ranlib $(.TARGET) -.DE -.Ix 0 ref variable local .TARGET -.Ix 0 ref variable local .ALLSRC -.IP "\&" \n(pw -Several system makefiles (not to be confused with The System Makefile) -make use of these .USE rules to make your -life easier (they're in the default, system makefile directory...take a look). -Note that the .USE rule source itself -.CW MAKELIB ) ( -does not appear in any of the targets's local variables. -There is no limit to the number of times I could use the -.CW MAKELIB -rule. If there were more libraries, I could continue with -.CW "lib3.a : $(LIB3OBJS) MAKELIB" '' `` -and so on and so forth. -.xH 2 Special Targets -.LP -As there were in Make, so there are certain targets that have special -meaning to PMake. When you use one on a dependency line, it is the -only target that may appear on the left-hand-side of the operator. -.Ix 0 ref target -.Ix 0 ref operator -As for the attributes and variables, all the special targets -begin with a period and consist of upper-case letters only. -I won't describe them all in detail because some of them are rather -complex and I'll describe them in more detail than you'll want in -chapter 4. -The targets are as follows: -.nr pw 10 -.IP .BEGIN \n(pw -.Ix 0 def .BEGIN -Any commands attached to this target are executed before anything else -is done. You can use it for any initialization that needs doing. -.IP .DEFAULT \n(pw -.Ix 0 def .DEFAULT -This is sort of a .USE rule for any target (that was used only as a -source) that PMake can't figure out any other way to create. It's only -``sort of'' a .USE rule because only the shell script attached to the -.CW .DEFAULT -target is used. The -.CW .IMPSRC -variable of a target that inherits -.CW .DEFAULT 's -commands is set to the target's own name. -.Ix 0 ref .IMPSRC -.Ix 0 ref variable local .IMPSRC -.IP .END \n(pw -.Ix 0 def .END -This serves a function similar to -.CW .BEGIN , -in that commands attached to it are executed once everything has been -re-created (so long as no errors occurred). It also serves the extra -function of being a place on which PMake can hang commands you put off -to the end. Thus the script for this target will be executed before -any of the commands you save with the ``.\|.\|.''. -.Ix 0 ref ... -.IP .EXPORT \n(pw -The sources for this target are passed to the exportation system compiled -into PMake. Some systems will use these sources to configure -themselves. You should ask your system administrator about this. -.IP .IGNORE \n(pw -.Ix 0 def .IGNORE target -.Ix 0 ref .IGNORE attribute -.Ix 0 ref attributes .IGNORE -This target marks each of its sources with the -.CW .IGNORE -attribute. If you don't give it any sources, then it is like -giving the -.B \-i -flag when you invoke PMake \*- errors are ignored for all commands. -.Ix 0 ref flags -i -.IP .INCLUDES \n(pw -.Ix 0 def .INCLUDES target -.Ix 0 def variable global .INCLUDES -.Ix 0 def .INCLUDES variable -The sources for this target are taken to be suffixes that indicate a -file that can be included in a program source file. -The suffix must have already been declared with -.CW .SUFFIXES -(see below). -Any suffix so marked will have the directories on its search path -(see -.CW .PATH , -below) placed in the -.CW .INCLUDES -variable, each preceded by a -.B \-I -flag. This variable can then be used as an argument for the compiler -in the normal fashion. The -.CW .h -suffix is already marked in this way in the system makefile. -.Ix 0 ref makefilesystem -E.g. if you have -.DS -\&.SUFFIXES : .bitmap -\&.PATH.bitmap : /usr/local/X/lib/bitmaps -\&.INCLUDES : .bitmap -.DE -PMake will place -.CW "-I/usr/local/X/lib/bitmaps" '' `` -in the -.CW .INCLUDES -variable and you can then say -.DS -cc $(.INCLUDES) -c xprogram.c -.DE -(Note: the -.CW .INCLUDES -variable is not actually filled in until the entire makefile has been read.) -.IP .INTERRUPT \n(pw -.Ix 0 def .INTERRUPT -When PMake is interrupted, -it will execute the commands in the script for this target, if it -exists. -.IP .LIBS \n(pw -.Ix 0 def .LIBS target -.Ix 0 def .LIBS variable -.Ix 0 def variable global .LIBS -This does for libraries what -.CW .INCLUDES -does for include files, except the flag used is -.B \-L , -as required by those linkers that allow you to tell them where to find -libraries. The variable used is -.CW .LIBS . -Be forewarned that PMake may not have been compiled to do this if the -linker on your system doesn't accept the -.B \-L -flag, though the -.CW .LIBS -variable will always be defined once the makefile has been read. -.IP .MAIN \n(pw -.Ix 0 def .MAIN -If you didn't give a target (or targets) to create when you invoked -PMake, it will take the sources of this target as the targets to -create. -.IP .MAKEFLAGS \n(pw -.Ix 0 def .MAKEFLAGS target -This target provides a way for you to always specify flags for PMake -when the makefile is used. The flags are just as they would be typed -to the shell (except you can't use shell variables unless they're in -the environment), -though the -.B \-f -and -.B \-r -flags have no effect. -.IP .NULL \n(pw -.Ix 0 def .NULL -.Ix 0 ref suffix null -.Ix 0 ref "null suffix" -This allows you to specify what suffix PMake should pretend a file has -if, in fact, it has no known suffix. Only one suffix may be so -designated. The last source on the dependency line is the suffix that -is used (you should, however, only give one suffix.\|.\|.). -.IP .PATH \n(pw -.Ix 0 def .PATH -If you give sources for this target, PMake will take them as -directories in which to search for files it cannot find in the current -directory. If you give no sources, it will clear out any directories -added to the search path before. Since the effects of this all get -very complex, I'll leave it til chapter four to give you a complete -explanation. -.IP .PATH\fIsuffix\fP \n(pw -.Ix 0 ref .PATH -This does a similar thing to -.CW .PATH , -but it does it only for files with the given suffix. The suffix must -have been defined already. Look at -.B "Search Paths" -(section 4.1) -.Rm 6 4.1 -for more information. -.IP .PRECIOUS \n(pw -.Ix 0 def .PRECIOUS target -.Ix 0 ref .PRECIOUS attribute -.Ix 0 ref attributes .PRECIOUS -Similar to -.CW .IGNORE , -this gives the -.CW .PRECIOUS -attribute to each source on the dependency line, unless there are no -sources, in which case the -.CW .PRECIOUS -attribute is given to every target in the file. -.IP .RECURSIVE \n(pw -.Ix 0 def .RECURSIVE -.Ix 0 ref attributes .MAKE -.Ix 0 ref .MAKE -This target applies the -.CW .MAKE -attribute to all its sources. It does nothing if you don't give it any sources. -.IP .SHELL \n(pw -.Ix 0 def .SHELL -PMake is not constrained to only using the Bourne shell to execute -the commands you put in the makefile. You can tell it some other shell -to use with this target. Check out -.B "A Shell is a Shell is a Shell" -(section 4.4) -.Rm 7 4.4 -for more information. -.IP .SILENT \n(pw -.Ix 0 def .SILENT target -.Ix 0 ref .SILENT attribute -.Ix 0 ref attributes .SILENT -When you use -.CW .SILENT -as a target, it applies the -.CW .SILENT -attribute to each of its sources. If there are no sources on the -dependency line, then it is as if you gave PMake the -.B \-s -flag and no commands will be echoed. -.IP .SUFFIXES \n(pw -.Ix 0 def .SUFFIXES -This is used to give new file suffixes for PMake to handle. Each -source is a suffix PMake should recognize. If you give a -.CW .SUFFIXES -dependency line with no sources, PMake will forget about all the -suffixes it knew (this also nukes the null suffix). -For those targets that need to have suffixes defined, this is how you do it. -.LP -In addition to these targets, a line of the form -.DS -\fIattribute\fP : \fIsources\fP -.DE -applies the -.I attribute -to all the targets listed as -.I sources . -.xH 2 Modifying Variable Expansion -.LP -.Ix 0 def variable expansion modified -.Ix 0 ref variable expansion -.Ix 0 def variable modifiers -Variables need not always be expanded verbatim. PMake defines several -modifiers that may be applied to a variable's value before it is -expanded. You apply a modifier by placing it after the variable name -with a colon between the two, like so: -.DS -${\fIVARIABLE\fP:\fImodifier\fP} -.DE -Each modifier is a single character followed by something specific to -the modifier itself. -You may apply as many modifiers as you want \*- each one is applied to -the result of the previous and is separated from the previous by -another colon. -.LP -There are seven ways to modify a variable's expansion, most of which -come from the C shell variable modification characters: -.RS -.IP "M\fIpattern\fP" -.Ix 0 def :M -.Ix 0 def modifier match -This is used to select only those words (a word is a series of -characters that are neither spaces nor tabs) that match the given -.I pattern . -The pattern is a wildcard pattern like that used by the shell, where -.CW * -means 0 or more characters of any sort; -.CW ? -is any single character; -.CW [abcd] -matches any single character that is either `a', `b', `c' or `d' -(there may be any number of characters between the brackets); -.CW [0-9] -matches any single character that is between `0' and `9' (i.e. any -digit. This form may be freely mixed with the other bracket form), and -`\\' is used to escape any of the characters `*', `?', `[' or `:', -leaving them as regular characters to match themselves in a word. -For example, the system makefile -.CW <makedepend.mk> -uses -.CW "$(CFLAGS:M-[ID]*)" '' `` -to extract all the -.CW \-I -and -.CW \-D -flags that would be passed to the C compiler. This allows it to -properly locate include files and generate the correct dependencies. -.IP "N\fIpattern\fP" -.Ix 0 def :N -.Ix 0 def modifier nomatch -This is identical to -.CW :M -except it substitutes all words that don't match the given pattern. -.IP "S/\fIsearch-string\fP/\fIreplacement-string\fP/[g]" -.Ix 0 def :S -.Ix 0 def modifier substitute -Causes the first occurrence of -.I search-string -in the variable to be replaced by -.I replacement-string , -unless the -.CW g -flag is given at the end, in which case all occurrences of the string -are replaced. The substitution is performed on each word in the -variable in turn. If -.I search-string -begins with a -.CW ^ , -the string must match starting at the beginning of the word. If -.I search-string -ends with a -.CW $ , -the string must match to the end of the word (these two may be -combined to force an exact match). If a backslash precedes these two -characters, however, they lose their special meaning. Variable -expansion also occurs in the normal fashion inside both the -.I search-string -and the -.I replacement-string , -.B except -that a backslash is used to prevent the expansion of a -.CW $ , -not another dollar sign, as is usual. -Note that -.I search-string -is just a string, not a pattern, so none of the usual -regular-expression/wildcard characters have any special meaning save -.CW ^ -and -.CW $ . -In the replacement string, -the -.CW & -character is replaced by the -.I search-string -unless it is preceded by a backslash. -You are allowed to use any character except -colon or exclamation point to separate the two strings. This so-called -delimiter character may be placed in either string by preceding it -with a backslash. -.IP T -.Ix 0 def :T -.Ix 0 def modifier tail -Replaces each word in the variable expansion by its last -component (its ``tail''). For example, given -.DS -OBJS = ../lib/a.o b /usr/lib/libm.a -TAILS = $(OBJS:T) -.DE -the variable -.CW TAILS -would expand to -.CW "a.o b libm.a" .'' `` -.IP H -.Ix 0 def :H -.Ix 0 def modifier head -This is similar to -.CW :T , -except that every word is replaced by everything but the tail (the -``head''). Using the same definition of -.CW OBJS , -the string -.CW "$(OBJS:H)" '' `` -would expand to -.CW "../lib /usr/lib" .'' `` -Note that the final slash on the heads is removed and -anything without a head is replaced by the empty string. -.IP E -.Ix 0 def :E -.Ix 0 def modifier extension -.Ix 0 def modifier suffix -.Ix 0 ref suffix "variable modifier" -.CW :E -replaces each word by its suffix (``extension''). So -.CW "$(OBJS:E)" '' `` -would give you -.CW ".o .a" .'' `` -.IP R -.Ix 0 def :R -.Ix 0 def modifier root -.Ix 0 def modifier base -This replaces each word by everything but the suffix (the ``root'' of -the word). -.CW "$(OBJS:R)" '' `` -expands to `` -.CW "../lib/a b /usr/lib/libm" .'' -.RE -.LP -In addition, the System V style of substitution is also supported. -This looks like: -.DS -$(\fIVARIABLE\fP:\fIsearch-string\fP=\fIreplacement\fP) -.DE -It must be the last modifier in the chain. The search is anchored at -the end of each word, so only suffixes or whole words may be replaced. -.xH 2 More on Debugging -.xH 2 More Exercises -.IP (3.1) -You've got a set programs, each of which is created from its own -assembly-language source file (suffix -.CW .asm ). -Each program can be assembled into two versions, one with error-checking -code assembled in and one without. You could assemble them into files -with different suffixes -.CW .eobj \& ( -and -.CW .obj , -for instance), but your linker only understands files that end in -.CW .obj . -To top it all off, the final executables -.I must -have the suffix -.CW .exe . -How can you still use transformation rules to make your life easier -(Hint: assume the error-checking versions have -.CW ec -tacked onto their prefix)? -.IP (3.2) -Assume, for a moment or two, you want to perform a sort of -``indirection'' by placing the name of a variable into another one, -then you want to get the value of the first by expanding the second -somehow. Unfortunately, PMake doesn't allow constructs like -.DS I -$($(FOO)) -.DE -What do you do? Hint: no further variable expansion is performed after -modifiers are applied, thus if you cause a $ to occur in the -expansion, that's what will be in the result. -.xH 1 PMake for Gods -.LP -This chapter is devoted to those facilities in PMake that allow you to -do a great deal in a makefile with very little work, as well as do -some things you couldn't do in Make without a great deal of work (and -perhaps the use of other programs). The problem with these features, -is they must be handled with care, or you will end up with a mess. -.LP -Once more, I assume a greater familiarity with -.UX -or Sprite than I did in the previous two chapters. -.xH 2 Search Paths -.Rd 6 -.LP -PMake supports the dispersal of files into multiple directories by -allowing you to specify places to look for sources with -.CW .PATH -targets in the makefile. The directories you give as sources for these -targets make up a ``search path.'' Only those files used exclusively -as sources are actually sought on a search path, the assumption being -that anything listed as a target in the makefile can be created by the -makefile and thus should be in the current directory. -.LP -There are two types of search paths -in PMake: one is used for all types of files (including included -makefiles) and is specified with a plain -.CW .PATH -target (e.g. -.CW ".PATH : RCS" ''), `` -while the other is specific to a certain type of file, as indicated by -the file's suffix. A specific search path is indicated by immediately following -the -.CW .PATH -with the suffix of the file. For instance -.DS -\&.PATH.h : /sprite/lib/include /sprite/att/lib/include -.DE -would tell PMake to look in the directories -.CW /sprite/lib/include -and -.CW /sprite/att/lib/include -for any files whose suffix is -.CW .h . -.LP -The current directory is always consulted first to see if a file -exists. Only if it cannot be found there are the directories in the -specific search path, followed by those in the general search path, -consulted. -.LP -A search path is also used when expanding wildcard characters. If the -pattern has a recognizable suffix on it, the path for that suffix will -be used for the expansion. Otherwise the default search path is employed. -.LP -When a file is found in some directory other than the current one, all -local variables that would have contained the target's name -.CW .ALLSRC , ( -and -.CW .IMPSRC ) -will instead contain the path to the file, as found by PMake. -Thus if you have a file -.CW ../lib/mumble.c -and a makefile -.DS -\&.PATH.c : ../lib -mumble : mumble.c - $(CC) -o $(.TARGET) $(.ALLSRC) -.DE -the command executed to create -.CW mumble -would be -.CW "cc -o mumble ../lib/mumble.c" .'' `` -(As an aside, the command in this case isn't strictly necessary, since -it will be found using transformation rules if it isn't given. This is because -.CW .out -is the null suffix by default and a transformation exists from -.CW .c -to -.CW .out . -Just thought I'd throw that in.) -.LP -If a file exists in two directories on the same search path, the file -in the first directory on the path will be the one PMake uses. So if -you have a large system spread over many directories, it would behoove -you to follow a naming convention that avoids such conflicts. -.LP -Something you should know about the way search paths are implemented -is that each directory is read, and its contents cached, exactly once -\&\*- when it is first encountered \*- so any changes to the -directories while PMake is running will not be noted when searching -for implicit sources, nor will they be found when PMake attempts to -discover when the file was last modified, unless the file was created in the -current directory. While people have suggested that PMake should read -the directories each time, my experience suggests that the caching seldom -causes problems. In addition, not caching the directories slows things -down enormously because of PMake's attempts to apply transformation -rules through non-existent files \*- the number of extra file-system -searches is truly staggering, especially if many files without -suffixes are used and the null suffix isn't changed from -.CW .out . -.xH 2 Archives and Libraries -.LP -.UX -and Sprite allow you to merge files into an archive using the -.CW ar -command. Further, if the files are relocatable object files, you can -run -.CW ranlib -on the archive and get yourself a library that you can link into any -program you want. The main problem with archives is they double the -space you need to store the archived files, since there's one copy in -the archive and one copy out by itself. The problem with libraries is -you usually think of them as -.CW -lm -rather than -.CW /usr/lib/libm.a -and the linker thinks they're out-of-date if you so much as look at -them. -.LP -PMake solves the problem with archives by allowing you to tell it to -examine the files in the archives (so you can remove the individual -files without having to regenerate them later). To handle the problem -with libraries, PMake adds an additional way of deciding if a library -is out-of-date: -.IP \(bu 2 -If the table of contents is older than the library, or is missing, the -library is out-of-date. -.LP -A library is any target that looks like -.CW \-l name'' `` -or that ends in a suffix that was marked as a library using the -.CW .LIBS -target. -.CW .a -is so marked in the system makefile. -.LP -Members of an archive are specified as -``\fIarchive\fP(\fImember\fP[ \fImember\fP...])''. -Thus -.CW libdix.a(window.o) '' ``' -specifies the file -.CW window.o -in the archive -.CW libdix.a . -You may also use wildcards to specify the members of the archive. Just -remember that most the wildcard characters will only find -.I existing -files. -.LP -A file that is a member of an archive is treated specially. If the -file doesn't exist, but it is in the archive, the modification time -recorded in the archive is used for the file when determining if the -file is out-of-date. When figuring out how to make an archived member target -(not the file itself, but the file in the archive \*- the -\fIarchive\fP(\fImember\fP) target), special care is -taken with the transformation rules, as follows: -.IP \(bu 2 -\&\fIarchive\fP(\fImember\fP) is made to depend on \fImember\fP. -.IP \(bu 2 -The transformation from the \fImember\fP's suffix to the -\fIarchive\fP's suffix is applied to the \fIarchive\fP(\fImember\fP) target. -.IP \(bu 2 -The \fIarchive\fP(\fImember\fP)'s -.CW .TARGET -variable is set to the name of the \fImember\fP if \fImember\fP is -actually a target, or the path to the member file if \fImember\fP is -only a source. -.IP \(bu 2 -The -.CW .ARCHIVE -variable for the \fIarchive\fP(\fImember\fP) target is set to the name -of the \fIarchive\fP. -.Ix 0 def variable local .ARCHIVE -.Ix 0 def .ARCHIVE -.IP \(bu 2 -The -.CW .MEMBER -variable is set to the actual string inside the parentheses. In most -cases, this will be the same as the -.CW .TARGET -variable. -.Ix 0 def variable local .MEMBER -.Ix 0 def .MEMBER -.IP \(bu 2 -The \fIarchive\fP(\fImember\fP)'s place in the local variables of the -targets that depend on it is taken by the value of its -.CW .TARGET -variable. -.LP -Thus, a program library could be created with the following makefile: -.DS -\&.o.a : - ... - rm -f $(.TARGET:T) -OBJS = obj1.o obj2.o obj3.o -libprog.a : libprog.a($(OBJS)) - ar cru $(.TARGET) $(.OODATE) - ranlib $(.TARGET) -.DE -This will cause the three object files to be compiled (if the -corresponding source files were modified after the object file or, if -that doesn't exist, the archived object file), the out-of-date ones -archived in -.CW libprog.a , -a table of contents placed in the archive and the newly-archived -object files to be removed. -.LP -All this is used in the -.CW makelib.mk -system makefile to create a single library with ease. This makefile -looks like this: -.DS -.SM -# -# Rules for making libraries. The object files that make up the library -# are removed once they are archived. -# -# To make several libraries in parallel, you should define the variable -# "many_libraries". This will serialize the invocations of ranlib. -# -# To use, do something like this: -# -# OBJECTS = <files in the library> -# -# fish.a: fish.a($(OBJECTS)) MAKELIB -# -# - -#ifndef _MAKELIB_MK -_MAKELIB_MK = - -#include <po.mk> - -\&.po.a .o.a : - ... - rm -f $(.MEMBER) - -ARFLAGS ?= crl - -# -# Re-archive the out-of-date members and recreate the library's table of -# contents using ranlib. If many_libraries is defined, put the ranlib -# off til the end so many libraries can be made at once. -# -MAKELIB : .USE .PRECIOUS - ar $(ARFLAGS) $(.TARGET) $(.OODATE) -#ifndef no_ranlib -# ifdef many_libraries - ... -# endif many_libraries - ranlib $(.TARGET) -#endif no_ranlib - -#endif _MAKELIB_MK -.DE -.xH 2 On the Condition... -.Rd 1 -.LP -Like the C compiler before it, PMake allows you to configure the makefile, -based on the current environment, using conditional statements. A -conditional looks like this: -.DS -#if \fIboolean expression\fP -\fIlines\fP -#elif \fIanother boolean expression\fP -\fImore lines\fP -#else -\fIstill more lines\fP -#endif -.DE -They may be nested to a maximum depth of 30 and may occur anywhere -(except in a comment, of course). The -.CW # '' `` -must the very first character on the line. -.LP -Each -.I "boolean expression" -is made up of terms that look like function calls, the standard C -boolean operators -.CW && , -.CW || , -and -.CW ! , -and the standard relational operators -.CW == , -.CW != , -.CW > , -.CW >= , -.CW < , -and -.CW <= , -with -.CW == -and -.CW != -being overloaded to allow string comparisons as well. -.CW && -represents logical AND; -.CW || -is logical OR and -.CW ! -is logical NOT. The arithmetic and string operators take precedence -over all three of these operators, while NOT takes precedence over -AND, which takes precedence over OR. This precedence may be -overridden with parentheses, and an expression may be parenthesized to -your heart's content. Each term looks like a call on one of four -functions: -.nr pw 9 -.Ix 0 def make -.Ix 0 def conditional make -.Ix 0 def if make -.IP make \n(pw -The syntax is -.CW make( \fItarget\fP\c -.CW ) -where -.I target -is a target in the makefile. This is true if the given target was -specified on the command line, or as the source for a -.CW .MAIN -target (note that the sources for -.CW .MAIN -are only used if no targets were given on the command line). -.IP defined \n(pw -.Ix 0 def defined -.Ix 0 def conditional defined -.Ix 0 def if defined -The syntax is -.CW defined( \fIvariable\fP\c -.CW ) -and is true if -.I variable -is defined. Certain variables are defined in the system makefile that -identify the system on which PMake is being run. -.IP exists \n(pw -.Ix 0 def exists -.Ix 0 def conditional exists -.Ix 0 def if exists -The syntax is -.CW exists( \fIfile\fP\c -.CW ) -and is true if the file can be found on the global search path (i.e. -that defined by -.CW .PATH -targets, not by -.CW .PATH \fIsuffix\fP -targets). -.IP empty \n(pw -.Ix 0 def empty -.Ix 0 def conditional empty -.Ix 0 def if empty -This syntax is much like the others, except the string inside the -parentheses is of the same form as you would put between parentheses -when expanding a variable, complete with modifiers and everything. The -function returns true if the resulting string is empty (NOTE: an undefined -variable in this context will cause at the very least a warning -message about a malformed conditional, and at the worst will cause the -process to stop once it has read the makefile. If you want to check -for a variable being defined or empty, use the expression -.CW !defined( \fIvar\fP\c `` -.CW ") || empty(" \fIvar\fP\c -.CW ) '' -as the definition of -.CW || -will prevent the -.CW empty() -from being evaluated and causing an error, if the variable is -undefined). This can be used to see if a variable contains a given -word, for example: -.DS -#if !empty(\fIvar\fP:M\fIword\fP) -.DE -.LP -The arithmetic and string operators may only be used to test the value -of a variable. The lefthand side must contain the variable expansion, -while the righthand side contains either a string, enclosed in -double-quotes, or a number. The standard C numeric conventions (except -for specifying an octal number) apply to both sides. E.g. -.DS -#if $(OS) == 4.3 - -#if $(MACHINE) == "sun3" - -#if $(LOAD_ADDR) < 0xc000 -.DE -are all valid conditionals. In addition, the numeric value of a -variable can be tested as a boolean as follows: -.DS -#if $(LOAD) -.DE -would see if -.CW LOAD -contains a non-zero value and -.DS -#if !$(LOAD) -.DE -would test if -.CW LOAD -contains a zero value. -.LP -In addition to the bare -.CW #if ,'' `` -there are other forms that apply one of the first two functions to each -term. They are as follows: -.DS - ifdef \fRdefined\fP - ifndef \fR!defined\fP - ifmake \fRmake\fP - ifnmake \fR!make\fP -.DE -There are also the ``else if'' forms: -.CW elif , -.CW elifdef , -.CW elifndef , -.CW elifmake , -and -.CW elifnmake . -.LP -For instance, if you wish to create two versions of a program, one of which -is optimized (the production version) and the other of which is for debugging -(has symbols for dbx), you have two choices: you can create two -makefiles, one of which uses the -.CW \-g -flag for the compilation, while the other uses the -.CW \-O -flag, or you can use another target (call it -.CW debug ) -to create the debug version. The construct below will take care of -this for you. I have also made it so defining the variable -.CW DEBUG -(say with -.CW "pmake -D DEBUG" ) -will also cause the debug version to be made. -.DS -#if defined(DEBUG) || make(debug) -CFLAGS += -g -#else -CFLAGS += -O -#endif -.DE -There are, of course, problems with this approach. The most glaring -annoyance is that if you want to go from making a debug version to -making a production version, you have to remove all the object files, -or you will get some optimized and some debug versions in the same -program. Another annoyance is you have to be careful not to make two -targets that ``conflict'' because of some conditionals in the -makefile. For instance -.DS -#if make(print) -FORMATTER = ditroff -Plaser_printer -#endif -#if make(draft) -FORMATTER = nroff -Pdot_matrix_printer -#endif -.DE -would wreak havoc if you tried -.CW "pmake draft print" '' `` -since you would use the same formatter for each target. As I said, -this all gets somewhat complicated. -.xH 2 A Shell is a Shell is a Shell -.Rd 7 -.LP -In normal operation, the Bourne Shell (better known as -.CW sh '') `` -is used to execute the commands to re-create targets. PMake also allows you -to specify a different shell for it to use when executing these -commands. There are several things PMake must know about the shell you -wish to use. These things are specified as the sources for the -.CW .SHELL -.Ix 0 ref .SHELL -.Ix 0 ref target .SHELL -target by keyword, as follows: -.IP "\fBpath=\fP\fIpath\fP" -PMake needs to know where the shell actually resides, so it can -execute it. If you specify this and nothing else, PMake will use the -last component of the path and look in its table of the shells it -knows and use the specification it finds, if any. Use this if you just -want to use a different version of the Bourne or C Shell (yes, PMake knows -how to use the C Shell too). -.IP "\fBname=\fP\fIname\fP" -This is the name by which the shell is to be known. It is a single -word and, if no other keywords are specified (other than -.B path ), -it is the name by which PMake attempts to find a specification for -it (as mentioned above). You can use this if you would just rather use -the C Shell than the Bourne Shell -.CW ".SHELL: name=csh" '' (`` -will do it). -.IP "\fBquiet=\fP\fIecho-off command\fP" -As mentioned before, PMake actually controls whether commands are -printed by introducing commands into the shell's input stream. This -keyword, and the next two, control what those commands are. The -.B quiet -keyword is the command used to turn echoing off. Once it is turned -off, echoing is expected to remain off until the echo-on command is given. -.IP "\fBecho=\fP\fIecho-on command\fP" -The command PMake should give to turn echoing back on again. -.IP "\fBfilter=\fP\fIprinted echo-off command\fP" -Many shells will echo the echo-off command when it is given. This -keyword tells PMake in what format the shell actually prints the -echo-off command. Wherever PMake sees this string in the shell's -output, it will delete it and any following whitespace, up to and -including the next newline. See the example at the end of this section -for more details. -.IP "\fBechoFlag=\fP\fIflag to turn echoing on\fP" -Unless a target has been marked -.CW .SILENT , -PMake wants to start the shell running with echoing on. To do this, it -passes this flag to the shell as one of its arguments. If either this -or the next flag begins with a `\-', the flags will be passed to the -shell as separate arguments. Otherwise, the two will be concatenated -(if they are used at the same time, of course). -.IP "\fBerrFlag=\fP\fIflag to turn error checking on\fP" -Likewise, unless a target is marked -.CW .IGNORE , -PMake wishes error-checking to be on from the very start. To this end, -it will pass this flag to the shell as an argument. The same rules for -an initial `\-' apply as for the -.B echoFlag . -.IP "\fBcheck=\fP\fIcommand to turn error checking on\fP" -Just as for echo-control, error-control is achieved by inserting -commands into the shell's input stream. This is the command to make -the shell check for errors. It also serves another purpose if the -shell doesn't have error-control as commands, but I'll get into that -in a minute. Again, once error checking has been turned on, it is -expected to remain on until it is turned off again. -.IP "\fBignore=\fP\fIcommand to turn error checking off\fP" -This is the command PMake uses to turn error checking off. It has -another use if the shell doesn't do error-control, but I'll tell you -about that.\|.\|.\|now. -.IP "\fBhasErrCtl=\fP\fIyes or no\fP" -This takes a value that is either -.B yes -or -.B no . -Now you might think that the existence of the -.B check -and -.B ignore -keywords would be enough to tell PMake if the shell can do -error-control, but you'd be wrong. If -.B hasErrCtl -is -.B yes , -PMake uses the check and ignore commands in a straight-forward manner. -If this is -.B no , -however, their use is rather different. In this case, the check -command is used as a template, in which the string -.B %s -is replaced by the command that's about to be executed, to produce a -command for the shell that will echo the command to be executed. The -ignore command is also used as a template, again with -.B %s -replaced by the command to be executed, to produce a command that will -execute the command to be executed and ignore any error it returns. -When these strings are used as templates, you must provide newline(s) -.CW \en '') (`` -in the appropriate place(s). -.LP -The strings that follow these keywords may be enclosed in single or -double quotes (the quotes will be stripped off) and may contain the -usual C backslash-characters (\en is newline, \er is return, \eb is -backspace, \e' escapes a single-quote inside single-quotes, \e" -escapes a double-quote inside double-quotes). Now for an example. -.LP -This is actually the contents of the -.CW <shx.mk> -system makefile, and causes PMake to use the Bourne Shell in such a -way that each command is printed as it is executed. That is, if more -than one command is given on a line, each will be printed separately. -Similarly, each time the body of a loop is executed, the commands -within that loop will be printed, etc. The specification runs like -this: -.DS -# -# This is a shell specification to have the Bourne shell echo -# the commands just before executing them, rather than when it reads -# them. Useful if you want to see how variables are being expanded, etc. -# -\&.SHELL : path=/bin/sh \e - quiet="set -" \e - echo="set -x" \e - filter="+ set - " \e - echoFlag=x \e - errFlag=e \e - hasErrCtl=yes \e - check="set -e" \e - ignore="set +e" -.DE -.LP -It tells PMake the following: -.Bp -The shell is located in the file -.CW /bin/sh . -It need not tell PMake that the name of the shell is -.CW sh -as PMake can figure that out for itself (it's the last component of -the path). -.Bp -The command to stop echoing is -.CW "set -" . -.Bp -The command to start echoing is -.CW "set -x" . -.Bp -When the echo off command is executed, the shell will print -.CW "+ set - " -(The `+' comes from using the -.CW \-x -flag (rather than the -.CW \-v -flag PMake usually uses)). PMake will remove all occurrences of this -string from the output, so you don't notice extra commands you didn't -put there. -.Bp -The flag the Bourne Shell will take to start echoing in this way is -the -.CW \-x -flag. The Bourne Shell will only take its flag arguments concatenated -as its first argument, so neither this nor the -.B errFlag -specification begins with a \-. -.Bp -The flag to use to turn error-checking on from the start is -.CW \-e . -.Bp -The shell can turn error-checking on and off, and the commands to do -so are -.CW "set +e" -and -.CW "set -e" , -respectively. -.LP -I should note that this specification is for Bourne Shells that are -not part of Berkeley -.UX , -as shells from Berkeley don't do error control. You can get a similar -effect, however, by changing the last three lines to be: -.DS - hasErrCtl=no \e - check="echo \e"+ %s\e"\en" \e - ignore="sh -c '%s || exit 0\en" -.DE -.LP -This will cause PMake to execute the two commands -.DS -echo "+ \fIcmd\fP" -sh -c '\fIcmd\fP || true' -.DE -for each command for which errors are to be ignored. (In case you are -wondering, the thing for -.CW ignore -tells the shell to execute another shell without error checking on and -always exit 0, since the -.B || -causes the -.CW "exit 0" -to be executed only if the first command exited non-zero, and if the -first command exited zero, the shell will also exit zero, since that's -the last command it executed). -.xH 2 Compatibility -.Ix 0 ref compatibility -.LP -There are three (well, 3 \(12) levels of backwards-compatibility built -into PMake. Most makefiles will need none at all. Some may need a -little bit of work to operate correctly when run in parallel. Each -level encompasses the previous levels (e.g. -.B \-B -(one shell per command) implies -.B \-V ) -The three levels are described in the following three sections. -.xH 3 DEFCON 3 \*- Variable Expansion -.Ix 0 ref compatibility -.LP -As noted before, PMake will not expand a variable unless it knows of a -value for it. This can cause problems for makefiles that expect to -leave variables undefined except in special circumstances (e.g. if -more flags need to be passed to the C compiler or the output from a -text processor should be sent to a different printer). If the -variables are enclosed in curly braces -.CW ${PRINTER} ''), (`` -the shell will let them pass. If they are enclosed in parentheses, -however, the shell will declare a syntax error and the make will come -to a grinding halt. -.LP -You have two choices: change the makefile to define the variables -(their values can be overridden on the command line, since that's -where they would have been set if you used Make, anyway) or always give the -.B \-V -flag (this can be done with the -.CW .MAKEFLAGS -target, if you want). -.xH 3 DEFCON 2 \*- The Number of the Beast -.Ix 0 ref compatibility -.LP -Then there are the makefiles that expect certain commands, such as -changing to a different directory, to not affect other commands in a -target's creation script. You can solve this is either by going -back to executing one shell per command (which is what the -.B \-B -flag forces PMake to do), which slows the process down a good bit and -requires you to use semicolons and escaped newlines for shell constructs, or -by changing the makefile to execute the offending command(s) in a subshell -(by placing the line inside parentheses), like so: -.DS -install :: .MAKE - (cd src; $(.PMAKE) install) - (cd lib; $(.PMAKE) install) - (cd man; $(.PMAKE) install) -.DE -.Ix 0 ref operator double-colon -.Ix 0 ref variable global .PMAKE -.Ix 0 ref .PMAKE -.Ix 0 ref .MAKE -.Ix 0 ref attribute .MAKE -This will always execute the three makes (even if the -.B \-n -flag was given) because of the combination of the ``::'' operator and -the -.CW .MAKE -attribute. Each command will change to the proper directory to perform -the install, leaving the main shell in the directory in which it started. -.xH 3 "DEFCON 1 \*- Imitation is the Not the Highest Form of Flattery" -.Ix 0 ref compatibility -.LP -The final category of makefile is the one where every command requires -input, the dependencies are incompletely specified, or you simply -cannot create more than one target at a time, as mentioned earlier. In -addition, you may not have the time or desire to upgrade the makefile -to run smoothly with PMake. If you are the conservative sort, this is -the compatibility mode for you. It is entered either by giving PMake -the -.B \-M -flag (for Make), or by executing PMake as -.CW make .'' `` -In either case, PMake performs things exactly like Make (while still -supporting most of the nice new features PMake provides). This -includes: -.IP \(bu 2 -No parallel execution. -.IP \(bu 2 -Targets are made in the exact order specified by the makefile. The -sources for each target are made in strict left-to-right order, etc. -.IP \(bu 2 -A single Bourne shell is used to execute each command, thus the -shell's -.CW $$ -variable is useless, changing directories doesn't work across command -lines, etc. -.IP \(bu 2 -If no special characters exist in a command line, PMake will break the -command into words itself and execute the command directly, without -executing a shell first. The characters that cause PMake to execute a -shell are: -.CW # , -.CW = , -.CW | , -.CW ^ , -.CW ( , -.CW ) , -.CW { , -.CW } , -.CW ; , -.CW & , -.CW < , -.CW > , -.CW * , -.CW ? , -.CW [ , -.CW ] , -.CW : , -.CW $ , -.CW ` , -and -.CW \e . -You should notice that these are all the characters that are given -special meaning by the shell (except -.CW ' -and -.CW " , -which PMake deals with all by its lonesome). -.IP \(bu 2 -The use of the null suffix is turned off. -.Ix 0 ref "null suffix" -.Ix 0 ref suffix null -.xH 2 The Way Things Work -.LP -When PMake reads the makefile, it parses sources and targets into -nodes in a graph. The graph is directed only in the sense that PMake -knows which way is up. Each node contains not only links to all its -parents and children (the nodes that depend on it and those on which -it depends, respectively), but also a count of the number of its -children that have already been processed. -.LP -The most important thing to know about how PMake uses this graph is -that the traversal is breadth-first and occurs in two passes. -.LP -After PMake has parsed the makefile, it begins with the nodes the user -has told it to make (either on the command line, or via a -.CW .MAIN -target, or by the target being the first in the file not labeled with -the -.CW .NOTMAIN -attribute) placed in a queue. It continues to take the node off the -front of the queue, mark it as something that needs to be made, pass -the node to -.CW Suff_FindDeps -(mentioned earlier) to find any implicit sources for the node, and -place all the node's children that have yet to be marked at the end of -the queue. If any of the children is a -.CW .USE -rule, its attributes are applied to the parent, then its commands are -appended to the parent's list of commands and its children are linked -to its parent. The parent's unmade children counter is then decremented -(since the -.CW .USE -node has been processed). You will note that this allows a -.CW .USE -node to have children that are -.CW .USE -nodes and the rules will be applied in sequence. -If the node has no children, it is placed at the end of -another queue to be examined in the second pass. This process -continues until the first queue is empty. -.LP -At this point, all the leaves of the graph are in the examination -queue. PMake removes the node at the head of the queue and sees if it -is out-of-date. If it is, it is passed to a function that will execute -the commands for the node asynchronously. When the commands have -completed, all the node's parents have their unmade children counter -decremented and, if the counter is then 0, they are placed on the -examination queue. Likewise, if the node is up-to-date. Only those -parents that were marked on the downward pass are processed in this -way. Thus PMake traverses the graph back up to the nodes the user -instructed it to create. When the examination queue is empty and no -shells are running to create a target, PMake is finished. -.LP -Once all targets have been processed, PMake executes the commands -attached to the -.CW .END -target, either explicitly or through the use of an ellipsis in a shell -script. If there were no errors during the entire process but there -are still some targets unmade (PMake keeps a running count of how many -targets are left to be made), there is a cycle in the graph. PMake does -a depth-first traversal of the graph to find all the targets that -weren't made and prints them out one by one. -.xH 1 Answers to Exercises -.IP (3.1) -This is something of a trick question, for which I apologize. The -trick comes from the UNIX definition of a suffix, which PMake doesn't -necessarily share. You will have noticed that all the suffixes used in -this tutorial (and in UNIX in general) begin with a period -.CW .ms , ( -.CW .c , -etc.). Now, PMake's idea of a suffix is more like English's: it's the -characters at the end of a word. With this in mind, one possible -.Ix 0 def suffix -solution to this problem goes as follows: -.DS I -\&.SUFFIXES : ec.exe .exe ec.obj .obj .asm -ec.objec.exe .obj.exe : - link -o $(.TARGET) $(.IMPSRC) -\&.asmec.obj : - asm -o $(.TARGET) -DDO_ERROR_CHECKING $(.IMPSRC) -\&.asm.obj : - asm -o $(.TARGET) $(.IMPSRC) -.DE -.IP (3.2) -The trick to this one lies in the ``:='' variable-assignment operator -and the ``:S'' variable-expansion modifier. -.Ix 0 ref variable assignment expanded -.Ix 0 ref variable expansion modified -.Ix 0 ref modifier substitute -.Ix 0 ref :S -.Ix 0 ref := -Basically what you want is to take the pointer variable, so to speak, -and transform it into an invocation of the variable at which it -points. You might try something like -.DS I -$(PTR:S/^/\e$(/:S/$/)) -.DE -which places -.CW $( '' `` -at the front of the variable name and -.CW ) '' `` -at the end, thus transforming -.CW VAR ,'' `` -for example, into -.CW $(VAR) ,'' `` -which is just what we want. Unfortunately (as you know if you've tried -it), since, as it says in the hint, PMake does no further substitution -on the result of a modified expansion, that's \fIall\fP you get. The -solution is to make use of ``:='' to place that string into yet -another variable, then invoke the other variable directly: -.DS I -*PTR := $(PTR:S/^/\e$(/:S/$/)/) -.DE -You can then use -.CW $(*PTR) '' `` -to your heart's content. -.de Gp -.XP -\&\fB\\$1:\fP -.. -.xH 1 Glossary of Jargon -.Gp "attribute" -A property given to a target that causes PMake to treat it differently. -.Gp "command script" -The lines immediately following a dependency line that specify -commands to execute to create each of the targets on the dependency -line. Each line in the command script must begin with a tab. -.Gp "command-line variable" -A variable defined in an argument when PMake is first executed. -Overrides all assignments to the same variable name in the makefile. -.Gp "conditional" -A construct much like that used in C that allows a makefile to be -configured on the fly based on the local environment, or on what is being -made by that invocation of PMake. -.Gp "creation script" -Commands used to create a target. See ``command script.'' -.Gp "dependency" -The relationship between a source and a target. This comes in three -flavors, as indicated by the operator between the target and the -source. `:' gives a straight time-wise dependency (if the target is -older than the source, the target is out-of-date), while `!' provides -simply an ordering and always considers the target out-of-date. `::' -is much like `:', save it creates multiple instances of a target each -of which depends on its own list of sources. -.Gp "dynamic source" -This refers to a source that has a local variable invocation in it. It -allows a single dependency line to specify a different source for each -target on the line. -.Gp "global variable" -Any variable defined in a makefile. Takes precedence over variables -defined in the environment, but not over command-line or local variables. -.Gp "input graph" -What PMake constructs from a makefile. Consists of nodes made of the -targets in the makefile, and the links between them (the -dependencies). The links are directed (from source to target) and -there may not be any cycles (loops) in the graph. -.Gp "local variable" -A variable defined by PMake visible only in a target's shell script. -There are seven local variables, not all of which are defined for -every target: -.CW .TARGET , -.CW .ALLSRC , -.CW .OODATE , -.CW .PREFIX , -.CW .IMPSRC , -.CW .ARCHIVE , -and -.CW .MEMBER . -.CW .TARGET , -.CW .PREFIX , -.CW .ARCHIVE , -and -.CW .MEMBER -may be used on dependency lines to create ``dynamic sources.'' -.Gp "makefile" -A file that describes how a system is built. If you don't know what it -is after reading this tutorial.\|.\|.\|. -.Gp "modifier" -A letter, following a colon, used to alter how a variable is expanded. -It has no effect on the variable itself. -.Gp "operator" -What separates a source from a target (on a dependency line) and specifies -the relationship between the two. There are three: -.CW : ', ` -.CW :: ', ` -and -.CW ! '. ` -.Gp "search path" -A list of directories in which a file should be sought. PMake's view -of the contents of directories in a search path does not change once -the makefile has been read. A file is sought on a search path only if -it is exclusively a source. -.Gp "shell" -A program to which commands are passed in order to create targets. -.Gp "source" -Anything to the right of an operator on a dependency line. Targets on -the dependency line are usually created from the sources. -.Gp "special target" -A target that causes PMake to do special things when it's encountered. -.Gp "suffix" -The tail end of a file name. Usually begins with a period, -.CW .c -or -.CW .ms , -e.g. -.Gp "target" -A word to the left of the operator on a dependency line. More -generally, any file that PMake might create. A file may be (and often -is) both a target and a source (what it is depends on how PMake is -looking at it at the time \*- sort of like the wave/particle duality -of light, you know). -.Gp "transformation rule" -A special construct in a makefile that specifies how to create a file -of one type from a file of another, as indicated by their suffixes. -.Gp "variable expansion" -The process of substituting the value of a variable for a reference to -it. Expansion may be altered by means of modifiers. -.Gp "variable" -A place in which to store text that may be retrieved later. Also used -to define the local environment. Conditionals exist that test whether -a variable is defined or not. -.bp -.\" Output table of contents last, with an entry for the index, making -.\" sure to save and restore the last real page number for the index... -.nr @n \n(PN+1 -.\" We are not generating an index -.\" .XS \n(@n -.\" Index -.\" .XE -.nr %% \n% -.PX -.nr % \n(%% |
