Index: trunk/minix/man/man7/ACK.7 =================================================================== --- trunk/minix/man/man7/ACK.7 (revision 9) +++ (revision ) @@ -1,2090 +1,0 @@ -.TH ACK 7 -.SH NAME -ACK \- Additional information on the Amsterdam Compiler Kit compilers -.SH DESCRIPTION -.de SP -.if t .sp 0.4 -.if n .sp -.. -.de XS -.SP -.in +.5i -.nf -.. -.de XE -.fi -.in -.5i -.SP -.. -.de NS -.PP -.B ANS\ \\$1 -.. -.de UX -\s-2UNIX\s+2 -.. -.de MX -.if n MINIX 3 -.if t \s-1MINIX 3\s-1 -.. -.if n .ds Mx MINIX 3 -.if t .ds Mx \s-1MINIX 3\s-1 -.if n .ds Mp Minix-PC -.if t .ds Mx \s-2MINIX-PC\s+2 -.if n .ds Mv Minix-vmd -.if t .ds Mv \s-1MINIX 3\s-1-vmd -.if n .ds Cw \fR -.if t .ds Cw \fC -.de CW -.if n .ft R -.if t .ft C -.. -.\" -These are the details on the Amsterdam Compiler Kit compilers for the -languages C, Modula-2, and Pascal. The design decisions that were made -where the respective standards allowed or mandated this, and the extensions -that were implemented. -.SH "ANSI C REPORT" -This section specifies the implementation-defined behavior of the ANSI-C -compiler as required by ANS X3.159-1989. -.NS A.6.3.1 -.IP \(bu -Diagnostics are placed on the standard error output. They have the -following specification: -.XS -"", line : [()] -.XE -There are three classes of diagnostics: 'error', 'strict' and 'warning'. -When the class is 'error', the class specification is absent. -The class 'strict' is used for violations of the standard which are -not severe enough to stop compilation, for example the occurrence -of non white-space after an '#endif' preprocessing -directive. The class 'warning' is used for legal but dubious -constructions, for example the declaration of a structure-tag in a -parameter type list. -.NS A.6.3.2 -.IP \(bu -The function 'main' can have zero or two parameters. When it has two -parameters, the first parameter is an integer specifying the number of -arguments on the command line (including the command). The second -parameter is a pointer to an array of pointers to the arguments -(as strings). -.IP \(bu -Interactive devices are terminals. -.NS A.6.3.3 -.IP \(bu -The number of significant characters is 64. -Corresponding upper-case and lower-case letters are different. -.NS A.6.3.4 -.IP \(bu -The compiler assumes ASCII-characters in both the source and execution -character set. -.IP \(bu -There are no multibyte characters. -.IP \(bu -There are 8 bits in a character. -.IP \(bu -Character constants that cannot be represented in 8 bits -are truncated. -.IP \(bu -Character constants that are more than 1 character wide will have the -first character specified in the least significant byte. -.IP \(bu -The only supported locale is 'C'. -.IP \(bu -A plain 'char' has the same range of values as 'signed char'. -.NS A.6.3.5 -.IP \(bu -The i80x86 and 68000 both have a two's complement binary-number system. -Shorts are 2 bytes; ints are 2 bytes under 16-bits \*(Mp and 68000 \*(Mx, 4 -bytes under 32-bits \*(Mp; longs occupy 4 bytes. -.IP \(bu -Converting an integer to a shorter signed integer is implemented by -ignoring the high-order byte(s) of the former. -Converting a unsigned integer to a signed integer of the same type is -only done in administration. This means that the bit-pattern remains -unchanged. -.IP \(bu -The result of bitwise operations on signed integers are what can be -expected on a two's complement machine. -.IP \(bu -When either operand is negative, the result of the / operator is the -largest integer less than or equal to the algebraic quotient. -The sign of the remainder on integer division is the sign of the -enumerator. -.IP \(bu -The right-shift of a negative value is negative. -.NS A.6.3.6 -.IP \(bu -The compiler uses IEEE format for floating-point numbers. -High-precision floating-point is used for constant folding. -.IP \(bu -Truncation is done to the nearest floating-point number that can -be represented. -.NS A.6.3.7 -.IP \(bu -The type of the sizeof-operator (also known as size_t) is 'unsigned int'. -.IP \(bu -Casting an integer to a pointer or vice versa has no effect in -bit-pattern when the sizes are equal. Otherwise the value will be -truncated or zero-extended (depending on the direction of the -conversion and the relative sizes). -.IP \(bu -The type of a 'ptrdiff_t' is 'int' on \*(Mp, and 'long' on the 68000 -\*(Mx versions. -.NS A.6.3.8 -.IP \(bu -Since the front end has only limited control over the registers, it can -only make it more likely that variables that are declared as -registers also end up in registers. The only things that can possibly be -put into registers are plain ints and pointers. -.NS A.6.3.9 -.IP \(bu -When a member of a union object is accessed using a member of a -different type, the resulting value will usually be garbage. The -compiler makes no effort to catch these errors. -.IP \(bu -The alignment of types under 16-bit \*(Mp is 1 byte for characters and 2 -bytes for all other types. Under other MINIX 3 versions 'int' and smaller -types are aligned to a multiple of their size, bigger scalar types are -aligned like 'int'. Arrays have the same alignment as their elements; -structs and unions are aligned like their field with the worst alignment. -.IP \(bu -A plain 'int' bit-field is taken as a 'signed int'. This means that -a field with a size 1 bit-field can only store the values 0 and \(mi1. -.IP \(bu -In bit-fields, high-order bits are allocated first. -.IP \(bu -An enum has the same size as a plain 'int'. -.NS A.6.3.10 -.IP \(bu -An access to a volatile object is either a load or a store. Just -mentioning a volatile variable is not enough. -E.g. the statement 'x;' where x is declared volatile, does not -constitute an access. When a volatile object should be read, but its -value ignored, 'if (x);' should do the trick. -.NS A.6.3.11 -.IP \(bu -There is no fixed limit on the number of declarators that may modify an -arithmetic, structure or union type, although specifying too many may -cause the compiler to run out of memory. -.NS A.6.3.12 -.IP \(bu -The maximum number of cases in a switch-statement is in the order of -1e9, although the compiler may run out of memory somewhat earlier. -.NS A.6.3.13 -.IP \(bu -Since both the preprocessor and the compiler assume ASCII-characters, -a single character constant in a conditional-inclusion directive -matches the same value in the execution character set. -.IP \(bu -The preprocessor recognizes \fI\(enI...\fR command-line options. The -directories thus specified are searched first. After that, /usr/include is -visited. -.IP \(bu -Quoted names are first looked for in the directory in which the file -which does the include resides. -.IP \(bu -The characters in a h- or q- char-sequence are taken to be -.UX -paths. -.IP \(bu -Neither the front-end nor the preprocessor know any pragmas. -.IP \(bu -Since the compiler runs on -.MX , -_\^_DATE_\^_ and _\^_TIME_\^_ will always be -defined. -.NS A.6.3.14 -.IP \(bu -NULL is defined as ((void *)0). This in order to detect dubious -constructions like 'int x = NULL;'. -.IP \(bu -The diagnostic printed by 'assert' is as follows: -.XS -Assertion "" failed, file "", line -.XE -where is the argument to the assert macro, printed as string. -(the and should be clear) -.IP \(bu -The sets for character test macros for the C locale are as follows: -.XS -.ta +\w'isalnum 'u -\fBName Set\fR -\fIisalnum\fR 0-9A-Za-z -\fIisalpha\fR A-Za-z -\fIiscntrl\fR \e000-\e037\e177 -\fIislower\fR a-z -\fIisupper\fR A-Z -\fIisprint\fR \e040-\e176 -.DT -.XE -As an addition, there is an \fIisascii\fR macro, which tests whether a character -is an ASCII character. Characters in the range from \e000 to \e177 are ASCII -characters. -.IP \(bu -The behavior of ACK mathematical functions on domain error is as follows: -.XS -.ta +\w'log10 'u -\fBName Returns\fR -\fIasin\fR 0.0 -\fIacos\fR 0.0 -\fIatan2\fR 0.0 -\fIfmod\fR 0.0 -\fIlog\fR \(miHUGE_VAL -\fIlog10\fR \(miHUGE_VAL -\fIpow\fR 0.0 -\fIsqrt\fR 0.0 -.DT -.XE -\*(Mv uses the BSD4.4 C library and the Sun FDLIBM C math library instead -of the ACK library. See -.BR math (3) -for details about the math functions. The \*(Mv libraries offer at -least the same functionality as the ACK library. -.IP \(bu -Underflow range errors do not cause \fIerrno\fR to be set. -.IP \(bu -The function \fIfmod\fR returns 0.0 and sets \fIerrno\fR to EDOM when the second -argument is 0.0. -.IP \(bu -The set of signals for the \fIsignal\fR function is as described by -.BR sigaction (2). -.IP \(bu -A text-stream need not end in a new-line character. -.IP \(bu -White space characters before a new-line appear when read in. -.IP \(bu -There may be any number of null characters appended to a binary -stream. -.IP \(bu -The file position indicator of an append mode stream is initially -positioned at the beginning of the file. -.IP \(bu -A write on a text stream does not cause the associated file to be -truncated beyond that point. -.IP \(bu -The buffering intended by the standard is fully supported. -.IP \(bu -A zero-length file actually exists. -.IP \(bu -A file name can consist of any character, except for the '\e0' and -the '/'. -.IP \(bu -A file can be open multiple times. -.IP \(bu -When a \fIremove\fR is done on an open file, reading and writing behave -just as can be expected from a non-removed file. When the associated -stream is closed, however, all written data will be lost. -.IP \(bu -When a file exists prior to a call to \fIrename\fR, it is removed. -.IP \(bu -The %p conversion in \fIfprintf\fR has the same effect as %#x on \*(Mp and -%#lx on the 68000 versions of \*(Mx. -.IP \(bu -The %p conversion in \fIfscanf\fR has the same effect as %x on \*(Mp and -%lx on the 68000 versions of \*(Mx. -.IP \(bu -A \(mi character that is neither the first nor the last character in the -scanlist for %[ conversion is taken to be a range indicator. When the -first character has a higher ASCII-value than the second, the \(mi will -just be put into the scanlist. -.IP \(bu -The value of \fIerrno\fR when \fIfgetpos\fR or \fIftell\fR failed is that of \fIlseek\fR. -This means: -.XS -.ta +\w'ESPIPE 'u +\w'\- 'u -EBADF \- when the stream is not valid -ESPIPE \- when fildes is associated with a pipe -EINVAL \- the resulting file pointer would be negative -.XE -.IP \(bu -The messages generated by \fIperror\fR depend on the value of \fIerrno\fR. -The mapping of errors to strings is done by \fIstrerror\fR. -.IP \(bu -When the requested size is zero, \fImalloc\fR, \fIcalloc\fR and \fIrealloc\fR -return a null-pointer under \*(Mx. Under \*(Mv a unique non-null pointer is -returned. -.IP \(bu -When \fIabort\fR is called, output buffers will be flushed. Temporary files -(made with the \fItmpfile\fR function) will have disappeared when SIGABRT -is not caught or ignored. -.IP \(bu -The \fIexit\fR function returns the low-order eight bits of its argument -to the environment. -.IP \(bu -The predefined environment names are controlled by the user. -Setting environment variables is done through the \fIputenv\fR function. -This function accepts a pointer to char as its argument. -To set, for example, the environment variable TERM to a230 one writes -.XS -static char terminal[] = "TERM=a230"; -putenv(terminal); -.XE -The argument to \fIputenv\fR is stored in an internal table, so malloc'ed -strings cannot be freed until another call to \fIputenv\fR (which sets the -same environment variable) is made. The argument to \fIputenv\fR must be -writable, which means that officially, the argument cannot be a string -constant. -The function returns 1 if it fails, 0 otherwise. -.LP -.IP \(bu -The argument to \fIsystem\fR is passed as argument to \fI/bin/sh \(enc\fR. -.IP \(bu -The strings returned by \fIstrerror\fR depend on \fIerrno\fR. They are -listed in -.BR intro (2). -Everything else causes \fIstrerror\fR to return "unknown error" under \*(Mx, -or the result of sprintf("Error %d", errno) under \*(Mv. -.IP \(bu -The local time zone is per default GMT. This can be -changed through the TZ environment variable, e.g. TZ=EST6. -See -.BR TZ (5). -.IP \(bu -The \fIclock\fR function returns the number of ticks since process -startup. -.SS References -.IP [1] -ANS X3.159-1989 -.ft I -American National Standard for Information Systems - -Programming Language C -.ft R -.SH "THE MINIX MODULA-2 COMPILER" -This section describes the implementation-specific features of the -.MX -Modula-2 compiler. -It is not intended to teach Modula-2 programming. -For a description of the Modula-2 language, -the reader is referred to [1]. -.SS "The language implemented" -.PP -This paragraph discusses the deviations from the Modula-2 language as described -in the 'Report on The Programming Language Modula-2', -as it appeared in [1], -from now on referred to as 'the Report'. -Also, -the Report sometimes leaves room for interpretation. -The section numbers -mentioned are the section numbers of the Report. -.SS "Syntax (section 2)" -.PP -The syntax recognized is that of the Report, -with some extensions to -also recognize the syntax of an earlier definition, -given in [2]. -Only one compilation unit per file is accepted. -.SS "Vocabulary and Representation (section 3)" -.PP -The input '\*(Cw10..\fR' is parsed as two tokens: '\*(Cw10\fR' and '\*(Cw..\fR'. -.PP -The empty string \*(Cw""\fR has type -.XS -.CW -ARRAY [0 .. 0] OF CHAR -.ft P -.XE -and contains one character: \*(Cw0C\fR. -.PP -When the text of a comment starts with a '\*(Cw$\fR', -it may be a pragma. -Currently, -the following pragmas exist: -.nf -.SP -.CW -(*$F (F stands for Foreign) *) -(*$R[+|-] (Runtime checks, on or off, default on) *) -(*$A[+|-] (Array bound checks, on or off, default off) *) -(*$U (Allow for underscores within identifiers) *) -.ft P -.SP -.fi -The Foreign pragma is only meaningful in a \*(CwDEFINITION MODULE\fR, -and indicates that this -\*(CwDEFINITION MODULE\fR describes an interface to a module written in another -language (for instance C or Pascal). -Runtime checks that can be disabled are: -range checks, -\*(CwCARDINAL\fR overflow checks, -checks when assigning a \*(CwCARDINAL\fR to an \*(CwINTEGER\fR and vice versa, -and checks that \*(CwFOR\fR-loop control-variables are not changed -in the body of the loop. -Array bound checks can be enabled, -because many EM implementations do not -implement the array bound checking of the EM array instructions. -When enabled, -the compiler generates a check before generating an -EM array instruction. -Even when underscores are enabled, -they still may not start an identifier. -.PP -Constants of type \*(CwLONGINT\fR are integers with a suffix letter \*(CwD\fR -(for instance \*(Cw1987D\fR). -Constants of type \*(CwLONGREAL\fR have suffix \*(CwD\fR if a scale factor is missing, -or have \*(CwD\fR in place of \*(CwE\fR in the scale factor (f.i. \*(Cw1.0D\fR, -\*(Cw0.314D1\fR). -This addition was made, -because there was no way to indicate long constants, -and also because the addition was made in Wirth's newest Modula-2 compiler. -.SS "Declarations and scope rules (section 4)" -.PP -Standard identifiers are predeclared, -and valid in all -parts of a program. -They are called \fIpervasive\fR. -Unfortunately, -the Report does not state how this pervasiveness is accomplished. -However, -page 87 of [1] states: 'Standard identifiers are automatically -imported into all modules'. -Our implementation therefore allows -redeclarations of standard identifiers within procedures, -but not within -modules. -.SS "Constant expressions (section 5)" -.PP -Each operand of a constant expression must be a constant: -a string, -a number, -a set, -an enumeration literal, -a qualifier denoting a -constant expression, -a type transfer with a constant argument, -or one of the standard procedures -\*(CwABS\fR, -\*(CwCAP\fR, -\*(CwCHR\fR, -\*(CwLONG\fR, -\*(CwMAX\fR, -\*(CwMIN\fR, -\*(CwODD\fR, -\*(CwORD\fR, -\*(CwSIZE\fR, -\*(CwSHORT\fR, -\*(CwTSIZE\fR, -or \*(CwVAL\fR, -with constant argument(s); -\*(CwTSIZE\fR and \*(CwSIZE\fR may also have a variable as argument. -.SS "Type declarations (section 6)" -.LP -.ft I -1. Basic types (section 6.1) -.PP -The type \*(CwCHAR\fR includes the ASCII character set as a subset. -Values range from -\*(Cw0C\fR to \*(Cw377C\fR, -not from \*(Cw0C\fR to \*(Cw177C\fR. -.LP -.ft I -2. Enumerations (section 6.2) -.PP -The maximum number of enumeration literals in any one enumeration type -is \*(CwMAX(INTEGER)\fR. -.LP -.ft I -3. Record types (section 6.5) -.PP -The syntax of variant sections in [1] is different from the one in [2]. -Our implementation recognizes both, -giving a warning for the older one. -.LP -.ft I -4. Set types (section 6.6) -.PP -The only limitation imposed by the compiler is that the base type of the -set must be a subrange type, -an enumeration type, -\*(CwCHAR\fR, -or \*(CwBOOLEAN\fR. -So, -the lower bound may be negative. -However, -if a negative lower bound is used, -the compiler gives a warning of the \fIrestricted\fR class. -.PP -The standard type \*(CwBITSET\fR is defined as -.XS -.CW -TYPE BITSET = SET OF [0 .. 8*SIZE(INTEGER)-1]; -.ft P -.XE -.SS "Expressions (section 8)" -.LP -.ft I -1. Operators (section 8.2) -.LP -.ft I -1.1. Arithmetic operators (section 8.2.1) -.PP -The Report does not specify the priority of the unary -operators \*(Cw+\fR or \*(Cw-\fR: -It does not specify whether -.XS -.CW -- 1 + 1 -.ft P -.XE -means -.XS -.CW -- (1 + 1) -.ft P -.XE -or -.XS -.CW -(-1) + 1 -.ft P -.XE -The -.MX -Modula-2 compiler implements the second alternative. -.SS "Statements (section 9)" -.LP -.ft I -1. Assignments (section 9.1) -.PP -The Report does not define the evaluation order in an assignment. -Our compiler certainly chooses an evaluation order, -but it is explicitly left undefined. -Therefore, -programs that depend on it may cease to work later. -.PP -The types \*(CwINTEGER\fR and \*(CwCARDINAL\fR are assignment-compatible with -\*(CwLONGINT\fR, -and \*(CwREAL\fR is assignment-compatible with \*(CwLONGREAL\fR. -.LP -.ft I -2. Case statements (section 9.5) -.PP -The size of the type of the case-expression must be less than or equal to -the word-size. -.PP -The Report does not specify what happens if the value of the case-expression -does not occur as a label of any case, -and there is no \*(CwELSE\fR-part. -In our implementation, -this results in a runtime error. -.LP -.ft I -3. For statements (section 9.8) -.PP -The Report does not specify the legal types for a control variable. -Our implementation allows the basic types (except \*(CwREAL\fR), -enumeration types, -and subranges. -A runtime warning is generated when the value of the control variable -is changed by the statement sequence that forms the body of the loop, -unless runtime checking is disabled. -.LP -.ft I -4. Return and exit statements (section 9.11) -.PP -The Report does not specify which result-types are legal. -Our implementation allows any result type. -.SS "Procedure declarations (section 10)" -.PP -Function procedures must exit through a RETURN statement, -or a runtime error occurs. -.LP -.ft I -1. Standard procedures (section 10.2) -.PP -Our implementation supports \*(CwNEW\fR and \*(CwDISPOSE\fR -for backwards compatibility, -but issues warnings for their use. -.PP -Also, -some new standard procedures were added, -similar to the new standard procedures in Wirth's newest compiler: -.IP \- -\*(CwLONG\fR converts an argument of type \*(CwINTEGER\fR or \*(CwREAL\fR to the -types \*(CwLONGINT\fR or \*(CwLONGREAL\fR. -.IP \- -\*(CwSHORT\fR performs the inverse transformation, -without range checks. -.IP \- -\*(CwFLOATD\fR is analogous to \*(CwFLOAT\fR, -but yields a result of type -\*(CwLONGREAL\fR. -.IP \- -\*(CwTRUNCD\fR is analogous to \*(CwTRUNC\fR, -but yields a result of type -\*(CwLONGINT\fR. -.SS "System-dependent facilities (section 12)" -.PP -The type \*(CwBYTE\fR is added to the \*(CwSYSTEM\fR module. -It occupies a storage unit of 8 bits. -\*(CwARRAY OF BYTE\fR has a similar effect to \*(CwARRAY OF WORD\fR, -but is safer. -In some obscure cases the \*(CwARRAY OF WORD\fR mechanism does not quite -work properly. -.PP -The procedure \*(CwIOTRANSFER\fR is not implemented. -.SS "Backwards compatibility" -.PP -Besides recognizing the language as described in [1], -the compiler recognizes most of the language described in [2], -for backwards compatibility. -It warns the user for old-fashioned -constructions (constructions that [1] does not allow). -If the \fI\(en3\fR option is passed to \fIm2\fR, -this backwards compatibility feature is disabled. -.SS "Compile time errors" -.PP -The compile time error messages are intended to be self-explanatory, -and not listed here. -The compiler also sometimes issues warnings, -recognizable by a warning-classification between parentheses. -There are 3 classifications: -.IP "(old-fashioned use)" -.br -These warnings are given on constructions that are not allowed by [1], -but are allowed by [2]. -.IP (strict) -.br -These warnings are given on constructions that are supported by the -.MX -Modula-2 compiler, -but might not be supported by others. -Examples: functions returning structured types, -SET types of subranges with -negative lower bound. -.IP (warning) -.br -The other warnings, -such as warnings about variables that are never assigned, -never used, -etc. -.SS "Runtime errors" -.PP -The \fITraps\fR module enables the user to install his own runtime -error handler. -The default one just displays what happened and exits. -Basically, -a trap handler is just a procedure that takes an INTEGER as -parameter. -The INTEGER is the trap number. -This INTEGER can be one of the -EM trap numbers, -listed in [3], -or one of the numbers listed in the -\fITraps\fR definition module. -.PP -The following runtime errors may occur: -.IP "array bound error" -.br -This error is detected if the \fI\(enA\fR option is given to \fIm2\fR. -.IP "range bound error" -.br -Range bound errors are always detected, -unless runtime checks are disabled. -.IP "set bound error" -.IP "cardinal overflow" -.br -This error is detected, -unless runtime checks are disabled. -.IP "cardinal underflow" -.br -This error is detected, -unless runtime checks are disabled. -.IP "divide by 0" -.IP "divide by 0.0" -.IP "conversion error" -.br -This error occurs when assigning a negative value of type INTEGER to a -variable of type CARDINAL, -or when assigning a value of CARDINAL that is > MAX(INTEGER), -to a variable of type INTEGER. -It is detected, -unless runtime checking is disabled. -.IP "heap overflow" -.br -This might happen when ALLOCATE fails. -.IP "case error" -.br -This error occurs when non of the cases in a CASE statement are selected, -and the CASE statement has no ELSE part. -.IP "stack size of process too large" -.br -This is most likely to happen if the reserved space for a coroutine stack -is too small. -In this case, -increase the size of the area given to -\*(CwNEWPROCESS\fR. -It can also happen if the stack needed for the main -process is too large and there are coroutines. -In this case, -the only fix is to reduce the stack size needed by the main process, -f.i. by avoiding local arrays. -.IP "too many nested traps + handlers" -.br -This error can only occur when the user has installed his own trap handler. -It means that during execution of the trap handler another trap has occurred, -and that several times. -In some cases, -this is an error because of overflow of some internal tables. -.IP "no RETURN from function procedure" -.br -This error occurs when a function procedure does not return properly -('falls' through). -.IP "illegal instruction" -.br -This error might occur when you use floating point operations on an -implementation that does not have floating point. -.PP -In addition, -some of the library modules may give error messages. -The \fBTraps\fR-module has a suitable mechanism for this. -.SS "The procedure call interface" -.PP -Parameters are pushed on the stack in reversed order. -For VAR parameters, -its address is passed, -for value parameters its value. -The only exception to this rule is with conformant arrays. -For conformant arrays, -the address is passed, -and an array descriptor is -passed. -The descriptor is an EM array descriptor. -It consists of three -fields: the lower bound (always 0), -upper bound \(mi lower bound, -and the size of the elements. -The descriptor is pushed first. -If the parameter is a value parameter, -the called routine must make sure -that its value is never changed, -for instance by making its own copy -of the array. -.PP -When the size of the return value of a function procedure is larger than -the maximum of \*(CwSIZE(LONGREAL)\fR and twice the pointer-size, -the caller reserves this space on the stack, -above the parameters. -Callee then stores -its result there, -and returns no other value. -.SS "The Modula-2 runtime library" -.PP -The definition modules of the modules available in the -.MX -Modula-2 runtime library reside in the directory \fI/usr/lib/ack/m2\fR. -.SS References -.IP [1] -Niklaus Wirth, -.ft I -Programming in Modula-2, third, corrected edition, -.ft R -Springer-Verlag, Berlin (1985) -.IP [2] -Niklaus Wirth, -.ft I -Programming in Modula-2, -.ft R -Stringer-Verlag, Berlin (1983) -.IP [3] -A.S.Tanenbaum, J.W.Stevenson, Hans van Staveren, E.G.Keizer, -.ft I -Description of a machine architecture for use with block structured languages, -.ft R -Informatica rapport IR-81, Vrije Universiteit, Amsterdam -.SH "THE MINIX PASCAL COMPILER" -.PP -.de IT -.PP -.B BS\ \\$1: -.. -.de IS -.PP -.in +.5i -.. -.PP -This section refers to the (1982) BSI standard for Pascal [1]. -.MX -Pascal complies with the requirements of level 1 of BS 6192: 1982, with -the exceptions as listed in this section. -.PP -The standard requires an accompanying document describing the -implementation-defined and implementation-dependent features, -the reaction on errors and the extensions to standard Pascal. -These four items will be treated in the rest of this section. -.SS "Implementation-defined features" -.PP -For each implementation-defined feature mentioned in the BSI standard -we give the section number, the quotation from that section and the definition. -First we quote the definition of implementation-defined: -.PP -.RS -Possibly differing between processors, but defined for any particular -processor. -.RE -.IT 6.1.7 -Each string-character shall denote an implementation-defined value of the -required char-type. -.IS -All 7-bit ASCII characters except linefeed LF (10) are allowed. -.IT 6.4.2.2 -The values of type real shall be an implementation-defined subset -of the real numbers denoted as specified by 6.1.5 by the signed-real values. -.IS -The set of real values range from a low of \(mi1.7976931348623157e+308 to -a high of 1.7976931348623157e+308. -.IT 6.4.2.2 -The type char shall be the enumeration of a set of implementation-defined -characters, some possibly without graphic representations. -.IS -The 7-bit ASCII character set is used, where LF (10) denotes the -end-of-line marker on text-files. -.IT 6.4.2.2 -The ordinal numbers of the character values shall be values of integer-type, -that are implementation-defined, and that are determined by mapping -the character values on to consecutive non-negative integer values -starting at zero. -.IS -The normal ASCII ordering is used: ord('0')=48, ord('A')=65, ord('a')=97, etc. -.IT 6.6.5.2 -The post-assertions imply corresponding activities on the external entities, -if any, to which the file-variables are bound. -These activities, and the -point at which they are actually performed, shall be -implementation-defined. -.IS -The reading and writing writing of objects on files is buffered. -This means that when a program terminates abnormally, I/O may be -unfinished. -Terminal I/O is unbuffered. -Files are closed whenever they are rewritten or reset, or on -program termination. -.IT 6.7.2.2 -The predefined constant \fImaxint\fR shall be of integer-type and shall denote -an implementation-defined value, that satisfies the following conditions: -.IP (a) -All integral values in the closed interval from \fI\(mimaxint\fR to \fI+maxint\fR -shall be values of the integer-type. -.IP (b) -Any monadic operation performed on an integer value in this interval -shall be correctly performed according to the mathematical rules for -integer arithmetic. -.IP (c) -Any dyadic integer operation on two integer values in this same interval -shall be correctly performed according to the mathematical rules for -integer arithmetic, provided that the result is also in this interval. -.IP (d) -Any relational operation on two integer values in this same interval -shall be correctly performed according to the mathematical rules for -integer arithmetic. -.SP -The representation of integers under 16-bit \*(Mp or under 68000 \*(Mx -is a 16-bit word using two's complement arithmetic. The integers range -from \(mi32768 to +32767. Under 32-bit \*(Mp a 32-bit integer is used -ranging from \(mi2147483648 to +2147483647. -.IT 6.7.2.2 -The result of the real arithmetic operators and functions shall be -approximations to the corresponding mathematical results. -The accuracy of -this approximation shall be implementation-defined -.IS -The default size of reals is 8 bytes, the accuracy is 11 bits for the exponent, -and 53 bits for the mantissa. -This gives an accuracy of about 16 digits. -and exponents ranging from \(mi307 to +307. -.IT 6.9.3.1 -The default TotalWidth values for integer, Boolean and real types -shall be implementation-defined. -.IS -The defaults are: -.XS -.ta +\w'Boolean 'u +\w'14 'u -integer 6 (16-bit) -integer 11 (32-bit) -Boolean 5 -real 14 -.DT -.XE -.IT 6.9.3.4.1 -ExpDigits, the number of digits written in an exponent part of a real, -shall be implementation-defined. -.IS -ExpDigits is defined as 3. -.IT 6.9.3.4.1 -The character written as part of the representation of -a real to indicate the beginning of the exponent part shall be -implementation-defined, either 'E' or 'e'. -.IS -The exponent part starts with 'e'. -.IT 6.9.3.5 -The case of the characters written as representation of the -Boolean values shall be implementation-defined. -.IS -The representations of true and false are 'true' and 'false'. -.IT 6.9.5 -The effect caused by the standard procedure page -on a text file shall be implementation-defined. -.IS -The ASCII character form feed FF (12) is written. -.IT 6.10 -The binding of the variables denoted by the program-parameters -to entities external to the program shall be implementation-defined if -the variable is of a file-type. -.IS -The program parameters must be files and all, except input and output, -must be declared as such in the program block. -.PP -The program parameters input and output, if specified, will correspond -with the UNIX streams 'standard input' and 'standard output'. -.PP -The other program parameters will be mapped to the argument strings -provided by the caller of this program. -The argument strings are supposed to be path names of the files to be -opened or created. -The order of the program parameters determines the mapping: -the first parameter is mapped onto the first argument string, etc. -Note that input and output are ignored in this mapping. -.PP -The mapping is recalculated each time a program parameter -is opened for reading or writing by a call to the standard procedures -reset or rewrite. -This gives the programmer the opportunity to manipulate the list -of string arguments using the external procedures argc, argv and argshift -available in the Pascal library. -.IT 6.10 -The effect of an explicit use of reset or rewrite -on the standard text files input or output shall be implementation-defined. -.IS -The procedures reset and rewrite are no-ops -if applied to input or output. -.in 0 -.SS "Implementation-dependent features" -.PP -For each implementation-dependent feature mentioned in the BSI standard, -we give the section number, the quotation from that section and the way -this feature is treated by the -.MX -Pascal system. -First we quote the definition of 'implementation-dependent': -.PP -.RS -Possibly differing between processors and not necessarily defined for any -particular processor. -.RE -.IT 6.7.2.1 -The order of evaluation of the operands of a dyadic operator -shall be implementation-dependent. -.IS -Operands are always evaluated, so the program part -.XS -if (p<>nil) and (p^.value<>0) then -.XE -is probably incorrect. -.PP -The left-hand operand of a dyadic operator is almost always evaluated -before the right-hand side. -Some peculiar evaluations exist for the following cases: -.IP 1. -The modulo operation is performed by a library routine to -check for negative values of the right operand. -.IP 2. -The expression -.XS -set1 <= set2 -.XE -where set1 and set2 are compatible set types is evaluated in the -following steps: -.XS -.ta +\w'\- 'u -\- evaluate set2; -\- evaluate set1; -\- compute set2+set1; -\- test set2 and set2+set1 for equality. -.DT -.XE -.IP 3. -The expression -.XS -set1 >= set2 -.XE -where set1 and set2 are compatible set types is evaluated in the following steps: -.XS -.ta +\w'\- 'u -\- evaluate set1; -\- evaluate set2; -\- compute set1+set2; -\- test set1 and set1+set2 for equality. -.DT -.XE -.IT 6.7.3 -The order of evaluation, accessing and binding -of the actual-parameters for functions -shall be implementation-dependent. -.IS -The order of evaluation is from right to left. -.IT 6.8.2.2 -The decision as to the order of accessing the variable and evaluating -the expression in an assignment-statement, shall be -implementation-dependent. -.IS -The expression is evaluated first. -.IT 6.8.2.3 -The order of evaluation and binding of the actual-parameters for procedures -shall be implementation-dependent. -.IS -The same as for functions. -.IT 6.9.5 -The effect of inspecting a text file to which the page -procedure was applied during generation is -implementation-dependent. -.IS -The formfeed character written by page is -treated like a normal character, with ordinal value 12. -.IT 6.10 -The binding of the variables denoted by the program-parameters -to entities external to the program shall be implementation-dependent unless -the variable is of a file-type. -.IS -Only variables of a file-type are allowed as program parameters. -.in 0 -.SS "Error handling" -.PP -There are three classes of errors to be distinguished. -In the first class are the error messages generated by the compiler. -The second class consists of the occasional errors generated by the other -programs involved in the compilation process. -Errors of the third class are the errors as defined in the standard by: -.PP -.RS -An error is a violation by a program of the requirements of this standard -that a processor is permitted to leave undetected. -.RE -.LP -.ft I -Compiler errors -.PP -Error are written on the standard error output. -Each line has the form: -.XS -, line : -.XE -Every time the compiler detects an error that does not have influence -on the code produced by the compiler or on the syntax decisions, a warning -messages is given. -If only warnings are generated, compilation proceeds and probably results -in a correctly compiled program. -.PP -Sometimes the compiler produces several errors for the same line. -They are only shown up to a maximum of 5 errors per line. -Warning are also shown up to a maximum of 5 per line. -.PP -Extensive treatment of these errors is outside the scope of this manual. -.LP -.ft I -Runtime errors -.PP -Errors detected at run time cause an error message to be generated on the -diagnostic output stream (UNIX file descriptor 2). -The message consists of the name of the program followed by a message -describing the error, possibly followed by the source line number. -Unless the \fI\(enn\fR option is turned on, the compiler generates code to keep track -of which source line causes which instructions to be generated. -.PP -For each error mentioned in the standard we give the section number, -the quotation from that section and the way it is processed by the -Pascal-compiler or runtime system. -.PP -For detected errors the corresponding message -and trap number are given. -Trap numbers are useful for exception-handling routines. -Normally, each error causes the program to terminate. -By using exception-handling routines one can -ignore errors or perform alternate actions. -Only some of the errors can be ignored -by restarting the failing instruction. -These errors are marked as non-fatal, -all others as fatal. -A list of errors with trap number between 0 and 63 -(EM errors) can be found in [2]. -Errors with trap number between 64 and 127 (Pascal errors) are listed below. -.IT 6.4.6 -It shall be an error if a value of type T2 must be -assignment-compatible with type T1, while -T1 and T2 are compatible ordinal-types and the value of -type T2 is not in the closed interval specified by T1. -.IS -The compiler distinguishes between array-index expressions and the other -places where assignment-compatibility is required. -.PP -Array subscripting errors are only detected when the 'A' option is used. -In the other cases, a range bound error occurs when the value of type T2 -is not in the closed interval specified by T1, unless range checks are -disabled. -.IT 6.4.6 -It shall be an error if a value of type T2 must be -assignment-compatible with type T1, while T1 and T2 are compatible -set-types and any member of the value of type T2 -is not in the closed interval specified by the base-type -of the type T1. -.IS -This error is not detected. -.IT 6.5.3.3 -It shall be an error if a component of a variant-part of a variant, -where the selector of the variant-part is not a field, -is accessed unless the variant is active for the entirety of each -reference and access to each component of the variant. -.IS -This error is not detected. -.IT 6.5.4 -It shall be an error if -the pointer-variable of an identified-variable either denotes a -nil-value or is undefined. -.IS -This error is not detected. -.IT 6.5.4 -It shall be an error to remove the identifying-value of an identified -variable from its pointer-type when a reference to the variable exists. -.IS -When the identified variable is an element of the record-variable-list of -a with-statement, a warning is given at compile-time. -Otherwise, this error is not detected. -.IT 6.5.5 -It shall be an error to alter the value of a file-variable f when a -reference to the buffer-variable f^ exists. -.IS -When f is altered when it is an element of the record-variable-list of a -with-statement, a warning is given. -When a buffer-variable is used as a -variable-parameter, an error is given. -This is done at compile-time. -.IT 6.6.5.2 -It shall be an error if -the stated pre-assertion does not hold immediately -prior to any use of the file handling procedures -rewrite, put, reset and get. -.IS -For each of these four operations the pre-assertions -can be reformulated as: -.XS -.ta +\w'rewrite(f): 'u -rewrite(f): no pre-assertion. -put(f): f is opened for writing and f^ is not undefined. -reset(f): f exists. -get(f): f is opened for reading and eof(f) is false. -.DT -.XE -The following errors are detected for these operations: -.SP -rewrite(f): -.in +6 -.ti -3 -more args expected, trap 64, fatal: -.br -f is a program-parameter and the corresponding -file name is not supplied by the caller of the program. -.ti -3 -rewrite error, trap 101, fatal: -.br -the caller of the program lacks the necessary -access rights to create the file in the file system -or operating system problems like table overflow -prevent creation of the file. -.in -6 -.SP -put(f): -.in +6 -.ti -3 -file not yet open, trap 72, fatal: -.br -reset or rewrite are never applied to the file. -The checks performed by the run time system are not foolproof. -.ti -3 -not writable, trap 96, fatal: -.br -f is opened for reading. -.ti -3 -write error, trap 104, fatal: -.br -probably caused by file system problems. -For instance, the file storage is exhausted. -Because I/O is buffered to improve performance, -it might happen that this error occurs if the -file is closed. -Files are closed whenever they are rewritten or reset, or on -program termination. -.in -6 -.SP -reset(f): -.in +6 -.ti -3 -more args expected, trap 64, fatal: -.br -same as for rewrite(f). -.ti -3 -reset error, trap 100, fatal: -.br -f does not exist, or the caller has insufficient access rights, or -operating system tables are exhausted. -.in -6 -.SP -get(f): -.in +6 -.ti -3 -file not yet open, trap 72, fatal: -.br -as for put(f). -.ti -3 -not readable, trap 97, fatal: -.br -f is opened for writing. -.ti -3 -end of file, trap 98, fatal: -.br -eof(f) is true just before the call to get(f). -.ti -3 -read error, trap 103, fatal: -.br -unlikely to happen. -Probably caused by hardware problems -or by errors elsewhere in your program that destroyed -the file information maintained by the run time system. -.ti -3 -truncated, trap 99, fatal: -.br -the file is not properly formed by an integer -number of file elements. -For instance, the size of a file of integer is odd. -.ti -3 -non-ASCII char read, trap 106, non-fatal: -.br -the character value of the next character-type -file element is out of range (0..127). -Only for text files. -.in -6 -.IT 6.6.5.3 -It shall be an error if a variant of a variant-part within the new -variable becomes active and a different variant of the variant-part is -one of the specified variants. -.IS -This error is not detected. -.IT 6.6.5.3 -It shall be an error to use dispose(q) if the identifying variable has been -allocated using the form new(p,c1,...,cn). -.IS -This error is not detected. -However, this error can cause more memory -to be freed then was allocated. -Dispose causes a fatal trap 73 when memory already on the free -list is freed again. -.IT 6.6.5.3 -It shall be an error to use dispose(q,k1,...,km) if the identifying -variable has been allocated using the form new(p,c1,...,cn) and m is not -equal to n. -.IS -This error is not detected. -However, this error can cause more memory -to be freed then was allocated. -Dispose causes a fatal trap 73 when memory already on the free -list is freed again. -.IT 6.6.5.3 -It shall be an error if the variants of a variable to be disposed -are different from those specified by the case-constants to dispose. -.IS -This error is not detected. -.IT 6.6.5.3 -It shall be an error if the value of the pointer parameter of dispose has -nil-value or is undefined. -.IS -This error is detected for nil-value (dispose error, trap 73, fatal). -.IT 6.6.5.3 -It shall be an error if a variable created using the second form of new is -accessed by the identified variable of the variable-access of a factor, -of an assignment-statement, or of an actual-parameter. -.IS -This error is not detected. -.IT 6.6.6.2 -It shall be an error if the value of sqr(x) does not exist. -.IS -This error is detected for real-type arguments (real overflow, -trap 4, non-fatal). -.IT 6.6.6.2 -It shall be an error if x in ln(x) is smaller than or equal to 0. -.IS -This error is detected (error in ln, trap 66, non-fatal) -.IT 6.6.6.2 -It shall be an error if x in sqrt(x) is smaller than 0. -.IS -This error is detected (error in sqrt, trap 67, non-fatal) -.SP -In addition to these errors, overflow in the expression exp(x) is -detected (error in exp, trap 65, non-fatal; real overflow, trap 4, non-fatal) -.IT 6.6.6.3 -It shall be an error if -the integer value of trunc(x) does not exist. -.IS -This error is detected (conversion error, trap 10, non-fatal). -.IT 6.6.6.3 -It shall be an error if -the integer value of round(x) does not exist. -.IS -This error is detected (conversion error, trap 10, non-fatal). -.IT 6.6.6.4 -It shall be an error if -the integer value of ord(x) does not exist. -.IS -This error can not occur, because the compiler will not allow -such ordinal types. -.IT 6.6.6.4 -It shall be an error if -the character value of chr(x) does not exist. -.IS -This error is detected (range bound error, trap 1, non-fatal). -.IT 6.6.6.4 -It shall be an error if the value of succ(x) does not exist. -.IS -Same comments as for chr(x). -.IT 6.6.6.4 -It shall be an error if the value of pred(x) does not exist. -.IS -Same comments as for chr(x). -.IT 6.6.6.5 -It shall be an error if f in eof(f) is undefined. -.IS -This error is detected (file not yet open, trap 72, fatal). -.IT 6.6.6.5 -It shall be an error if -f in eoln(f) is undefined, or if eof(f) is true at that time. -.IS -The following errors may occur: -.IS -file not yet open, trap 72, fatal; -.br -not readable, trap 97, fatal; -.br -end of file, trap 98, fatal. -.IT 6.7.1 -It shall be an error if a variable-access used as an operand -in an expression is undefined at the time of its use. -.IS -The compiler performs some limited checks to see if identifiers are -used before they are set. -Since it can not always be sure (one could, for -instance, jump out of a loop), only a warning is generated. -When an -expression contains a function-call, an error occurs if the -function is not assigned at run-time. -.IT 6.7.2.2 -A term of the form x/y shall be an error if y is zero. -.IS -This error is detected (divide by 0.0, trap 7, non-fatal). -.IT 6.7.2.2 -It shall be an error if j is zero in 'i div j'. -.IS -This error is detected (divide by 0, trap 6, non-fatal). -.IT 6.7.2.2 -It shall be an error if -j is zero or negative in i MOD j. -.IS -This error is detected (only positive j in 'i mod j', trap 71, non-fatal). -.IT 6.7.2.2 -It shall be an error if the result of any operation on integer -operands is not performed according to the mathematical -rules for integer arithmetic. -.IS -This implementation does not detect integer overflow. -.IT 6.8.3.5 -It shall be an error if none of the case-constants is equal to the -value of the case-index upon entry to the case-statement. -.IS -This error is detected (case error, trap 20, fatal). -.IT 6.9.1 -It shall be an error if the sequence of characters read looking for an -integer does not form a signed-integer as specified in 6.1.5. -.IS -This error is detected (digit expected, trap 105, non-fatal). -.IT 6.9.1 -It shall be an error if the sequence of characters read looking for a -real does not form a signed-number as specified in 6.1.5. -.IS -This error is detected (digit expected, trap 105, non-fatal). -.IT 6.9.1 -When read is applied to f, it shall be an error if the buffer-variable f^ -is undefined or the pre-assertions for get do not hold. -.IS -This error is detected (see get(f)). -.IT 6.9.3 -When write is applied to a text file f, it shall be an error if f is -undefined or f is opened for reading. -.IS -This error is detected (see put(f)). -Furthermore, this error is also -detected when f is not a text file. -.IT 6.9.3.1 -The values of TotalWidth or FracDigits shall be greater than or equal to -one; it shall be an error if either value is less then one. -.IS -When either value is less than zero, an error (illegal field width, trap -75, non-fatal) occurs. -Zero values are allowed, in order to maintain some -compatibility with the old -.MX -Pascal compiler. -.IT 6.9.5 -It shall be an error if the pre-assertion required for writeln(f) doe not -hold prior to the invocation of page(f); -.IS -This error is detected (see put(f)). -.in 0 -.SS "Extensions to the standard" -.LP -.ft I -1. External routines -.LP -Except for the required directive 'forward' the -.MX -Pascal compiler recognizes -the directive 'extern'. -This directive tells the compiler that the procedure block of this -procedure will not be present in the current program. -The code for the body of this procedure must be included at a later -stage of the compilation process. -.PP -This feature allows one to build libraries containing often used routines. -These routines do not have to be included in all the programs using them. -Maintenance is much simpler if there is only one library module to be -changed instead of many Pascal programs. -.PP -Another advantage is that these library modules may be written in a different -language, for instance C. -.PP -The use of external routines, however, is dangerous. -The compiler normally checks for the correct number and type of parameters -when a procedure is called and for the result type of functions. -If an external routine is called these checks are not sufficient, -because the compiler can not check whether the procedure heading of the -external routine as given in the Pascal program matches the actual routine -implementation. -It should be the loader's task to check this. -However, the current loaders are not that smart. -.PP -For those who wish the use the interface between C and Pascal we -give an incomplete list of corresponding formal parameters in C and Pascal. -.SP -.XS -.ta +\w'function a(pars):type 'u -\fBPascal C\fR -a:integer int a -a:char int a -a:boolean int a -a:real double a -a:^type type *a -var a:type type *a -procedure a(pars) struct { - void (*a)() ; - char *static_link ; - } -function a(pars):type struct { - type (*a)() ; - char *static_link ; - } -.DT -.XE -The Pascal runtime system uses the following algorithm when calling -function/procedures passed as parameters. -.XS -if (static_link) { - (*a)(static_link, pars); -} else { - (*a)(pars); -} -.XE -.LP -.ft I -2. Separate compilation. -.LP -The compiler is able to (separately) compile a collection of declarations, -procedures and functions to form a library. -The library may be linked with the main program, compiled later. -The syntax of these modules is -.XS -.in +\w'module = 'u -.ti -\w'module = 'u -module = [constant-definition-part] -[type-definition-part] -[var-declaration-part] -[procedure-and-function-declaration-part] -.in -\w'module = 'u -.XE -The compiler accepts a program or a module: -.XS -unit = program | module -.XE -All variables declared outside a module must be imported -by parameters, even the files input and output. -Access to a variable declared in a module is only possible -using the procedures and functions declared in that same module. -By giving the correct procedure/function heading followed by the -directive 'extern' you may use procedures and functions declared in -other units. -.LP -.ft I -3. Assertions. -.LP -When the s-option is off, -.MX -Pascal compiler recognizes an additional -statement, the assertion. -Assertions can be used as an aid in debugging -and documentation. -The syntax is: -.XS -assertion = 'assert' Boolean-expression -.XE -An assertion is a simple-statement, so -.XS -.in +\w'simple-statement = ['u -.ti -\w'simple-statement = ['u -simple-statement = [assignment-statement | -procedure-statement | -goto-statement | -assertion -.in -\w'['u -] -.in -\w'simple-statement = 'u -.XE -An assertion causes an error if the Boolean-expression is false. -That is its only purpose. -It does not change any of the variables, at least it should not. -Therefore, do not use functions with side-effects in the Boolean-expression. -If the a-option is turned on, then assertions are skipped by the -compiler. 'assert' is not a word-symbol (keyword) and may be used as identifier. -However, assignment to a variable and calling of a procedure with that -name will be impossible. -If the s-option is turned on, the compiler will not know a thing about -assertions, so using assertions will then give a parse error. -.LP -.ft I -4. Additional procedures. -.LP -Three additional standard procedures are available: -.IP "halt:" -a call of this procedure is equivalent to jumping to the -end of your program. -It is always the last statement executed. -The exit status of the program may be supplied -as optional argument. -If not, it will be zero. -.IP release: -.IP mark: -for most applications it is sufficient to use the heap as second stack. -Mark and release are suited for this type of use, more suited than dispose. -mark(p), with p of type pointer, stores the current value of the -heap pointer in p. release(p), with p initialized by a call -of mark(p), restores the heap pointer to its old value. -All the heap objects, created by calls of new between the call of -mark and the call of release, are removed and the space they used -can be reallocated. -Never use mark and release together with dispose! -.RE -.LP -.ft I -5. UNIX interfacing. -.LP -If the c-option is turned on, then some special features are available -to simplify an interface with the UNIX environment. -First of all, the compiler allows you to use a different type -of string constants. -These string constants are delimited by double quotes ('"'). -To put a double quote into these strings, you must repeat the double quote, -like the single quote in normal string constants. -These special string constants are terminated by a zero byte (chr(0)). -The type of these constants is a pointer to a packed array of characters, -with lower bound 1 and unknown upper bound. -.br -Secondly, the compiler predefines a new type identifier 'string' denoting -this just described string type. -.PP -The only thing you can do with these features is declaration of -constants and variables of type 'string'. -String objects may not be allocated on the heap and string pointers -may not be de-referenced. -Still these strings are very useful in combination with external routines. -The procedure write is extended to print these zero-terminated -strings correctly. -.LP -.ft I -6. Double length (32 bit) integers. -.LP -If the d-option is turned on, then the additional type 'long' is known -to the compiler. -Long variables have integer values in the -range \(mi2147483648 .. +2147483647. -Long constants can not be declared. -Longs can not be used as control-variables. -It is not allowed to form subranges of type long. -All operations allowed on integers are also -allowed on longs and are indicated by the same -operators: '+', '-', '*', '/', 'div', 'mod'. -The procedures read and write have been extended to handle long -arguments correctly. -It is possible to read longs from a file of integers -and vice-versa, but only if longs and integers have the same size. -The default width for longs is 11. -The standard procedures 'abs' and 'sqr' have been extended to work -on long arguments. -Conversion from integer to long, long to real, -real to long and long to integer are automatic, like the conversion -from integer to real. -These conversions may cause a -.PP -.RS -conversion error, trap 10, non-fatal -.RE -.LP -.ft I -7. Underscore as letter. -.LP -The character '_' may be used in forming identifiers, if the u- or U-option -is turned on. -It is forbidden to start identifiers with underscores, since -this may cause name-clashes with run-time routines. -.LP -.ft I -8. Zero field width in write. -.LP -Zero TotalWidth arguments are allowed. -In this case, no characters are written for -character, string or Boolean type arguments. -A zero FracDigits -argument for fixed-point representation of reals causes the fraction and -the character '.' to be suppressed. -.LP -.ft I -9. Pre-processing. -.LP -If the very first character of a file containing a Pascal -program is the sharp ('#', ASCII 23(hex)) the file is preprocessed -in the same way as C programs. -Lines beginning with a '#' are taken as preprocessor command lines -and not fed to the Pascal compiler proper. -C style comments, /*......*/, are removed by the C preprocessor, -thus C comments inside Pascal programs are also removed when they -are fed through the preprocessor. -.in 0 -.SS "Deviations from the standard" -.PP -.MX -Pascal deviates from the standard in the following ways: -.IP 1. -Standard procedures and functions are not allowed as parameters in -.MX -Pascal. -You can obtain the same result with negligible loss of performance -by declaring some user routines like: -.XS -.CW -function sine(x:real):real; -begin - sine:=sin(x) -end; -.ft R -.XE -.IP 2. -The standard procedures read, readln, write and writeln are implemented as -word-symbols, and can therefore not be redeclared. -.SS "Compiler options" -.PP -Some options of the compiler may be controlled by using '{$....}'. -Each option consists of a lower case letter followed by +, \(mi or an unsigned -number. -Options are separated by commas. -The following options exist: -.IP a+/\(mi -This option switches assertions on and off. -If this option is on, then code is included to test these assertions -at run time. -Default +. -.IP c+/\(mi -This option, if on, allows you to use C-type string constants -surrounded by double quotes. -Moreover, a new type identifier 'string' is predefined. -Default \(mi. -.IP d+/\(mi -This option, if on, allows you to use variables of type 'long'. -Default \(mi. -.IP i -.br -With this flag the setsize for a set of integers can be -manipulated. -The number must be the number of bits per set. -The default value is 16. -.IP l+/\(mi -If + then code is inserted to keep track of the source line number. -When this flag is switched on and off, an incorrect line number may appear -if the error occurs in a part of your program for which this flag is off. -Default +. -.IP r+/\(mi -If + then code is inserted to check subrange variables against -lower and upper subrange limits. -Default +. -.IP s+/\(mi -If + then the compiler will hunt for places in your program -where non-standard features are used, and for each place found -it will generate a warning. -Default \(mi. -.IP t+/\(mi -If + then each time a procedure is entered, the routine 'procentry' is -called, and each time a procedure exits, the procedure 'procexit' is -called. -Both 'procentry' and 'procexit' have a 'string' as parameter. -This means that when a user specifies his or her own procedures, the c-option -must be used. -Default procedures are present in the run time library. -Default \(mi. -.IP u+/\(mi -If + then the character '_' is treated like a letter, -so that it may be used in identifiers. -Procedure and function identifiers are not allowed to start with an -underscore because they may collide with library routine names. -Default \(mi. -.PP -Some of these flags (c, d, i, s, u, C and U) are only effective when -they appear before the 'program' symbol. -The others may be switched -on and off. -.PP -A very powerful debugging tool is the knowledge that inaccessible statements -and useless tests are removed by the optimizer. -For instance, a statement like: -.XS -.CW -if debug then - writeln('initialization done'); -.ft R -.XE -is completely removed by the optimizer if debug is a constant with -value false. -The first line is removed if debug is a constant with value true. -Of course, if debug is a variable nothing can be removed. -.SS "Library routines" -.PP -The following library of external routines for Pascal programs is available: -.nf -.SP -.CW -.ta 12n -const bufsize = ?; -type br1 = 1..bufsize; - br2 = 0..bufsize; - br3 = -1..bufsize; - ok = -1..0; - buf = packed array[br1] of char; - alfa = packed array[1..8] of char; - string = ^packed array[1..?] of char; - filetype = file of ?; - long = ?; -.SP -{all routines must be declared extern} -.SP -function argc:integer; -function argv(i:integer):string; -function environ(i:integer):string; -procedure argshift; -.SP -procedure buff(var f:filetype); -procedure nobuff(var f:filetype); -procedure notext(var f:text); -procedure diag(var f:text); -procedure pcreat(var f:text; s:string); -procedure popen(var f:text; s:string); -procedure pclose(var f:filetype); -.SP -procedure trap(err:integer); -procedure encaps(procedure p; procedure q(n:integer)); -.SP -function perrno:integer; -function uread(fd:integer; var b:buf; len:br1):br3; -function uwrite(fd:integer; var b:buf; len:br1):br3; -.SP -function strbuf(var b:buf):string; -function strtobuf(s:string; var b:buf; len:br1):br2; -function strlen(s:string):integer; -function strfetch(s:string; i:integer):char; -procedure strstore(s:string; i:integer; c:char); -.SP -function clock:integer; -.fi -.ft R -.PP -This library contains some often used external routines for Pascal programs. -The routines can be divided into several categories: -.PP -.ti -2 -Argument control: -.RS -.IP argc 10 -Gives the number of arguments provided when the program is called. -.IP argv -Selects the specified argument from the argument list and returns a -pointer to it. -This pointer is nil if the index is out of bounds (<0 or >=argc). -.IP environ -Returns a pointer to the i-th environment string (i>=0). -Returns nil -if i is beyond the end of the environment list (UNIX version 7). -.IP argshift -Effectively deletes the first argument from the argument list. -Its function is equivalent to \fIshift\fR in the UNIX shell: argv[2] becomes -argv[1], argv[3] becomes argv[2], etc. -It is a useful procedure to skip optional flag arguments. -Note that the matching of arguments and files -is done at the time a file is opened by a call to reset or rewrite. -.PP -.ti -2 -Additional file handling routines: -.IP buff -Turn on buffering of a file. -Not very useful, because all -files are buffered except standard output to a terminal and diagnostic output. -Input files are always buffered. -.IP nobuff -Turn off buffering of an output file. -It causes the current contents of the -buffer to be flushed. -.IP notext -Only useful for input files. -End of line characters are not replaced by a space and character codes out of -the ASCII range (0..127) do not cause an error message. -.IP diag -Initialize a file for output on the diagnostic output stream (fd=2). -Output is not buffered. -.IP pcreat -The same as rewrite(f), except that you must provide the file name yourself. -The name must be zero terminated. -Only text files are allowed. -.IP popen -The same as reset(f), except that you must provide the file name yourself. -The name must be zero terminated. -Only text files are allowed. -.IP pclose -Gives you the opportunity to close files hidden in records or arrays. -All other files are closed automatically. -.PP -.ti -2 -String handling: -.IP strbuf -Type conversion from character array to string. -It is your own responsibility that the string is zero terminated. -.IP strtobuf -Copy string into buffer until the string terminating zero byte -is found or until the buffer if full, whatever comes first. -The zero byte is also copied. -The number of copied characters, excluding the zero byte, is returned. -So if -the result is equal to the buffer length, then the end of buffer is reached -before the end of string. -.IP strlen -Returns the string length excluding the terminating zero byte. -.IP strfetch -Fetches the i-th character from a string. -There is no check against the string length. -.IP strstore -Stores a character in a string. -There is no check against -string length, so this is a dangerous procedure. -.PP -.ti -2 -Trap handling: -.PP -These routines allow you to handle almost all -the possible error situations yourself. -You may define your own trap handler, replacing the -default handler that produces an error message and quits. -You may also generate traps yourself. -.IP trap -Trap generates the trap passed as argument (0..252). -The trap numbers 128..252 may be used freely. -The others are reserved. -.IP encaps -Encapsulate the execution of \fIp\fR with the trap handler \fIq\fR. -Encaps replaces the previous trap handler by \fIq\fR, calls \fIp\fR -and restores -the previous handler when \fIp\fR returns. -If, during the execution of \fIp\fR, a trap occurs, -then \fIq\fR is called with the trap number as parameter. -For the duration of \fIq\fR the previous trap handler is restored, so that -you may handle only some of the errors in \fIq\fR. -All the other errors must -then be raised again by a call to \fItrap\fR. -.br -Encapsulations may be nested: you may encapsulate a procedure while executing -an encapsulated routine. -.br -Jumping out of an encapsulated procedure (non-local goto) is dangerous, -because the previous trap handler must be restored. -Therefore, you may only jump out of procedure \fIp\fR from inside \fIq\fR and -you may only jump out of one level of encapsulation. -If you want to exit several levels of encapsulation, use traps. -See pc_prlib(7) for lists of trap numbers -for EM machine errors and Pascal run time system errors. -Note that \fIp\fR may not have parameters. -.PP -.ti -2 -UNIX system calls: -.IP uread -Equal to the read system call. -Its normal name is blocked by the standard Pascal routine read. -.IP uwrite -As above but for write(2). -.IP perrno -Because external data references are not possible in Pascal, -this routine returns the global variable \fIerrno\fR, indicating the result of -the last system call. -.PP -.ti -2 -Miscellaneous: -.IP clock -Return the number of ticks of user and system time consumed by the program. -.PP -The following program presents an example of how these routines can be used. -This program is equivalent to the UNIX command cat(1). -.nf -.SP -.CW -{$c+} -.CW -program cat(input,inp,output); -.CW -var inp:text; -.CW - s:string; -.SP -.CW -function argc:integer; extern; -.CW -function argv(i:integer):string; extern; -.CW -procedure argshift; extern; -.CW -function strlen(s:string):integer; extern; -.CW -function strfetch(s:string; i:integer):char; extern; -.SP -.CW -procedure copy(var fi:text); -.CW -var c:char; -.CW -begin reset(fi); -.CW - while not eof(fi) do -.CW - begin -.CW - while not eoln(fi) do -.CW - begin -.CW - read(fi,c); -.CW - write(c) -.CW - end; -.CW - readln(fi); -.CW - writeln -.CW - end -.CW -end; -.SP -.CW -begin {main} -.CW - if argc = 1 then -.CW - copy(input) -.CW - else -.CW - repeat -.CW - s := argv(1); -.CW - if (strlen(s) = 1) and (strfetch(s,1) = '-') -.CW - then copy(input) -.CW - else copy(inp); -.CW - argshift; -.CW - until argc <= 1; -.CW -end. -.fi -.ft R -.PP -Another example gives some idea of the way to manage trap handling: -.nf -.SP -.CW -program bigreal(output); -.CW -const EFOVFL=4; -.CW -var trapped:boolean; -.CW -.SP -.CW -procedure encaps(procedure p; procedure q(n:integer)); extern; -.CW -procedure trap(n:integer); extern; -.CW -.SP -.CW -procedure traphandler(n:integer); -.CW -begin if n=EFOVFL then trapped:=true else trap(n) end; -.CW -.SP -.CW -procedure work; -.CW -var i,j:real; -.CW -begin trapped:=false; i:=1; -.CW - while not trapped do -.CW - begin j:=i; i:=i*2 end; -.CW - writeln('bigreal = ',j); -.CW -end; -.CW -.SP -.CW -begin -.CW - encaps(work,traphandler); -.CW -end. -.fi -.ft R -.PP -Two routines may cause fatal error messages to be generated. -These are: -.IP pcreat -Rewrite error (trap 77) if the file cannot be created. -.IP popen -Reset error (trap 76) if the file cannot be opened for reading -.SS References -.IP [1] -BSI standard BS 6192: 1982 (ISO 7185). -.IP [2] -A.S.Tanenbaum, J.W.Stevenson, Hans van Staveren, E.G.Keizer, -"Description of a machine architecture for use with block structured languages", -Informatica rapport IR-81. Index: trunk/minix/man/man7/ascii.7 =================================================================== --- trunk/minix/man/man7/ascii.7 (revision 9) +++ (revision ) @@ -1,76 +1,0 @@ -.TH ASCII 7 -.SH NAME -ascii \- the ASCII character set. -.SH DESCRIPTION -The ASCII character set is as follows: -.PP -.nf -.if t .ft C -|000 nul|001 soh|002 stx|003 etx|004 eot|005 enq|006 ack|007 bel| -|010 bs |011 ht |012 nl |013 vt |014 np |015 cr |016 so |017 si | -|020 dle|021 dc1|022 dc2|023 dc3|024 dc4|025 nak|026 syn|027 etb| -|030 can|031 em |032 sub|033 esc|034 fs |035 gs |036 rs |037 us | -|040 sp |041 ! |042 " |043 # |044 $ |045 % |046 & |047 ' | -|050 ( |051 ) |052 * |053 + |054 , |055 - |056 . |057 / | -|060 0 |061 1 |062 2 |063 3 |064 4 |065 5 |066 6 |067 7 | -|070 8 |071 9 |072 : |073 ; |074 < |075 = |076 > |077 ? | -|100 @ |101 A |102 B |103 C |104 D |105 E |106 F |107 G | -|110 H |111 I |112 J |113 K |114 L |115 M |116 N |117 O | -|120 P |121 Q |122 R |123 S |124 T |125 U |126 V |127 W | -|130 X |131 Y |132 Z |133 [ |134 \e |135 ] |136 ^ |137 _ | -|140 ` |141 a |142 b |143 c |144 d |145 e |146 f |147 g | -|150 h |151 i |152 j |153 k |154 l |155 m |156 n |157 o | -|160 p |161 q |162 r |163 s |164 t |165 u |166 v |167 w | -|170 x |171 y |172 z |173 { |174 | |175 } |176 ~ |177 del| - -|00 nul|01 soh|02 stx|03 etx|04 eot|05 enq|06 ack|07 bel| -|08 bs |09 ht |0A nl |0B vt |0C np |0D cr |0E so |0F si | -|10 dle|11 dc1|12 dc2|13 dc3|14 dc4|15 nak|16 syn|17 etb| -|18 can|19 em |1A sub|1B esc|1C fs |1D gs |1E rs |1F us | -|20 sp |21 ! |22 " |23 # |24 $ |25 % |26 & |27 ' | -|28 ( |29 ) |2A * |2B + |2C , |2D - |2E . |2F / | -|30 0 |31 1 |32 2 |33 3 |34 4 |35 5 |36 6 |37 7 | -|38 8 |39 9 |3A : |3B ; |3C < |3D = |3E > |3F ? | -|40 @ |41 A |42 B |43 C |44 D |45 E |46 F |47 G | -|48 H |49 I |4A J |4B K |4C L |4D M |4E N |4F O | -|50 P |51 Q |52 R |53 S |54 T |55 U |56 V |57 W | -|58 X |59 Y |5A Z |5B [ |5C \e |5D ] |5E ^ |5F _ | -|60 ` |61 a |62 b |63 c |64 d |65 e |66 f |67 g | -|68 h |69 i |6A j |6B k |6C l |6D m |6E n |6F o | -|70 p |71 q |72 r |73 s |74 t |75 u |76 v |77 w | -|78 x |79 y |7A z |7B { |7C | |7D } |7E ~ |7F del| - -.if t .ft P -.nf -.bp -These are what your terminal shows for the top 96 codes: -.PP -.nf -.if t .ft C -|240   |241 ¡ |242 ¢ |243 £ |244 € |245 ¥ |246 Š |247 § | -|250 š |251 © |252 ª |253 « |254 ¬ |255 ­ |256 ® |257 ¯ | -|260 ° |261 ± |262 ² |263 ³ |264 Ž |265 µ |266 ¶ |267 · | -|270 ž |271 ¹ |272 º |273 » |274 Œ |275 œ |276 Ÿ |277 ¿ | -|300 À |301 Á |302  |303 à |304 Ä |305 Å |306 Æ |307 Ç | -|310 È |311 É |312 Ê |313 Ë |314 Ì |315 Í |316 Î |317 Ï | -|320 Ð |321 Ñ |322 Ò |323 Ó |324 Ô |325 Õ |326 Ö |327 × | -|330 Ø |331 Ù |332 Ú |333 Û |334 Ü |335 Ý |336 Þ |337 ß | -|340 à |341 á |342 â |343 ã |344 ä |345 å |346 æ |347 ç | -|350 è |351 é |352 ê |353 ë |354 ì |355 í |356 î |357 ï | -|360 ð |361 ñ |362 ò |363 ó |364 ô |365 õ |366 ö |367 ÷ | -|370 ø |371 ù |372 ú |373 û |374 ü |375 ý |376 þ |377 ÿ | - -|A0   |A1 ¡ |A2 ¢ |A3 £ |A4 € |A5 ¥ |A6 Š |A7 § | -|A8 š |A9 © |AA ª |AB « |AC ¬ |AD ­ |AE ® |AF ¯ | -|B0 ° |B1 ± |B2 ² |B3 ³ |B4 Ž |B5 µ |B6 ¶ |B7 · | -|B8 ž |B9 ¹ |BA º |BB » |BC Œ |BD œ |BE Ÿ |BF ¿ | -|C0 À |C1 Á |C2  |C3 à |C4 Ä |C5 Å |C6 Æ |C7 Ç | -|C8 È |C9 É |CA Ê |CB Ë |CC Ì |CD Í |CE Î |CF Ï | -|D0 Ð |D1 Ñ |D2 Ò |D3 Ó |D4 Ô |D5 Õ |D6 Ö |D7 × | -|D8 Ø |D9 Ù |DA Ú |DB Û |DC Ü |DD Ý |DE Þ |DF ß | -|E0 à |E1 á |E2 â |E3 ã |E4 ä |E5 å |E6 æ |E7 ç | -|E8 è |E9 é |EA ê |EB ë |EC ì |ED í |EE î |EF ï | -|F0 ð |F1 ñ |F2 ò |F3 ó |F4 ô |F5 õ |F6 ö |F7 ÷ | -|F8 ø |F9 ù |FA ú |FB û |FC ü |FD ý |FE þ |FF ÿ | -.if t .ft P -.nf Index: trunk/minix/man/man7/environ.7 =================================================================== --- trunk/minix/man/man7/environ.7 (revision 9) +++ (revision ) @@ -1,111 +1,0 @@ -.\" Copyright (c) 1983 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. -.\" -.\" @(#)environ.7 6.1 (Berkeley) 5/20/85 -.\" -.TH ENVIRON 7 "May 20, 1985" -.UC 5 -.SH NAME -environ \- user environment -.SH SYNOPSIS -.B "extern char *const *environ;" -.SH DESCRIPTION -An array of strings called the `environment' is made available by -.BR execve (2) -when a process begins. By convention these strings have the form -.RI ` name = value '. -The following names are used by various commands: -.TP "\w'TERMCAP 'u" -.B PATH -The sequence of directory prefixes that -.BR sh , -.BR time , -.BR nice (1), -etc., apply in searching for a file known by an incomplete path name. -The prefixes are separated by `:'. -Login shells set -.BR PATH=:/bin:/usr/bin . -Note that the empty space between the `=' and the `:' indicates the current -directory. Security aware people move the extra `:' to the end of their -path or omit it. -.TP -.B HOME -A user's login directory, set by -.BR login (1) -from the password file -.BR passwd (5). -.TP -.B TERM -The kind of terminal for which output is to be prepared. -This information is used by programs that wish to exploit special -terminal capabilities, a screen oriented text editor for instance. -The terminal type is set by -.BR login (1) -from the tty database -.BR ttytab (5). -.TP -.B SHELL -The file name of the users login shell, set by -.BR login (1) -from the password file -.BR passwd (5). -.TP -.B TERMCAP -The string describing the terminal in TERM, or the name of the termcap file, -see -.BR termcap (5), -.BR termcap (3). -.TP -.B EXINIT -A startup list of commands read by -.BR elvis (1). -.TP -.B USER -The login name of the user, set by -.BR login (1) -from the password file -.BR passwd (5). -.TP -.B LOGNAME -Set to the same value as -.BR USER . -BSD derived systems have -.BR USER , -System V has -.BR LOGNAME , -so modern systems have both to avoid problems. -.TP -.PP -Further names may be placed in the environment by the -.B export -command and -.RI ` name = value ' -arguments in -.BR sh (1). -Arguments may also be placed in their environment by -programs if they use -.BR putenv (3). -Or in the environment of another program by building a new environment -for one of the exec functions that accepts an environment list, like -.BR execle (2) -or -.BR execve (2). -It is unwise to conflict with certain -.BR sh (1) -variables that are frequently set and/or exported by `.profile' files: -.BR MAIL , -.BR PS1 , -.BR PS2 , -.BR IFS . -.SH SEE ALSO -.BR elvis (1), -.BR login (1), -.BR sh (1), -.BR execl (3), -.BR execve (2), -.BR system (3), -.BR termcap (3), -.BR termcap (5), -.BR passwd (5), -.BR ttytab (5). Index: trunk/minix/man/man7/hier.7 =================================================================== --- trunk/minix/man/man7/hier.7 (revision 9) +++ (revision ) @@ -1,195 +1,0 @@ -.TH HIER 7 -.SH NAME -hier \- file system hierarchy -.SH DESCRIPTION -.de SP -.if t .sp 0.4 -.if n .sp -.. -A tour through the MINIX 3 directory hierarchy. -.nf -.SP -/ root -.SP -/bin/ Utility programs, cf /usr/bin/ (1) - cat Show files, \fBcat\fP(1) - sh Shell, \fBsh\fP(1) - mount Mount file systems, \fBmount\fP(8) - ... -.SP -/boot Boot Monitor, \fBmonitor\fP(8) -.SP -/dev/ devices (4) - console - Main console, \fBtty\fP(4) - tty* Terminals, \fBtty\fP(4) - hd* Hard disk, \fBhd\fP(4) - fd* Floppy disk, \fBfd\fP(4) - ... -.SP -/etc/ System configuration and data files, cf /usr/etc/ (1,5,8) - ethers Ethernet addresses database, \fBethers\fP(5) - fstab File system table, \fBfstab\fP(5) - group Groups database, \fBgroup\fP(5) - hostname.file - Name of the local system, \fBusage\fP(5) - hosts TCP/IP hosts database, \fBhosts\fP(5) - hosts.equiv - Network equivalent hosts, \fBhosts.equiv\fP(5) - inet.conf - Inet server config file, \fBinet\fP(8) - keymap Keymap for custom keyboard, \fBloadkeys\fP(8) - motd Message of the day, \fBlogin\fP(1) - mtab Mounted file system table, \fBfstab\fP(5) - passwd User database, \fBpasswd\fP(5) - profile - System wide shell profile, \fBsh\fP(1) - rc System startup script, \fBboot\fP(8) - resolv.conf - TCP/IP domain name system, \fBresolv.conf\fP(5) - services - TCP/IP names to services, \fBservices\fP(5) - serv.access - Internet service access control, \fBserv.access\fP(5) - shadow Shadow password database, \fBpasswd\fP(5) - termcap - Terminal type descriptions, \fBtermcap\fP(5) - ttytab Terminals device table, \fBttytab\fP(5) - utmp User login database, \fBlogin\fP(1) - ... -.SP -/minix - MINIX 3 kernel image, \fBmonitor\fP(8) -.SP -/tmp/ Small, short-lived temporary files, cf /usr/tmp/ -.SP -/usr/ Home directories and more system files -.SP - adm/ System administration files (1,5,8) - lastlog - Last logins, \fBlogin\fP(1) - log - Default log file - old - Last weeks log files - wtmp - User logins and logouts, \fBlogin\fP(1) - *.cache - Cached data of some programs - ... -.SP - ast/ Honorary home directory of Andrew S. Tanenbaum - Also new user initial files -.SP - \fIuser\fP/ Home directory of \fIuser\fP - .ashrc Ash (shell) startup, \fBash\fP(1) - .ellepro.b1 - Elle (editor) startup (compiled), \fBelle\fP(1) - .ellepro.e - Elle (editor) startup (text), \fBelle\fP(1) - .exrc Ex/vi (editor) startup, \fBex\fP(1) - .profile - Custom user shell profile, \fBsh\fP(1) - .rhosts Remote user permission file, \fBrhosts\fP(5) - ... -.SP - bin/ User programs - cc C compiler, \fBcc\fP(1) - cp Copy files, \fBcp\fP(1) - ls List files, \fBls\fP(1) - man Show manual pages, \fBman\fP(1) - ... -.SP - etc/ More system data files, cf /etc (8) - rc Continued system startup, \fBboot\fP(8) - daily - Daily system cleanup - ... -.SP - include/ - C-compiler include files - minix/ MINIX 3 kernel include files - ... - ... -.SP - lib/ Compiler libraries and other support stuff - cawf/ Text formatter support files, \fBcawf\fP(1) - crontab - Cron jobs, \fBcron\fP(8) - dict/ Word lists - words American English word list, \fBlook\fP(1) - ... - libc.a C library (Minix-8086 only), \fBcc\fP(1) - \fIarch\fP Per architecture compiler binaries and - libaries, \fBcc\fP(1) - ... -.SP - local/ Local software, cf /usr/ - bin/ Local utilities - etc/ Local data files - rc Local system startup - ... - man/ Local manual pages - src/ Local sources - ... -.SP - man/ Manual pages, \fBman\fP(1) - cat*/ Preformatted manual pages - man0/ Section 0, Book style user commands - man1/ User commands - man2/ System calls - man3/ Library routines - man4/ Device files - man5/ File formats - man6/ Games - man7/ Miscellaneous - man8/ System utilities - whatis Table of manual pages, \fBwhatis\fP(5) - ... -.SP - mdec/ - boot Bootstrap code, \fBinstallboot\fP(8) - ... -.SP - preserve/ - Saved elvis editor buffers, \fBelvprsv\fP(8), \fBelvrec\fP(1) -.SP - spool/ Mail and command spooling - at/ At jobs, \fBat\fP(1) - past/ Completed at jobs - mail/ Mail drops, \fBmail\fP(1) - \fIuser\fP Mailbox of \fIuser\fP - ... - ... -.SP - src/ System and command sources (home of bin) - LICENSE - MINIX 3 license to use - commands/ - Utility sources - crclist - CRC checksums of the source tree, \fBsrccrc\fP(8) - lib/ Library sources - fs/ File system - inet/ TCP/IP task - kernel/ - Kernel - mm/ Memory manager - boot/ Boot Monitor - tools/ Kernel image making tools, \fBtools\fP(8) -.SP - tmp/ Large temporary files -.fi -.SH "SEE ALSO" -.BR ls (1), -.BR man (1), -.BR find (1), -.BR grep (1), -.BR checkhier (8). -.SH NOTES -Not all of the directories and files shown are present. They must be -created as needed. -.SH BUGS -Many of the listed manual references do not yet exist. -.SH AUTHOR -Kees J. Bot (kjb@cs.vu.nl) Index: trunk/minix/man/man7/man.7 =================================================================== --- trunk/minix/man/man7/man.7 (revision 9) +++ (revision ) @@ -1,278 +1,0 @@ -.\" man(7) manpage by rosenkra@hall.cray.com (Bill Rosenkranz) -.\" Modified a bit for MINIX 3 by Kees J. Bot (kjb@cs.vu.nl) -.\" -.TH MAN 7 -.SH NAME -man - nroff macro package for manual pages -.SH SYNOPSIS -.B nroff \-man -.IR file " ..." -.SH DESCRIPTION -.de SP -.if t .sp 0.4 -.if n .sp -.. -These macros are used to lay out reference pages for manuals. -.PP -Any text argument -.I t -may be zero to six words. Quotes may be used to include blanks in a 'word'. -.I Text -can be empty, but unlike normal \s-2UNIX\s+2 macros, the next line is not used. -.PP -A prevailing indent distance is remembered between successive -indented paragraphs, and is reset to default value upon -reaching a non-indented paragraph (i.e. at .SH or .SS). -.SH FILES -.TP 25n -/usr/lib/tmac/tmac.an -For standard MINIX 3 nroff. -.TP -/usr/lib/cawf/man.mac -For cawf. -.SH SEE ALSO -.BR nroff (1), -.BR man (1). -.SH "REQUEST SUMMARY" -.nf -.ta +15n +9n -Request Cause Explanation - Break? - -\&.B t no Text t is bold. Quote to imbed blanks. -\&.I t no Text t is italic. Quote to imbed blanks. -\&.IP x yes Set prevailing indent to 5. Begin - indented paragraph with hanging tag - given by first argument. Tag x is - always placed on a separate line. -\&.LP yes Same as .PP. -\&.PP yes Begin paragraph. Set prevailing - indent to 5. -\&.RE yes End of relative indent. Set prevailing - indent to amount of starting .RS. -\&.RS yes Start relative indent, move left margin - in distance 5. -\&.SH t yes Subhead. Quote to imbed blanks. -\&.SS t yes Subsection. Quote to imbed blanks. No - indent for t. -\&.TH n s c v d yes Begin page named n of chapter s; c is - the chapter name; d is the date of the - most recent change; v is version number. - Sets prevailing indent and tabs to 5. -.fi -.SH EXAMPLE -The following illustrates some of the requests available -with this macro package: -.RS -.nf -\&.\e" this is a comment -\&.TH DEMO 1 -\&.SH NAME -demo \e- show how to use \e-man package -\&.SH SYNOPSIS -\&.B demo -\&.RI [ options ] -\&.IR file " ..." -\&.SH DESCRIPTION -This is a test for showing how to use the -\&.BR nroff (1) -man package. It shows how to use .TH, .SH, .PP, .B, .I, and .IP -commands. -\&.PP -This will be a new paragraph. You can also use normal -\&.BR nroff (1) -commands in the text. -\&.SS Nroff Commands -\&.IP '\ee"' -This is the comment command. \e" You won't see this. -\&.IP nf -No fill mode (the normal mode is fill mode where things -get justified right and left). -\&.IP fi -Re-enter fill mode. -\&.IP br -Break line here no matter what. -\&.IP sp -Vertical space (also causes a break to occur). -\&.sp -Note that to continue an indent and make a new paragraph (as -is the case here), just put in a space (.sp). -\&.PP -Now we should be at a new paragraph. -.fi -.RE -.PP -Executing -.B nroff \-man demo.man -results in the following output: (Ignoring page headers and footers) -.PP -.RS -.B NAME -.RS -demo \e- show how to use \e-man package -.RE -.SP -.B SYNOPSIS -.RS -.B demo -.RI [ options ] -.IR file " ..." -.RE -.SP -.B DESCRIPTION -.RS -This is a test for showing how to use the -.BR nroff (1) -man package. It shows how to use .TH, .SH, .PP, .B, .I, and .IP -commands. -.SP -This will be a new paragraph. You can also use normal -.BR nroff (1) -commands in the text. -.RE -.SP -.ti +2n -.B Nroff Commands -.RS -.RS -.ta +5n -.SP -.ti -5n -\&'\e"' This is the comment command. -.SP -.ti -5n -nf No fill mode (the normal mode is fill mode where things -get justified right and left). -.SP -.ti -5n -fi Re-enter fill mode. -.SP -.ti -5n -br Break line here no matter what. -.SP -.ti -5n -sp Vertical space (also causes a break to occur). -.sp -Note that to continue an indent and make a new paragraph (as -is the case here), just put in a space (.sp). -.RE -.SP -Now we should be at a new paragraph. -.RE -.RE -.SH CONVENTIONS -A typical manual page for a command or function is laid out as follows: -.nf - - .TH TITLE [1-8] - The name of the command or function in upper-case, - which serves as the title of the manual page. This is - followed by the number of the section in which it - appears. - - .SH NAME - name - one-line summary - - The name, or list of names, by which the command is - called, followed by a dash and then a one-line summary - of the action performed. All in roman font, this sec- - tion contains no troff(1) commands or escapes, and no - macro requests. It is used to generate the whatis(1) - database. - - .SH SYNOPSIS - - Commands: - - The syntax of the command and its arguments as - typed on the command line. When in boldface, a - word must be typed exactly as printed. When in - italics, a word can be replaced with text that you - supply. Syntactic symbols appear in roman face: - - [ ] An argument, when surrounded by brackets is - optional. - - | Arguments separated by a vertical bar are - exclusive. You can supply only item from - such a list. - - ... Arguments followed by an elipsis can be - repeated. When an elipsis follows a brack- - eted set, the expression within the brackets - can be repeated. - - Functions: - - If required, the data declaration, or #include - directive, is shown first, followed by the func- - tion declaration. Otherwise, the function declara- - tion is shown. - - .SH DESCRIPTION - A narrative description of the command or function in - detail, including how it interacts with files or data, - and how it handles the standard input, standard output - and standard error. - - Filenames, and references to commands or functions - described elswhere in the manual, are italicised. The - names of options, variables and other literal terms are - in boldface. - - .SH OPTIONS - The list of options along with a description of how - each affects the commands operation. - - .SH ENVIRONMENT - Environment variables used. - - .SH FILES - A list of files associated with the command or func- - tion. - - .SH "SEE ALSO" - A comma-separated list of related manual pages, - followed by references to other published materials. - This section contains no troff(1) escapes or commands, - and no macro requests. - - .SH DIAGNOSTICS - A list of diagnostic messages and an explanation of - each. - - .SH NOTES - Any additional notes such as installation-dependent - functionality. - - .SH BUGS - A description of limitations, known defects, and possi- - ble problems associated with the command or function. - - .SH AUTHOR - The program's author and any pertinent release info. - - .SH VERSION - The program's current version number and release date. -.fi -.SH BUGS -Even though -.BR cawf (1) -has a better chance at formatting a random manual page then the standard -MINIX 3 nroff, it has two annoying bugs in its macro set. Both .PP and .IP -reset the indentation level to the level set by .SH. This means that -you can't use them in a piece of text indented by .RS. For .IP this is -troublesome, you can see why in the unformatted source of this text. .PP -can simply be replaced by .sp, or better yet, by .SP with the following -macro defined somewhere in your text: -.PP -.RS -.nf -\&.de SP -\&.if t .sp 0.4 -\&.if n .sp -\&.. -.fi -.RE -.PP -This will make .SP use 4/10 of a line if formatted by troff, just like .PP. Index: trunk/minix/man/man7/re_format.7 =================================================================== --- trunk/minix/man/man7/re_format.7 (revision 9) +++ (revision ) @@ -1,269 +1,0 @@ -.\" Copyright (c) 1992, 1993, 1994 Henry Spencer. -.\" Copyright (c) 1992, 1993, 1994 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" This code is derived from software contributed to Berkeley by -.\" Henry Spencer. -.\" -.\" 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. -.\" -.\" @(#)re_format.7 8.3 (Berkeley) 3/20/94 -.\" -.TH RE_FORMAT 7 "March 20, 1994" -.SH NAME -re_format \- POSIX 1003.2 regular expressions -.SH DESCRIPTION -Regular expressions (``RE''s), -as defined in POSIX 1003.2, come in two forms: -modern REs (roughly those of -.BR egrep ; -1003.2 calls these ``extended'' REs) -and obsolete REs (roughly those of -.BR ed ; -1003.2 ``basic'' REs). -Obsolete REs mostly exist for backward compatibility in some old programs; -they will be discussed at the end. -1003.2 leaves some aspects of RE syntax and semantics open; -`\(dg' marks decisions on these aspects that -may not be fully portable to other 1003.2 implementations. -.PP -A (modern) RE is one\(dg or more non-empty\(dg \fIbranches\fR, -separated by `|'. -It matches anything that matches one of the branches. -.PP -A branch is one\(dg or more \fIpieces\fR, concatenated. -It matches a match for the first, followed by a match for the second, etc. -.PP -A piece is an \fIatom\fR possibly followed -by a single\(dg `*', `+', `?', or \fIbound\fR. -An atom followed by `*' matches a sequence of 0 or more matches of the atom. -An atom followed by `+' matches a sequence of 1 or more matches of the atom. -An atom followed by `?' matches a sequence of 0 or 1 matches of the atom. -.PP -A \fIbound\fR is `{' followed by an unsigned decimal integer, -possibly followed by `,' -possibly followed by another unsigned decimal integer, -always followed by `}'. -The integers must lie between 0 and RE_DUP_MAX (255\(dg) inclusive, -and if there are two of them, the first may not exceed the second. -An atom followed by a bound containing one integer \fIi\fR -and no comma matches -a sequence of exactly \fIi\fR matches of the atom. -An atom followed by a bound -containing one integer \fIi\fR and a comma matches -a sequence of \fIi\fR or more matches of the atom. -An atom followed by a bound -containing two integers \fIi\fR and \fIj\fR matches -a sequence of \fIi\fR through \fIj\fR (inclusive) matches of the atom. -.PP -An atom is a regular expression enclosed in `()' (matching a match for the -regular expression), -an empty set of `()' (matching the null string)\(dg, -a \fIbracket expression\fR (see below), `.' -(matching any single character), `^' (matching the null string at the -beginning of a line), `$' (matching the null string at the -end of a line), a `\e' followed by one of the characters -`^.[$()|*+?{\e' -(matching that character taken as an ordinary character), -a `\e' followed by any other character\(dg -(matching that character taken as an ordinary character, -as if the `\e' had not been present\(dg), -or a single character with no other significance (matching that character). -A `{' followed by a character other than a digit is an ordinary -character, not the beginning of a bound\(dg. -It is illegal to end an RE with `\e'. -.PP -A \fIbracket expression\fR is a list of characters enclosed in `[]'. -It normally matches any single character from the list (but see below). -If the list begins with `^', -it matches any single character -(but see below) \fInot\fR from the rest of the list. -If two characters in the list are separated by `\-', this is shorthand -for the full \fIrange\fR of characters between those two (inclusive) in the -collating sequence, -e.g. `[0-9]' in ASCII matches any decimal digit. -It is illegal\(dg for two ranges to share an -endpoint, e.g. `a-c-e'. -Ranges are very collating-sequence-dependent, -and portable programs should avoid relying on them. -.PP -To include a literal `]' in the list, make it the first character -(following a possible `^'). -To include a literal `\-', make it the first or last character, -or the second endpoint of a range. -To use a literal `\-' as the first endpoint of a range, -enclose it in `[.' and `.]' to make it a collating element (see below). -With the exception of these and some combinations using `[' (see next -paragraphs), all other special characters, including `\e', lose their -special significance within a bracket expression. -.PP -Within a bracket expression, a collating element (a character, -a multi-character sequence that collates as if it were a single character, -or a collating-sequence name for either) -enclosed in `[.' and `.]' stands for the -sequence of characters of that collating element. -The sequence is a single element of the bracket expression's list. -A bracket expression containing a multi-character collating element -can thus match more than one character, -e.g. if the collating sequence includes a `ch' collating element, -then the RE `[[.ch.]]*c' matches the first five characters -of `chchcc'. -.PP -Within a bracket expression, a collating element enclosed in `[=' and -`=]' is an equivalence class, standing for the sequences of characters -of all collating elements equivalent to that one, including itself. -(If there are no other equivalent collating elements, -the treatment is as if the enclosing delimiters were `[.' and `.]'.) -For example, if o and \o'o^' are the members of an equivalence class, -then `[[=o=]]', `[[=\o'o^'=]]', and `[o\o'o^']' are all synonymous. -An equivalence class may not\(dg be an endpoint -of a range. -.PP -Within a bracket expression, the name of a \fIcharacter class\fR enclosed -in `[:' and `:]' stands for the list of all characters belonging to that -class. -Standard character class names are: -.PP -.RS -.nf -.ta 3c 6c 9c -alnum digit punct -alpha graph space -blank lower upper -cntrl print xdigit -.fi -.RE -.PP -These stand for the character classes defined in -.BR ctype (3). -A locale may provide others. -A character class may not be used as an endpoint of a range. -.PP -There are two special cases\(dg of bracket expressions: -the bracket expressions `[[:<:]]' and `[[:>:]]' match the null string at -the beginning and end of a word respectively. -A word is defined as a sequence of -word characters -which is neither preceded nor followed by -word characters. -A word character is an -.B alnum -character (as defined by -.BR ctype (3)) -or an underscore. -This is an extension, -compatible with but not specified by POSIX 1003.2, -and should be used with -caution in software intended to be portable to other systems. -.PP -In the event that an RE could match more than one substring of a given -string, -the RE matches the one starting earliest in the string. -If the RE could match more than one substring starting at that point, -it matches the longest. -Subexpressions also match the longest possible substrings, subject to -the constraint that the whole match be as long as possible, -with subexpressions starting earlier in the RE taking priority over -ones starting later. -Note that higher-level subexpressions thus take priority over -their lower-level component subexpressions. -.PP -Match lengths are measured in characters, not collating elements. -A null string is considered longer than no match at all. -For example, -`bb*' matches the three middle characters of `abbbc', -`(wee|week)(knights|nights)' matches all ten characters of `weeknights', -when `(.*).*' is matched against `abc' the parenthesized subexpression -matches all three characters, and -when `(a*)*' is matched against `bc' both the whole RE and the parenthesized -subexpression match the null string. -.PP -If case-independent matching is specified, -the effect is much as if all case distinctions had vanished from the -alphabet. -When an alphabetic that exists in multiple cases appears as an -ordinary character outside a bracket expression, it is effectively -transformed into a bracket expression containing both cases, -e.g. `x' becomes `[xX]'. -When it appears inside a bracket expression, all case counterparts -of it are added to the bracket expression, so that (e.g.) `[x]' -becomes `[xX]' and `[^x]' becomes `[^xX]'. -.PP -No particular limit is imposed on the length of REs\(dg. -Programs intended to be portable should not employ REs longer -than 256 bytes, -as an implementation can refuse to accept such REs and remain -POSIX-compliant. -.PP -Obsolete (``basic'') regular expressions differ in several respects. -`|', `+', and `?' are ordinary characters and there is no equivalent -for their functionality. -The delimiters for bounds are `\e{' and `\e}', -with `{' and `}' by themselves ordinary characters. -The parentheses for nested subexpressions are `\e(' and `\e)', -with `(' and `)' by themselves ordinary characters. -`^' is an ordinary character except at the beginning of the -RE or\(dg the beginning of a parenthesized subexpression, -`$' is an ordinary character except at the end of the -RE or\(dg the end of a parenthesized subexpression, -and `*' is an ordinary character if it appears at the beginning of the -RE or the beginning of a parenthesized subexpression -(after a possible leading `^'). -Finally, there is one new type of atom, a \fIback reference\fR: -`\e' followed by a non-zero decimal digit \fId\fR -matches the same sequence of characters -matched by the \fId\fRth parenthesized subexpression -(numbering subexpressions by the positions of their opening parentheses, -left to right), -so that (e.g.) `\e([bc]\e)\e1' matches `bb' or `cc' but not `bc'. -.SH SEE ALSO -regex(3) -.PP -POSIX 1003.2, section 2.8 (Regular Expression Notation). -.SH BUGS -Having two kinds of REs is a botch. -.PP -The current 1003.2 spec says that `)' is an ordinary character in -the absence of an unmatched `('; -this was an unintentional result of a wording error, -and change is likely. -Avoid relying on it. -.PP -Back references are a dreadful botch, -posing major problems for efficient implementations. -They are also somewhat vaguely defined -(does -`a\e(\e(b\e)*\e2\e)*d' match `abbbd'?). -Avoid using them. -.PP -1003.2's specification of case-independent matching is vague. -The ``one case implies all cases'' definition given above -is current consensus among implementors as to the right interpretation. -.PP -The syntax for word boundaries is incredibly ugly.