.; Bonner Lab Runoff required .define escape "^[" HSP,0 0 .br 2 Constant__representations .br 3 Integers .rm74 Integers starting with '0' are taken to be octal, integers starting with "0x" are hexadecimal, and all others are decimal, e.g_. 0177 = 0x7F = 127. An 'L' suffix may be used to force a constant to be long. .br 3 Floating__point .br Floating-point numbers may contain an optional decimal point and/or 'E' or 'e' exponent operator, e.g_. 12.34, 1E6, 1.5e-23. .br 3 Characters .br Character constants are enclosed in single primes, e.g_. 'a' gives a lower-case letter A. Non-printing characters are represented using a backslash (_\) as an "escape" character introducing one of the combinations:- .s.nf.lm+10.ts34 _\n###newline#(CR+LF) _\t###horizontal#tab _\b###backspace _\f###form#feed _\r###carriage#return _\_\###backslash _\'###single#quote _\"###double#quote _\0###null _\ddd#character#with#octal#code#ddd .f.lm-10 3 Strings .br String constants are enclosed in double-quotes ("), using the backslash convention, as for character types, for non-printing characters. Strings end with nulls (_\0), which must be allowed for when they are copied to character arrays. If a string in the program text is to continue over several lines, a backslash must appear at the end of each line, e.g.: .s.nf.lm+5 putfmt("This string covers _\ two lines of program source."); .lm-5.rm76 2 Operators .f In the descriptions, i and j are of integer type (usually char, long, or int), x and y any type or expression, p is a pointer. .nf.ts10 3 Unary *p value of object pointed to by p _&x pointer to (address of) x -x twos complement (negative) of x ~i ones complement of i ++i increment i by 1 before use i++ increment i by 1 after use --i decrement i by 1 before use i-- decrement i by 1 after use ^[!x (NOT) 1 if x=0, otherwise 0 (type)x x coerced to a particular type sizeof#x number of bytes required to store x 3 Arithmetic x*y x multiplied by y x/y x divided by y i_%j remainder on dividing i by j x+y x plus y x-y x minus y i<>j i shifted right j bits 3 Relational x=y 1 if x is greater than or equal to y, else 0 x>y 1 if x is greater than y, else 0 x!=y 1 if x is not equal to y, else 0 3 Logical i_&j i bit-wise ANDed with j i_^j i bit-wise exclusive ORed with j i|j i bit-wise inclusive ORed with j 3 Conditional x_&_&y AND (1=true if a and y are both non-zero) x||y OR##(1=true if either x or y is non-zero) 2 Declaration__statements .f Identifier names may consist of letters (cases are distinct), digits, and underscores (__), starting with a letter or underscore. Dollar signs (_$) are also accepted, as an extension to the C language standard, but are handled as follows: .lm+20.p-15 for#8080#######converted to underscore (__). .i for#68000######converted to hash (_#). .i for#VAX########passed unchanged, for system subroutine calls, but note that names consisting of _$ followed only by digits may clash with compiler-generated labels. .i for#PDP-11#####converted to hash (_#), giving assembly phase failures, and therefore unusable. .lm-20.p0 Whitesmiths' C defines, in standard header file SYS_$LIBRARY:STD.H, a number of alternative names for declaration types and classes:- .s.nf.lm+5.ts+8,+19,+8,+11,+8 ARGINT int FILE short TBOOL [unsigned#]char BITS unsigned#short GLOBAL extern TEXT [unsigned#]char BOOL int IMPORT extern TINY char BYTES unsigned#int INTERN static UCOUNT unsigned#short COUNT short LOCAL static ULONG unsigned#long DOUBLE double LONG long UTINY unsigned#char FAST register METACH short VOID int .lm-5.rm74 3 arrays .i5;char name[size] = { value__0, ... value__size-1 }; .i5;char name[] = "This is a string initialiser"; .f.s set up a single-dimension array. The square brackets are a required part of the syntax. The value list is optional; when it is given, the size is optional. If both are given, and the value list is too short, remaining elements are set to zero. Arrays start at 0, so the size is one greater than the high bound (highest-numbered element). The second form of initialisation is available only for char arrays, loading a string into the bytes. Arrays may be declared static. .p5 char name[row__size][col__size] = { .i9;{ value__[0][0], ... value__[0][row__size-1] }, .i17;_... .i9;{ value__[col__size-1][0], ... value__[col__size-1][row__size-1] } }; .s sets up a 2-dimensional char array. Arrays of other types and more dimensions may be declared similarly. .br 3 char .i5;char name[=value][,...]; .s reserves space for 8-bit integers in range -128 to +127. .s.i5;unsigned char name[=value][,...]; .s reserves space for 8-bit integers in range 0 to 255. .p0 If the value list is given, the variables are preset to those values the each time the function is entered. .p0 "TINY" is an alternative to "char" in Whitesmiths' C. "TEXT" is equivalent to "unsigned#char" if UTEXT is defined to the C preprocessor, or "char" if it is not defined. .br 3 DESCRIPTOR .br.lm+5.nf typedef struct { .lm+8 unsigned short length; unsigned short type; char *pointer; } DESCRIPTOR; .lm-13.s.f reserves space for a VAX/VMS-style string descriptor used by some system interface and library functions. This data type is defined in SYS_$LIBRARY:VMS.H for VAX systems only. The length entry gives the number of bytes in the string, and the pointer entry gives the address of the first byte. The type entry specifies the string class, and should be 0x10e (fixed-length static string) for normal usage. Other string types are discussed in the VAX MACRO-32 assembler documentation. .br 3 double .i5;double name[=value][,...]; .s reserves space for 64-bit floating-point numbers in the range 2.9E-39 to ^[1.7E+38, with 15-16 digits of precision. .p0 If the value list is given, the variables are preset to those values the each time the function is entered. .p0 "double" may be spelled in upper case in Whitesmiths' C. .br 3 extern .i5;extern type name[,...]; .s specifies that space is allocated variables in another module. .p0 "GLOBAL" is an alternative to "extern" in Whitesmiths' C. .br 3 FILE .br a short int, the first element of a FIO struct (q.v.) used to identify a file in some file I/O routines. Three standard FILEs are defined:- .lm+13.ts13.p-8 STDIN the standard input. This is the user's terminal, unless overridden by a file prefixed by '<' on the command line running the program. .p STDOUT the standard output stream. The user's terminal, or a file prefixed by '>' on the command line. .p STDERR the standard error message file, always the user's terminal. .lm-13 3 FIO .lm+5.nf typedef struct fio { FILE __fd; .lm+21 short __nleft; short __fmode; char *__pnext; char __buf[512]; .lm-21 } FIO; .lm-5.f.p0 A Whitesmiths'-specific data structure used for file control, and used to identify a file in some routines. Three standard FIOs are defined:- .lm+13.p-8 stdin the standard input. This is the user's terminal, unless overridden by a file prefixed by '<' on the command line running the program. .p stdout the standard output stream. The user's terminal, or a file prefixed by '>' on the command line. .p stderr the standard error message file, always the user's terminal. .lm-13 3 float .i5;float name[=value][,...]; .s reserves space for 32-bit floating-point numbers in range 2.9E-39 to ^[1.7E+38, with 6-7 decimal digits of precision. .p0 If the value list is given, the variables are preset to those values the each time the function is entered. .br 3 function .i5;type name([argument[,...]]) .i5;argument__spec[;...]; .s declares a function which may be called by name with zero or more arguments supplied. Arguments are variable names in the standard format. Argument specifications take a similar form to declarations. .br 3 int .i5;[int ]name[=value][,...]; .i5;unsigned [int ]name[=value][,...]; .s reserve space for integers of sufficient size to contain a machine address. short (16 bits) on 8080 and PDP-11, long (32 bits) on VAX and MC68000. .p0 If the value list is given, the variables are preset to those values the each time the function is entered. .p0 "ARGINT", "BOOL", and "VOID" are alternatives to "int" in Whitesmiths' C, and "BYTES" is equivalent to "unsigned int". .br 3 long .i5;long [int ]name[=value][,...]; .s reserves space for 32-bit integers in range -2147483685 to +2147483684. .p5;unsigned long [int ]name[=value][,...]; .s reserves space for 32-bit integers in range 0 to 4294967294. .p0 If the value list is given, the variables are preset to those values the each time the function is entered. .p0 "long" may be spelled in upper case in Whitesmiths' C. .br 3 short .i5;short [int ]name[=value][,...]; .s reserves space for 16-bit integers in range -32768 to +32767. .p5 unsigned short [int ]name[=value][,...]; .s reserves space for 16-bit integers in range 0 to 65535. .p0 If the value list is given, the variables are preset to those values the each time the function is entered. .p0 "COUNT", "FILE", and "METACH" are alternatives to "short" in Whitesmiths' C, and "BITS" and "UCOUNT" are equivalent to "unsigned short". .br 3 static .i5;static type name[=value][,...]; .s values are set once only, at the start of the program, and retained for each re-entry to a function. If used within a function, the variables are accessible to that function only. If used outside a function, the variables are accessible throughout the program when declared extern in functions using them. .p0 "INTERN" and "LOCAL" are alternatives to "static" in Whitesmiths' C. .br 3 register .i5;register type name[=value][,...]; .s specifies that the variables to be stored in cpu registers (if possible), for speed and coding efficiency. .p0 "FAST" is an alternative to "register" in Whitesmiths' C. .br 3 struct .i5;struct struct__identifier { declaration[,...] }; .s defines a data structure comprising one or more variables defined in the embraced declarations. struct declaration elements take the same form as normal declarations, plus bit-field declarations, in which ":n" follows the name of the element (which must be an unsigned integer), assigning n bits only. .p5 struct struct__identifier name [= { value[,...] } ]; .s declares a variable of the previously-defined structure type, optionally presetting its values. .br 3 typedef .i5;typedef type type__name[,...]; .s defines type__name as a synonym for a variable type, for use in other subsequent definitions. type can be a complex item, such as a structure. .br 3 union .i5;union { declaration[,...] } name; .p0 All variable(s) in the declarations share the same storage. .nf 2 Statements 3 assignment .lm+5.ts13 v=x variable = expression v*=x variable = variable * expression v/=x variable = variable / expression v_%=x variable = variable _% expression v+=x variable = variable + expression v-=x variable = variable - expression v<<=x variable = variable << expression v>>=x variable = variable >> expression v_&=x variable = variable _& expression v_^=x variable = variable _^ expression v|=x variable = variable | expression v+=x variable = variable + expression .s variable = condition ?#true__expression :#false__expression; .lm-5.f.p0 sets variable to the value of true__expression if condition is true, false__expression if not. .br 3 braces .i5;{#statement__1;#...#statement__n;#} .p0 Braces group one or more statements as a compound statement to be executed as if they were a single statement, e.g_. in a loop or as the result of a satisfied condition. .br 3 break .i5;break; .s immediately exits a switch, or a while, do, or for loop. .br 3 comment .i5;/*#...#*/ .p0 Text between /* and */ is ignored. .br 3 continue .i5;continue; .s exits the statement part of a while, do, or for loop, to the next test of the termination condition. .nf 3 do .i5;do statement while (condition); .s ^[1.#Execute statement. ^[2.#Test the condition expression. ^[3.#Exit if false. ^[4.#Repeat from step 1. 3 for .i5;for (expression__1;#condition;#expression__3) statement; .s ^[1.#Evaluate expression__1. ^[2.#Exit if condition evaluates to false (0). ^[3.#Execute statement. ^[4.#Evaluate expression__3. ^[5.#Repeat from step 2. .s Whitesmiths' C defines "FOREVER" as "for#(;;)", which loops indefinately. 3 goto .lm+5;goto label; ###... label: .lm-5.s transfers execution to label. 3 if .lm+5 if (condition__1) statement__1; ####[else if (condition__2) statement__2;#...#] ####[else statement__n] ; .lm-5.f.s executes the statement associated with the first condition which tests true. If none do, and statement__n is given, then this is executed, otherwise no action is taken. .br 3 return .i5;return[(expression)]; .s returns from a function with the value of expression, if present, undefined if not. .nf 3 switch .lm+5 switch (expression) { case value__1: [statement__1;] [break]; ###... case value__n: [statement__n;] [break]; [default:#[default__statement]];#} .lm-5.s.f transfers execution to a label selected by the value of the expression, or to the default statement if none match. .nf 3 while .i5;while (condition) statement; .s ^[1.#Test the condition expression. ^[2.#Exit if false. ^[3.#Execute statement. ^[4.#Repeat from step 1. .f.rm76 2 Preprocessor__commands .br Preprocessor commands commence with _#. They are evaluated as the first step of compilation, and not at run time. .rm74 3 define .i5;_#define identifier[(argument[,...])] [definition] .s defines, or redefines, a macro, with optional arguments. .nf 3 if .lm+5 _#if expression ##... [_#else ##... ] _#endif .lm-5.f.s skips (does not compile) statements up to the next _#else or _#endif if the expression evaluates to 0. _#else, if present, reverses the result of the test, up to the _#endif. .nf 3 ifdef .lm+5 _#ifdef identifier ##... [_#else ##... ] _#endif .lm-5.f.s compiles statements up to the next _#else or _#endif if the identifier is defined. _#else, if present, reverses the result of the test, and turns off compilation until the _#endif. .nf 3 ifndef .lm+5 _#ifndef identifier ##... [_#else ##... ] _#endif .lm-5.f.s compiles statements up to the next _#else or _#endif if the identifier is NOT defined. _#else, if present, reverses the result of the test, and turns on compilation until the _#endif. .br 3 include .i5;_#include "filename" .i5;_#include .s inserts the contents of filename at the point where this statement appears. The filetype must be given. In the first form, the file is in the user's (or explicitly specified) directory; in the second form, the file is in the as specified in the -i flag argument on the preprocessor command line (usually the system library directory, SYS_$LIBRARY). .br 3 line .i5;_#line number [filename] .s sets a line number and filename for use in subsequent compiler diagnostic messages. .br 3 undef .i5;_#undef identifier .s deletes the specified macro definition. If it was a redefinition, the next previously-defined definition becomes the current one. .br 2 Runtime__libraries .br Most routines are in the standard library, PLIB.OLB, or defined as macros in the standard header STD.H. Those which require the Unix library, ULIB.OLB, or header, STDIO.H, are indicated. All library and header files are in SYS_$LIBRARY. .br.ts1.tab right 3 abs .i5;abs(x) .s returns the absolute value of x. abs is implemented as a macro, by: .p5 _#define#abs(x)#((x)#<#0#?#-(x)#:#(x)) .s and its argument may therefore be of any type. .br 3 alloc .i5;char#*alloc(n,l) unsigned int n,l; .s allocates n bytes on the heap, writing link l into the zeroth integer location. .nf 3 amatch .lm+5 int#amatch(buf,n,idx,pat,psubs) char *buf;#unsigned int n,idx;#char *pat; struct { char *mtext;#unsigned int mlen;} *psubs; .lm-5.f.s searches in the n character buffer starting at buf[idx] for the encoded pattern pat. .br 3 arctan .i5;double#arctan(x) double x; .s returns, in radians and range (-pi/2,pi/2), the angle whose tangent is x. .br 3 atan .i5;double#atan(x)#double#x; /*#in#STDIO.H#*/ .s returns, in radians and range (-pi/2,pi/2), the angle whose tangent is x. .br 3 atof .i5;double#atof(s)#char#*s; /*#in#ULIB.OLB#*/ .s reads the ASCII floating-point number in string s to a double. .br 3 atoi .i5;int#atoi(s)#char#*s; /*#in#ULIB.OLB#*/ .s reads the ASCII number in string s to an int. .br 3 atol .i5;double#atol(s)#char#*s; /*#in#ULIB.OLB#*/ .s reads the ASCII number in string s to a long int. .br 3 bldks .i5;char#*bldks(ks,key) char ks[16][8],key[8]; .s builds a key schedule for encrypting/decrypting. .br 3 btod .i5;int#btod(s,n,p) char *s;#unsigned int n;#double *p; .s converts n-character string s to double, stored at p. .br 3 btoi .i5;int#btoi(s,n,p,b) char *s;#unsigned int n,*p;#short b; .s converts n-character string s, in base b, to an int stored at p. .br 3 btol .i5;int#btol(s,n,p,b) char *s;#unsigned int n;#long *p;#short b; .s converts n-character string s, in base b, to a long int stored at p. .br 3 btos .i5;int#btos(s,n,p,b) char *s;#unsigned int n;#short *p,b; .s converts n-character string s, in base b, to a short int stored at p. .br 3 buybuf .i5;char#*buybuf(s,n) char *s;#unsigned int n; .s allocates n bytes on the heap, and copies n bytes from s into it. .br 3 calloc .i5;char#*calloc(n,s)#unsigned#int#n,s; /*#in#ULIB.OLB#*/ .s allocates space on the heap for n objects of size s, setting the area to zero. .br 3 close .i5;FILE close(fd) FILE fd; .s closes the file associated with file descriptor fd. .br 3 cmpbuf .i5;int#cmpbuf(s,t,n) char *s,*t;#unsigned int n; .s compares n-bytes buffers s and t, returning 1 if identical, else 0. .br 3 cmpstr .i5;int#cmpstr(s,t) char *s,*t; .s compares null-terminated strings s and t, returning 1 if they are identical, or 0 if they differ. .br 3 cos .i5;double#cos(x) double x; .s returns the cosine of angle x, in radians. .br 3 cpybuf .i5;int#cpybuf(s,t,n) char *s,*t;#unsigned int n; .s copies n-byte buffer t to buffer s. .br 3 cpystr .i5;char#*cpystr(d,s,t,...,NULL) char *d,*s,*t,...; .s concatenates strings s, t, etc_. into d. .br 3 creat .i5;FILE#create(f,m)#char#*f;#short m; /*#in#STDIO.H#*/ .s creates a new (version of a) file with name f, opened for write. Argument m is not used. Global __recsize must be set non-zero for a binary file, zero for ASCII text. .br 3 create .i5;FILE create(f,m,r) char *f;#short m;#unsigned int r; .s creates a new (version of a) file with name f. m is the file mode: READ, WRITE, or UPDATE. r is the record size, and should be non-zero for a binary file, zero for ASCII text. .br 3 decode .i5;int#decode(s,n,f,a,b,c...) char *s,*f;#unsigned int n;#... .s writes characters to the n-character buffer s, decoding a,b,c etc_. according to format control string f. Returns the number of characters actually written (0-n). .br 3 decrypt .i5;char#*decrypt(d[8],ks) char d[8],ks[16][8]; .s decrypts 8 characters according to control block ks. .br 3 doesc .i5;int#doesc(p,m) char **p,*m; .s decodes the escape sequence beginning at p. .br 3 dtento .i5;double#dtento(d,n) double d;#short n; .s returns d multiplied by 10 to the power n. .br 3 dtoe .i5;int#dtoe(s,d,m,n) char *s;#double d;#unsigned int m,n; .s converts double d to exponent-form ASCII string s, with m digits before, and n digits after the decimal point. .br 3 dtof .i5;int#dtof(s,d,m,n) char *s;#double d;#unsigned int m,n; .s converts double d to fixed-point format ASCII string. .br 3 encode .i5;int#encode(s,n,f,a,b,c...) char *s,*f;#unsigned int n;#... .s reads n-character string s into variables a,b,c, etc_. decoding according to format control string f. .br 3 encrypt .i5;char#*encrypt(d[8],ks) char d[8],ks[16][8]; .s encrypts 8 characters according to control block ks. .br 3 enter .i5;int#enter(pf,a) unsigned int (*pf)(),a; .s establishes a "control region" that can be terminated early by a call to leave(). .br 3 errfmt .i5;errfmt(f,a,b,c,...)char *f,*a,*b,*c,...; .s performs formatted output to stderr. .br 3 error .i5;error(s,t) char *s,*t; .s exits, printing an error message including strings s and t. .br 3 exit .i5;int exit(s) int s; .s exits the program, returning status s to the operating system. .br 3 exp .i5;double#exp(x) double x; .s returns e to the power x. .br 3 fclose .i5;FIO#*fclose(pfio) FIO *pfio; .s closes the file under the control of FIO pfio. .br 3 fcreate .i5;FIO#*fcreate(pfio,f,m) FIO *pfio;#char *f;#short m; .s creates a new file with name f in mode m (BWRITE, READ, or WRITE), attaching it to FIO buffer pfio. .br 3 feof .i5;int#feof(pfio)#FIO#*pfio; /*#in#ULIB.OLB#*/ .s returns a non-zero value if the end of the file controlled by FIO pfio has been read, otherwise zero. .br 3 fflush .i5;int#fflush(pfio)#FIO#*pfio; /*#in#ULIB.OLB#*/ .s causes any buffered data for the file controlled by FIO pfio to be written onto disk. The file remains open. .br 3 fgetc .i5;int#fgetc(pfio)#FIO#*pfio; /*#in#ULIB.OLB#*/ .s gets the next char from the file controlled by pfio. .br 3 fgets .i5;char#*fgets(s,n,pfio) .i5;char#*s;#unsigned#int#n;#FIO#*pfio; /*#in#ULIB.OLB#*/ .s gets up to n-1 characters from the file controlled by pfio to string s, returning the address of s. Input terminates when n-1 characters have been read, or a newline character is encountered. .br 3 fileno .i5;FILE#fileno(pfio)#FIO#*pfio; /*#in#STDIO.H#*/ .s returns the FILE entry of the file control block *pfio. .br 3 fill .i5;int#fill(s,n,c) char *s,c;#unsigned int n; .s fills n-character buffer at s with char c. .br 3 finit .i5;FIO#*finit(pfio,fd,m) FIO *pfio;#FILE fd;#short m; .s #initialises FIO control buffer pfio for use with FILE fd, in mode m. .br 3 fopen .i5;FIO#*fopen(pfio,f,m) FIO *pfio;#char *f;#short m; .s opens an existing file, name f, for access in mode m, controlled by the FIO at pfio. .br 3 fprintf .i5;int#fprintf(fd,f,a,b,c,...)#FILE#fd;#char#*f;#... /*#in#ULIB.OLB#*/ .s converts arguments a,b,c etc_. to a text string under control of format specifier f, and writes the result to FILE fd. .br 3 fputc .i5;int#fputc(c,pfio)#FIO#char#c;#*pfio; /*#in#ULIB.OLB#*/ .s stores char c in the buffer controlled by FIO pfio. .br 3 fputs .i5;int#fputs(s,pfio)#char#*s;#FIO#*pfio; /*#in#ULIB.OLB#*/ .s writes string s as a line to the file controlled by pfio. .br 3 fread .br Whitesmiths' version: .i5;int#fread(fd,b,n)#FILE#fd;#char#*b;#unsigned#int#n; .s reads up to n chars into buffer b from the FILE fd. .s Unix version: .i5;int#fread(b,s,n,pfio) .i5;char#*b;#unsigned#int#s,n;#FIO#*pfio; /*#in#ULIB.OLB#*/ .s reads n items of size s bytes into buffer b from the file controlled by FIO *pfio. .br 3 free .i5;char#*free(p,l) char *p,*l; .s returns an alloc'd cell to the heap. .br 3 frelst .i5;struct#list#*frelst(pl,ps) .i8;struct list {struct list *next;...} *pl,*ps; .s frees a linked list of alloc'd cells. .br 3 fscanf .i5;int#fscanf(pfio,f,a,b,c,...) FIO *pfio;#char *f;#... .s reads text from the file controlled by pfio, decoding it into values a,b,c, etc., under control of format string f. .br 3 fwrite .br Whitesmiths' version: .i5;fwrite(fd,b,n) FILE fd;#char *b;#unsigned int n; .s writes n chars from buffer b to FILE fd. .s Unix version: .i5;int#fwrite(b,s,n,pfio) .i5;char#*b;#unsigned#int#s,n;#FIO#*pfio; /*#in#ULIB.OLB#*/ .s writes n items of size s bytes from buffer b to the file controlled by FIO *pfio. .br 3 getbfiles .i5;FILE#getbfiles(ac,av,dfd,efd,n) .i8;unsigned int *ac,n;#char ***av;#FILE dfd,efd; .s gets an argument from the command line, opening a file for binary reads. .br 3 getc .i5;int#getc(pfio) FIO *pfio; .s gets the next char from the file controlled by pfio. .br 3 getch .i5;int#getch(); .s gets the next character from stdin. .br 3 getchar .i5;int#getchar(); /*#in#STDIO.H#*/ .s gets the next character from stdin. .br 3 getf .i5;int#getf(pfio,f,a,b,c,...) FIO *pfio;#char *f;#... .s reads text from the file controlled by pfio, decoding it into values a,b,c, etc., under control of format string f. .br 3 getfiles .i5;FILE#getfiles(ac,av,dfd,efd,n) .i5;unsigned int *ac;#char ***av;#FILE dfd,efd; .s gets an argument from the command line, opening a file for reading as an ASCII file. .br 3 getflags .i5;char#*getflags(ac,av,f,a,b,c,...) .i5;unsigned int *ac;#char ***av,*f;#... .s gets flags from the command line and decodes them according to format control string f, into variables a,b,c etc.. .br 3 getfmt .i5;int#getfmt(f,a,b,c,...) char *f;#... .s reads text from stdin, decoding it into values a,b,c, etc., under control of format string f. .br 3 getin .i5;int#getin(ac,av) unsigned int *ac;#char ***av; .s reads lines of text from stdin, setting ac to the number read, and storing the lines in av. .br 3 getl .i5;int#getl(pfio,s,n) FIO *pfio;#char *s;#unsigned int n; .s gets a line from the file controlled by pfio to n-character buffer s, returning the number of chars read. .br 3 getlin .i5;int#getlin(s,n) char *s;#unsigned int n; .s gets a line of text from stdin to n-character buffer s, returning the number of chars read. .br 3 gets .i5;char#*gets(s)#char#*s; /*#in#ULIB.OLB#*/ .s gets a line from stdin to string s, returning the address of s. .br 3 gtc .i5;int#gtc(pfio)#FIO#*pfio; .s gets a character from the file controlled by pfio. This is actually defined as a macro, which fetches a character directly from the control block, if possible, or calls getc if not (because a file read is required). .br 3 inbuf .i5;int#inbuf(p,n,s) char *p,*s;#unsigned int n; .s scans n-character buffer p for the first character in string s, returning the index into p, or n if no characters are found. .br 3 index .i5;char#*index(s)#char#*s,c; /*#in#ULIB.OLB#*/ .s searches string s for the first occurrence of character c, returning a pointer to c, or NULL if c is not present. .br 3 instr .i5;int#instr(p,s) char *p,*s; .s scans string p for the first character in string s. .br 3 isalnum .i5;int#isalpha(c)#char#*c; /*#in#CTYPE.H#*/ .s tests if c is a letter_: 'a'-'z', or 'A'-'Z', or digit_: '0'-'9'. .br 3 isalpha .i5;int#isalpha(c) char *c; .s tests if c is a letter in either case_: 'a'-'z', or 'A'-'Z'. .p0 In Whitesmiths' C, this is implemented by the macro: .p5;_#define isalpha(c) (('a'<=(c)_&_&(c)<='z') || ('A'<=(c)_&_&(c)<='Z')) .s which means that c may be evaluated up to four times. .s In Unix-compatible C (defined in CTYPE.H), a table lookup is used, and c is evaluated only once. .br 3 isascii .i5;int#isascii(c)#char#c; /*#in#CTYPE.H#*/ .s tests if c is a character from the standard ASCII character set, having codes 0 to 127 (i.e_. bit 7 clear). .br 3 iscntrl .i5;int#iscntrl(c)#char#c; /*#in#CTYPE.H#*/ .s tests if c is one of the ASCII control characters having codes 0 to 31. .br 3 isdigit .i5;int#isdigit(c) char c; .s tests if c is a decimal digit_: '0'-'9'. .p0 In Whitesmiths' C, this is implemented by the macro: .p5;_#define isdigit(c) ('0' <= (c) _&_& (c) <= '9') .s which means that c may be evaluated twice. .p0 In Unix-compatible C (defined in CTYPE.H), a table lookup is used, and c is evaluated only once. .br 3 isgraph .i5;int#isgraph(c)#char#c; /*#in#CTYPE.H#*/ .s tests if c is any printing character: letters, digits, or punctuation, other than space. .p0 This is implemented by the macro: .p5;_#define isgraph(c) (isprint(c) _&_& (c) != ' ') .s which means that c may be evaluated twice. .br 3 islower .i5;int#islower(c) char c; .s tests if c is a lower case letter_: 'a'-'z'. .p0 In Whitesmiths' C, this is implemented by the macro: .p5;_#define islower(c) ('a' <= (c) _&_& (c) <= 'z') .s which means that c may be evaluated twice. .s In Unix-compatible C (defined in CTYPE.H), a table lookup is used, and c is evaluated only once. .br 3 isprint .i5;int#isprint(c)#char#c; /*#in#CTYPE.H#*/ .s tests if c is a printing character, including upper- and lower-case letters, digits, punctuation, and space. .br 3 ispunct .i5;int#ispunct(c)#char#c; /*#in#CTYPE.H#*/ .s tests if c is a space or one of the punctuation characters: .c;!"_#_$_%_&'()*+,-./:;<=>?@[_\]_^__`{|}~. .br 3 isspace .i5;int#isspace(c)#char#c; /*#in#CTYPE.H#*/ .s tests if c is one the characters tab, linefeed, formfeed, carriage-return, or space. .br 3 isupper .i5;int#isupper(c) char c; .s tests if c is an upper case letter_: 'A'-'Z'. .p0 In Whitesmiths' C, this is implemented by the macro: .p5;_#define#isupper(c)#('A'#<=#(c)#_&_&#(c)#<=#'Z') .s which means that c may be evaluated twice. .s In Unix-compatible C (defined in CTYPE.H), a table lookup is used, and c is evaluated only once. .br 3 iswhite .i5;int#iswhite(c) char c; .s tests if c is "whitespace", any character <= octal 040. .p0 This is implemented by the macro: .p5;_#define#iswhite(c)#((c)#<=#'#'#||#0177#<=#(c)) .s which means that c may be evaluated twice. .br 3 isxdigit .i5;int#isxdigit(c)#char#c; /*#in#CTYPE.H#*/ .s tests if c is a hexadecimal digit_: '0'-'9', 'A'-'F', or 'a'-'f'. .br 3 itob .i5;int#itob(s,i,b) char *s;#int i;#short base; .s converts int i to an ASCII string s, in base b. .br 3 itols .i5;char#itols(s,i) char *s;#short i; .s writes i *into s[0]/s[1], low byte in s[0]. .br 3 leave .i5;leave(v) unsigned int v; .s leaves the control region last enter'ed, returning value v. .br 3 lenstr .i5;int#lenstr(s) char *s; .s returns the length of string s. .br 3 ln .i5;double#ln(x) double x; .s returns the natural logarithm of x. .br 3 log .i5;double#log(x)#double#x; /*#in#STDIO.H#*/ .s returns the natural logarithm of x. .br 3 log10 .i5;double#log10(x)#double#x; /*#in#ULIB.OLB#*/ .s returns the common (base 10) logarithm of x. .br 3 lower .i5;char#lower(s,n) char *s;#unsigned int n; .s converts n-character buffer s to all lower case. .br 3 lseek .i5;short lseek(fd,o,s) FILE fd;#long 0;#short s; .s modifies the read/write pointer for FILE fd by offset o. If s#=#0, o is absolute. If s#=#1, o is added to the current position. .br 3 lstoi .i5;int#lstoi(s) char *s; .s returns the int formed from s[0]/s[1], where s[0] is the low byte. .br 3 lstol .i5;long#lstol(s) char *s; .s converts 4-byte string in byte order 2,3,0,1 to a long. .br 3 lstou .i5;short#lstou(s) char *s; .s returns the unsigned short formed from s[0]/s[1], where s[0] is the low byte. .br 3 ltob .i5;int#ltob(s,i,b) char *s;#long l;#short b; .s converts long i to an ASCII string s, in base b. .br 3 ltols .i5;char#*ltols(p,l) char *p;#long l; .s writes long l into buffer p, in byte order 2,3,0,1. .br 3 main .i5;main(ac,av) unsigned int ac;#char **av; .s the main module of a C program. av contains ac strings which are the command line arguments from the program invocation, av[0] being the program name itself (fixed, as __pname on VMS, may be read from the RUN command on other systems). .br 3 malloc .i5;char#*malloc(n,l)#unsigned#int#n;#char#*l; /*#in#STDIO.H#*/ .s allocates n bytes on the heap, and writes int l in the zeroth integer location. Returns a pointer to the buffer. .br 3 mapchar .i5;mapchar(c,p) char c,*p; .s writes char c into 2-byte buffer p, in escape form if necessary. .br 3 match .i5;int#match(b,n,p) char c,*p; .s tests n-character buffer b for a match with the encoded pattern p. .br 3 max .i5;max(a,b) .s returns the larger of a and b. .p0 This is implemented by the macro: .p5;_#define#max(x,y)#(((x)#<#(y))#?#(y)#:#(x)) .s which means that x or y may be evaluated twice, and may be of any type. .br 3 min .i5;min(a,b) .s returns the smaller of a and b. .p0 This is implemented by the macro: .p5;_#define#min(x,y)#(((x)#<#(y))#?#(x)#:#(y)) .s which means that x or y may be evaluated twice, and may be of any type. .b 3 mkord .i5;int#(*mkord(k,r))() char **k,*r; .s produces a function suitable for use with sort to compare two buffers for lexical order defined by array k a,d string r. .br 3 nalloc .i5;char#*nalloc(n,l) unsigned int n;#char *l; .s allocates n bytes on the heap, and writes int l in the zeroth integer location. Returns a pointer to the buffer. .br 3 notbuf .i5;int#notbuf(p,n,s) char *p,*s;#unsigned int n; .s finds the first occurrence in n-character buffer p of a character not in string s. .br 3 notstr .i5;int#notstr(p,s) char *p,*s; .s finds the first occurrence in string p of a character not in string s. .br 3 onexit .i5;int (*onexit())(pfn) int (*(*pfn)())(); .s registers function pfn to be called when the program exits. .br 3 onintr .i5;int onintr(pfn) int (*pfn)(); .s defines an interrupt service routine to be called when a (certain) key is pressed on the terminal. Not available under VAX/VMS. .br 3 open .i5;FILE open(f,m,r) char *f;#short m;#unsigned int r; .s opens an existing file in mode m: READ, WRITE, or UPDATE. r is the record size, and should be non-zero for a binary file, 0 for ASCII text. .br 3 ordbuf .i5;int#ordbuf(s,t,n) char *s,*t;#short n; .s compares two n-character buffers for lexical order, returning -1, 0, or +1 according to st. .br 3 pathnm .i5;char#*pathnm(b,s,t) char *b,*s,*t; .s builds a pathname in buf derived from strings s and t. .br 3 pattern .i5;char#*pattern(b,d,p) char *b,d,*p; .s builds from string p an encoded pattern in buffer b suitable for use with match or amatch. .br 3 pow .i5;double#pow(x,y)#double#x,y; /*#in#ULIB.OLB#*/ .s returns x to the power y. .br 3 __pname .i5;char __pname; .s the program name string, "error" by default. On some systems (but not VMS) it may be set from the system command which ran the program. .br 3 prefix .i5;int#prefix(s,t) char *s,*t; .s tests if string s begins with string t. .br 3 printf .i5;int#printf(f,a,b,c,...)#char#*f;#... /*#in#ULIB.OLB#*/ .s converts arguments a,b,c etc_. to a text string under control of format specifier f, and writes the result to stdout. .br 3 ptc .i5;int#ptc(pfio,c)#FIO#*pfio;#char#c; .s stores char c in the buffer controlled by FIO pfio. This is actually defined as a macro, which stores a character directly into the control block, if possible, or calls putc if not (because a file write is required). .br 3 putc .i5;int#putc(pfio,c)#FIO#*pfio;#char#c; /*#Whitesmiths'#*/ .i5;int#putc(c,pfio)#char#c;#FIO#*pfio; /*#Unix#--#in#ULIB.OLB#*/ .s store char c in the buffer controlled by FIO pfio. .br 3 putch .i5;int#putch(c) char c; .s writes char c to stdout. .br 3 putchar .i5;int#putchar(c)#char#c; /*#in#STDIO.H#*/ .s writes char c to stdout. .br 3 putf .i5;putf(pfio,f,a,b,c,...) FIO *pfio;#char *f;#... .s converts arguments a,b,c etc_. to a text string under control of format specifier f, and writes the result to the file controlled by FIO pfio. .br 3 putfmt .i5;putfmt(f,a,b,c,...) char *f;#... .s converts arguments a,b,c etc_. to a text string under control of format specifier f, and writes the result to stdout. .br 3 putl .i5;int#putl(pfio,s,n) FIO *pfio;#char *s;#unsigned int n; .s writes a line of n characters in buffer s to the file controlled by pfio. .br 3 putlin .i5;int#putlin(s,n) char *s;#unsigned int n; .s writes a line of characters to stdout. .br 3 puts .i5;int#puts(s)#char#*s; /*#in#ULIB.OLB#*/ .s writes string s as line to stdout. .br 3 putstr .i5;putstr(fd,s,t,u,...NULL) FILE fd;#char *s,*t,*u,...; .s writes a series of strings to the FILE with descriptor fd. .br 3 qsort .i5;int#qsort(b,n,w,comp)#char#*b;#int n,w,(*comp)(); /*#in#ULIB.OLB#*/ .s sorts in place a buffer, b, of n elements, each of width w, using routine comp to perform the comparisons. .br 3 rand .i5;long#rand(); /*#in#ULIB.OLB#*/ .br returns a positive pseudo-random long integer. .br 3 read .i5;short read(fd,b,n) FILE fd;#char *buf;#unsigned int n; .s reads up to n bytes from FILE fd into buffer b. For a binary file, 512 bytes are read unchanged; for an ASCII file, a record is read, and carriage-returns, nulls, and form-feeds deleted. -1 is returned if the end of file is passed, otherwise the return value is the number of bytes read. .br 3 remark .i5;remark(s,t) char *s,*t; .s writes a non-fatal message, containing strings s and t, to stderr. .br 3 remove .i5;short remove(f) char *f; .s deletes file named f. .br 3 rindex .i5;char#*rindex(s,c)#char#*s,c; /*#in#ULIB.OLB#*/ .s searches string s for the last occurrence of character c, returning a pointer to c, or NULL if c is not present. .br 3 round .i5;int#round(x) double x; .s rounds double x to the next integer nearest to zero. .br 3 sbreak .i5;char *sbreak(n) int n; .s requests n bytes of additional memory, returning a pointer to the start of the allocated area. .br 3 sbrk .i5;int#*sbrk(n)#int#n; /*#in#STDIO.H#*/ .s requests n bytes of additional memory, returning 0 if allocated successfully, -1 if not. .br 3 scanf .i5;int#fscanf(pfio,f,a,b,c,...) .i5;FIO#*pfio;#char#*f;#... /*#in#ULIB.OLB#*/ .s reads text from stdin, decoding it into values a,b,c, etc., under control of format string f. .br 3 scnbuf .i5;int#scnbuf(s,n,c) char *s,c;#unsigned int n; .s searches n-character buffer s for char c, returning the index of c, or n if c is not present. .br 3 scnstr .i5;int#scnstr(s,c) char *s,c; .s searches string s for character c, returning the index of c, or the length of s if c is not present. .br 3 sin .i5;double#sin(x) double x; .s returns the trigonometric sine of x. .br 3 sort .i5;sort(n,o,e,b) int n;#short (*o)();#int (*e)();#char *b; .s orders n items in memory using function o to determine their order, and function e for exchanges, both called with b as argument. .br 3 sprintf .i5;int#sprintf(s,f,a,b,c,...)#char#*s,*f;#... /*#in#ULIB.OLB#/ .s converts arguments a,b,c etc_. to text string s under control of format specifier f. .br 3 sqr .i5;double#sqr(x) double x; .s returns the square of x. .br 3 sqrt .i5;double#sqrt(x) double x; .s returns the square root of x. .br 3 sscanf .i5;int#sscanf(s,f,a,b,c,...)#char#*s,*f;#... /*#ULIB.OLB#*/ .s decodes text from string s into values a,b,c, etc., under control of format string f. .br 3 squeeze .i5;int#squeeze(s,n,c) char c,*s;#unsigned int n; .s removes all occurrences of char c from n-character buffer s, and compresses it, returning the new size. .br 3 srand .i5;int#srand(l)#unsigned#long#l; /*#in#ULIB.OLB#*/ .s seeds, or reseeds, the rand() random number generator with seed l. .br 3 stob .i5;int#stob(s,i,b) char *s;#short i,b; .s writes short i as an ASCII string in base b to buffer s. .br 3 strcat .i5;char#*strcat(s,t)#char#*s,*t; /*#in#STDIO.H#*/ .s appends string t to string s, returning a pointer to s. .br 3 strchr .i5;char#*strchr(s)#char#*s,c; /*#in#ULIB.OLB#*/ .s searches string s for the first occurrence of character c, returning a pointer to c, or NULL if c is not present. .br 3 strcmp .i5;int#strcmp(s,t)#char#*s,*t; /*#in#ULIB.OLB#*/ .s compares two strings for lexical order, returning a positive, zero, or negative integer, according to st. .br 3 strcpy .i5;char#*strcpy(s,t)#char#*s,*t; /*#in#STDIO.H#*/ .s copies string t to string s, returning a pointer to s. .br 3 strlen .i5;int#strlen(s)#char#*s; /*#in#STDIO.H#*/ .s returns the length of string s. .br 3 strncat .i5;char#*strncat(s,t,n)#char#*s,*t;#int#n; /*#in#ULIB.OLB#*/ .s appends string t to string s, copying at most n characters, and returning a pointer to s. .br 3 strncmp .i5;int#strncmp(s,t,n)#char#*s,*t;#int#n; /*#in#ULIB.OLB#*/ .s compares two strings of at most n characters for lexical order, returning a positive, zero, or negative integer, according to st. .br 3 strncpy .i5;char#*strncpy(s,t,n)#char#*s,*t;#int#n; /*#in#ULIB.OLB#*/ .s copies string t to string s, truncating or null-padding s as necessary, and returning a pointer to s. .br 3 strrchr .i5;char#*strrchr(s,c)#char#*s,c; /*#in#ULIB.OLB#*/ .s searches string s for the last occurrence of character c, returning a pointer to c, or NULL if c is not present. .br 3 subbuf .i5;int#subbuf(s,m,p,n) char *s,*p;#unsigned int m,n; .s finds the first occurrence of n-character buffer p in m-character buffer s, returning the position, or m if not present. .br 3 substr .i5;int#substr(s,p) char *s,*p; .s finds the first occurrence if string p in string s. .br 3 toascii .i5;char#toascii(c)#char#c; /*#in#CTYPE.H#*/ .s converts c to one of the basic ASCII characters, having codes 0 to 127, by stripping bit 7. .br 3 tolower .i5;char#tolower(c) char c; .s converts char c to lower case, if necessary. .p0 This#is#implemented#by#the##macro: .p5;_#define#tolower(c)#(isupper(c)#?#((c)#+#('a'#-#'A'))#:#(c)) .s which means that c may be evaluated four times. .br 3 __tolower .i5;char#__tolower(c)#char#c; /*#in#STDIO.H#*/ .s converts char c from upper- to lower-case, without any check that c was actually an upper-case letter. .br 3 toupper .i5;char#toupper(c) char c; .s converts char c to upper case, if necessary. .p0 This#is#implemented#by#the##macro: .p5;_#define#toupper(c)#(islower(c)#?#((c)#-#('a'#-#'A'))#:#(c)) .s which means that c may be evaluated four times. .br 3 __toupper .i5;char#__toupper(c)#char#c; /*#in#STDIO.H#*/ .s converts char c from lower- to upper-case, without any check that c was actually a lower-case letter. .br 3 trunc .i5;int#trunc(x) double x; .s truncates double d to an integer, towards zero. .br 3 uname .i5;char *uname() .s returns a unique filename, in a form unlikely to conflict with normal user names. .br 3 ungetc .i5;int#ungetc(c,pfio)#char#c;#FIO#*pfio; /*#in#ULIB.OLB#*/ .s pushes the character c back into the input stream of the file controlled by FIO pfio. .br 3 unlink .i5;short#unlink(f)#char#*f; /*#in#STDIO.H#*/ .s deletes file named f. .br 3 usage .i5;int#usage(s) char *s; .s writes the message "usage: s" to stderr. .br 3 write .i5;short write(fd,b,n) FILE fd;#char *b;#short n; .s writes n characters starting at b to FILE fd. .br 2 Format__specifiers .br 3 Whitesmiths' .br Format control strings used with getf, putf, etc., consist of strings and specifiers, the latter beginning with _%, and in the form: .s.c;_%[[+][-]fill][width][modifier]field__code .p0 _% followed by anything other than in the above form skips or outputs the next character literally, so _%_% reads or writes a percent sign, _%_\n a new line, etc.. .rm72 4 fill .i5;+fill .i5;-fill .p0 specifies fill characters to be stripped off on read. +fill strips leading characters, -fill strips trailing ones. .br 4 width .br specifies the total number of characters to be read or written. For floating-point data, the format may be "t.d", where t is the total width, and d the number of digits after the decimal point. For a string, ".w" limits the number of characters output to w. Giving an actual letter 'n' takes the width from the next argument in sequence. .br 4 modifier .br a single character that, along with field__code, determines how the corresponding item in the function call argument list is to be interpreted: .s.lm+8.i-4.ts8.tab left a as ASCII bytes .i-4;h in hexadecimal, with or without a leading "0x" on input, without on output .i-4;o in octal, with or without a leading '0' on input, without on output .i-4;u in unsigned decimal .lm-8 4 field__code .br defines the type of argument to be read or written:- .s.lm+4.nf c char s short i int l long p null-terminated string b buffer of specified length (no null terminator) f float on input, fixed-point form on output d double on input, exponent form on output x skip padding characters on input, write fillers on output .lm-4.rm74 3 Unix .f Format control strings used with printf, scanf, etc., consist of strings and specifiers, the latter beginning with _%, and in the form: .s.c;_%[-][width][.precision][l]field__code .p0 _% followed by anything other than in the above form skips or outputs the next character literally, so _%_% reads or writes a percent sign, _%_\n a new line, etc.. .rm72 4 - .br used to specify that an output string is to be left-justified in the field of given width. If the - is omitted, it is right-justified. Spaces are used for padding unless width begins with a '0', when zeroes are used. .br 4 width .br specifies the total number of characters to be written. Spaces are used for padding unless width begins with a '0', when zeroes are used. Giving an asterisk (*) takes the width from the next argument in sequence. .br 4 precision .i5;_.precision .p0 For floating-point data, specifies the number of digits after the decimal point. For a string, limits the number of characters output. Giving an asterisk (*) takes the width from the next argument in sequence. .br 4 l .br if present, specifies that a following d, o, x, or u corresponds to a long int instead of an int (D, O, X, or U accomplishes the same thing). .br 4 field__code .br defines the type of argument to be read or written:- .s.lm+4.nf c char d decimal short int D decimal long int e float in any format on input, exponent form on output E double in any format (input only) f float in any format on input, fixed-point form on output F double in any format (input only) g float to better precision of fixed or exponent forms G double to fixed or exponent form o octal short int O octal long int s null-terminated string u unsigned short int x hexadecimal short int X hexadecimal long int .i-4 [...] on input, skips any characters listed in the brackets .i-4 [_^...] on input, skips any characters not listed in the brackets .f.lm-4