Trailing-Edge
-
PDP-10 Archives
-
SRI_NIC_PERM_FS_1_19910112
-
c/old/nmit/cl-user.doc
There are no other files named cl-user.doc in the archive.
TOPS-20 Version 7 C System
Standard Library User Guide
May 14, 1985
Page 2
abs
abs, fabs: absolute value
SYNOPSIS
int abs(i)
int i;
float fabs(f)
float f;
DESCRIPTION
ABS and FABS return the absolute value of their
respective arguments.
Page 3
atoi, atol
atoi, atol: convert strings to numbers
SYNOPSIS
int atoi(s)
char *s;
long atol(s)
char *s;
DESCRIPTION
These functions convert the string pointed to by s to
integer or long integer representation, respectively.
The first unrecognized character ends the string.
ATOI and ATOL recognize an optional string of blanks or
tabs, then an optional sign, and then a string of
digits.
SEE ALSO
sscanf, itoa
Page 4
ator50, r50toa, atosix, sixtoa
ator50, r50toa, atosix, sixtoa: ascii/radix50/sixbit
conversion
SYNOPSIS
int ator50(result, buf)
int *result;
char *buf;
int r50toa(buf, r50_value)
char *buf;
int r50_value;
int atosix(result, buf)
int *result;
char *buf;
int sixtoa(buf, six_value)
char *buf;
int six_value;
DESCRIPTION
ATOR50 takes the given buffer, containing a string of
ascii characters, and converts at most the leading six
characters (fewer if the string is shorter than six
characters) to the rightmost 32 bits of a radix-50
integer, which it places in *result. It returns the
number of characters converted. Ascii characters
without a radix-50 equivalent are converted as if they
were periods, except lowercase letters, which are
converted as if they were uppercase.
R50TOA takes the rightmost 32 bits of the given radix-50
integer and converts them into six ascii characters,
appending a trailing nul character; thus R50TOA
requires that the given buf be at least seven characters
long. R50TOA always returns 6 (the number of characters
converted).
ATOSIX takes the given buffer, containing a string of
ascii characters, and converts at most the leading six
characters (fewer if the string is shorter than six
characters) to a sixbit integer, which it places in
*result. It returns the number of characters converted.
Ascii characters without a sixbit equivalent are
converted as if they were periods, except lowercase
letters, which are converted as if they were uppercase.
SIXTOA takes the given sixbit integer and converts it
into six ascii characters, appending a trailing nul
character; thus SIXTOA requires that the given buf be
at least seven characters long. SIXTOA always returns 6
(the number of characters converted).
Page 5
chdir
chdir: change connected directory
SYNOPSIS
int chdir(dir_name, password)
char *dir_name;
char *password;
DESCRIPTION
Chdir changes the connected directory of the current job
to be the named dir_name. This is equivalent to the
TOPS-20 command
@Connect dir_name
------- --------
The given password may be NULL, in which case the
function assumes that no password is necessary for the
change of directory; if a password is required for the
change, but none is given, the function will fail.
DIAGNOSTICS
Chdir returns 0 for success, -1 for failure.
Page 6
chmod
chmod: change protection of file
SYNOPSIS
int chmod(filename, prot)
char *filename;
int prot;
DESCRIPTION
Chmod changes the protection of the named file to prot.
DIAGNOSTICS
Chmod returns 0 for success, -1 for failure.
Page 7
close
close: close a file
SYNOPSIS
int close(fildes)
int fildes;
DESCRIPTION
Given a file descriptor (fildes) as returned by OPEN or
CREAT, CLOSE closes the associated file.
SEE ALSO
open, creat
Page 8
comnd.h, csb_setup, flddb_, comnd_, fdbc_setup, com_graph
comnd.h, csb_setup, flddb_, comnd_, fdbc_setup, com_graph:
access to COMND% JSYS command handling
SYNOPSIS
#include <comnd.h>
int csb_setup(csb_addr, flags, ifildes, ofildes,
retyp_text_ptr, textbuf_ptr, remain_count,
atombuf_ptr, atombuf_size, gtjfn_argblk)
csb_entry *csb_addr;
unsigned int flags;
int ifildes;
int ofildes;
char *retyp_text_ptr;
char *textbuf_ptr;
int remain_count;
char *atombuf_ptr;
int atombuf_size;
int *gtjfn_argblk;
fdb_entry *flddb_(fdb_addr, fun_code, flags, data, help_str,
default_str, next_fdb_addr, breakm_addr)
fdb_entry *fdb_addr;
int fun_code;
unsigned int flags;
int data;
char *help_str;
char *default_str;
fdb_entry *next_fdb_addr;
int *breakm_addr;
fdb_entry *flddb_ini(fdb_addr)
fdb_entry *fdb_addr;
fdb_entry *flddb_noi(fdb_addr, noise_str, next_fdb_addr)
fdb_entry *fdb_addr;
char *noise_str;
fdb_entry *next_fdb_addr;
fdb_entry *flddb_cma(fdb_addr, next_fdb_addr)
fdb_entry *fdb_addr;
fdb_entry *next_fdb_addr;
fdb_entry *flddb_cfm(fdb_addr, next_fdb_addr)
fdb_entry *fdb_addr;
fdb_entry *next_fdb_addr;
int comnd_(csb_addr, fdb_chain_addr, match_fdb_addr,
extra_info_addr)
csb_entry *csb_addr;
fdb_entry *fdb_chain_addr;
fdb_entry **match_fdb_addr;
int *extra_info_addr;
Page 9
comnd.h, csb_setup, flddb_, comnd_, fdbc_setup, com_graph
int fdbc_setup(fdbc_addr, fdbs, next_indices, gtj_argtab_addr,
fail_index)
fdbchn_head *fdbc_addr;
fdb_entry *fdbs;
int next_indices[];
int *gtj_argtab_addr;
int fail_index;
int com_graph(csb_addr, fdbc_heads, auto_reparse, match_entries,
me_size, me_count_addr, ret_err_addr)
csb_entry *csb_addr;
fdbchn_head fdbc_heads[];
int auto_reparse;
fdb_match_entry match_entries[];
int me_size;
int *me_count_addr;
int *ret_err_addr;
DESCRIPTION
<Comnd.h> and the associated functions provide access to
the TOPS-20 command-processing capabilities (COMND%
JSYS).
<Comnd.h>
<Comnd.h> provides a host of type and #define
definitions to be used in command handling. A
careful perusal of it, as well as a good reading of
the COMND% JSYS description in the TOPS-20 Monitor
Calls Reference Manual, is recommended before using
any of these routines.
CSB_SETUP(csb_addr, flags, ifildes, ofildes,
retyp_text_ptr, textbuf_ptr, remain_count,
atombuf_ptr, atombuf_size, gtjfn_argblk)
CSB_SETUP is used to set up command state blocks;
it always returns 0.
Csb_addr is (obviously) the address of a command
state block.
Flags is the value to place in the flags/reparse
address word of the csb, except that no reparse
dispatch address can be given (reparsing must be
handled manually when using these functions, except
COM_GRAPH). All of the flag bits defined for the
csb flags halfword are #define'd in <comnd.h>.
Ifildes and ofildes are the input and output file
designators for I/O for the command; _NULIO
(#define'd in <comnd.h>) may be used if the command
being parsed is a string instead of being from a
Page 10
comnd.h, csb_setup, flddb_, comnd_, fdbc_setup, com_graph
typing user, otherwise _PRIIN and _PRIOU are
probably the best choice.
Retyp_text_ptr should be a character string for the
prompt, and may be NULL, in which case CSB_SETUP
uses an empty string as the prompt.
Textbuf_ptr is a character array for the command's
text buffer, and remain_count is its size in
characters. Likewise, atombuf_ptr is a character
array for the atom buffer, and atombuf_size is its
size in characters.
Gtjfn_argblk is a pointer to a long-form GTJFN%
argument block, to be used when one is attempting to
parse a filespec of some sort (more about this
argument block later). If no filespecs are to be
parsed, gtjfn_argblk may be NULL.
FLDDB_(fdb_addr, fun_code, flags, data, help_str,
default_str, next_fdb_addr, breakm_addr)
FLDDB_ is used to set up function descriptor blocks;
it is analogous to the FLDBK. macro defined in
SYS:MONSYM.MAC.
Fdb_addr is the address of a function descriptor
block, which is always the return value of FLDDB_.
Fun_code is the function code for this fdb, and
flags is a value to be placed in the "function
flags" quarterword of the fdb. All of the function
codes and flag bits defined for COMND% are define'd
in <comnd.h>.
Data is the function-specific data for the given
function code, as follows:
Function Data Is
-------- -------
_CMKEY address of TBLUK% keyword index table,
an object of type tb_comtab, as defined
in <tb.h>
_CMNUM radix of number (2 through 10,
inclusive)
_CMNOI un-parenthesized noise string
_CMSWI address of TBLUK% switch index table, an
object of type tb_comtab, as defined in
<tb.h>
_CMIFI unused
_CMOFI unused
_CMFIL unused
Page 11
comnd.h, csb_setup, flddb_, comnd_, fdbc_setup, com_graph
_CMFLD (not used by COMND%) pointer to
character buffer into which COMND_
(possibly called via COM_GRAPH) will
place contents of atom buffer on
successful parse of field; NULL for
none
_CMCFM unused
_CMDIR possibly CM_DWC
_CMUSR unused
_CMCMA unused
_CMINI unused
_CMFLT unused
_CMDEV unused
_CMTXT (not used by COMND%) pointer to
character buffer into which COMND_
(possibly called via COM_GRAPH) will
place contents of atom buffer on
successful parse of field; NULL for
none
_CMTAD left halfword may be #define'd bits
CM_IDA, CM_ITM, CM_NCI; right halfword
is be address of three-word block if
CM_NCI is on
_CMQST (not used by COMND%) pointer to
character buffer into which COMND_
(possibly called via COM_GRAPH) will
place contents of atom buffer on
successful parse of field; NULL for
none
_CMUQS address of four-word block of 128 break
chararacter mask bits
_CMTOK pointer to token string
_CMNUX radix of number (2 through 10,
inclusive)
_CMACT (not used by COMND%) pointer to
character buffer into which COMND_
(possibly called via COM_GRAPH) will
place contents of atom buffer on
successful parse of field; NULL for
none
_CMNOD (not used by COMND%) pointer to
character buffer into which COMND_
(possibly called via COM_GRAPH) will
place contents of atom buffer on
successful parse of field; NULL for
none
Page 12
comnd.h, csb_setup, flddb_, comnd_, fdbc_setup, com_graph
Help_str is a pointer to a user-supplied help
message for this fdb, and default_str is a pointer
to user-supplied default string. Help_str
(default_str) may be NULL if no user-supplied help
message (default string) is required; if a non-NULL
help_str (default_str) is present, FLDDB_
automatically sets bit CM_HPP (CM_DPP) in the flags
quarterword of the fdb.
Next_fdb_addr is the address of the next fdb in a
chain of fdbs (NULL if this is the last or only fdb
in a chain). The reason that FLDDB_ returns its
argument is so that the value passed for
next_fdb_addr can be a call to FLDDB_ for the next
fdb in the chain.
Breakm_addr is the address of a four-word break mask
for the fdb (as described in the TOPS-20 Monitor
------- -------
Calls Reference Manual), and may be NULL if none is
----- --------- ------
needed. If a break mask address is supplied, bit
CM_BRK must be on in the passed-in flags values, or
the address will be ignored.
FLDDB_INI(fdb_addr)
FLDDB_INI is a #define'd macro to initialize a
_CMINI fdb. It is equivalent to FLDDB_(fdb_addr,
_CMINI, 0, 0, NULL, NULL, NULL, NULL). FLDDB_INI
does not provide for a next fdb address because it
would be highly unusual for an initialization fdb to
need one.
FLDDB_NOI(fdb_addr, noise_str, next_fdb_addr)
FLDDB_NOI is a #define'd macro to initialize a
_CMNOI fdb. It is equivalent to FLDDB_(fdb_addr,
_CMINI, 0, noise_str, NULL, NULL, next_fdb_addr,
NULL).
FLDDB_CMA(fdb_addr, next_fdb_addr)
FLDDB_CMA is a #define'd macro to initialize a
_CMCMA fdb. It is equivalent to FLDDB_(fdb_addr,
_CMCMA, 0, 0, NULL, NULL, next_fdb_addr, NULL).
FLDDB_CFM(fdb_addr, next_fdb_addr)
FLDDB_CFM is a #define'd macro to initialize a
_CMCFM fdb. It is equivalent to FLDDB_(fdb_addr,
_CMCFM, 0, 0, NULL, NULL, next_fdb_addr, NULL).
Page 13
comnd_: parsing commands token by token
Parsing commands token by token
COMND_ is used to parse commands one token at a
time, much as one would do in a MACRO-20 program.
COMND_(csb_addr, fdb_chain_addr, match_fdb_addr,
extra_info_addr)
At this point, having used CSB_SETUP to set up a
command state block and FLDDB_ to set up function
descriptor blocks, one can use COMND_ to parse
commands (although the full usefulness of this group
of functions requires the use of FDBC_SETUP and
COM_GRAPH).
Csb_addr and fdb_chain_addr are respectively the
address of a command state block and a function
descriptor block (which may have other fdbs chained
on to it).
Match_fdb_addr is the address of a pointer to an fdb
entry, and extra_info_addr is the address of an
integer.
On a successful parse COMND_ will return
COMND_SUCCESS, the address of the fdb that matched
the part of the command parsed will be stored into
*match_fdb_addr, and the contents of AC2 after the
execution of the COMND% JSYS will be stored into
*extra_info_addr.
If a reparse is needed, COMND_ will return
COMND_REPARSE without modifying either
*match_fdb_addr or *extra_info_addr.
If an error occured (or no fdb in the chain could be
used to parse the next input), COMND_ will return
COMND_ERROR, with *extra_info_addr containing a
TOPS-20 error code, and *match_fdb_addr unchanged.
Parsing commands all at once
It is possible to parse commands in a more automated
fashion than one could achieve even in a MACRO-20
program, using the functions FDBC_SETUP and
COM_GRAPH. These two operate on a graph of the
structure of acceptable commands, and can be used to
parse entire multiple-token commands in a single
call.
Page 14
fdbc_setup, com_graph: parsing commands all at once
A command graph is an array of function descriptor
block chain heads (fdbcs). Each fdbc in the array
is designed to parse some single token out of a set
of possible tokens at a given position in the
command structure. Furthermore, each fdbc contains
within it information as to the fdbc to proceed to
next, depending upon whether the entire current fdbc
fails to parse the current token or some fdb within
it succeeds in parsing the current token.
Each fdbc contains the address of an fdb or fdb
chain, the address of a GTJFN% long-form argument
block, and the index of another fdbc in the array.
Let the "current fdbc" be the one which is used to
attempt to parse the current token in the command.
If the current fdbc fails to parse the current
token, then the current fdbc's "other fdbc" index is
looked at. If this index is -1, attempts to
continue parsing are given up (i.e., the parse
fails). If it is some other value, it is the index
of the fdbc which is next used to attempt to parse
the current token. This is how parsing failures are
handled.
Parsing successes are handled as follows. Each fdb
in the chain has an extra integer (ignored by the
COMND% JSYS) which is again the index of another
fdbc in the array. If the current fdbc succeeds in
parsing the current token, then the matched fdb's
"another fdbc" index is looked at. If this index is
-1, parsing is considered successful (the parsed
command ends at the matched token). If it is some
other value, it is the index of some fdbc, which
will be used to try to parse the next token in the
command.
There is one complication to the fdbc indices
attached to the fdbs. If an fdb's function code is
_CMKEY or _CMSWI (both of which match tokens using
keyword tables), the "next fdbc index" integer is
actually a pointer to an array of such integers.
This array should have exactly one entry for each
entry in the keyword table used by the fdb in
question. Each array entry is the fdbc index of the
next fdbc to use when the given fdb matches the
current token and the corresponding keyword was the
one that matched.
Finally, if an entry in one of these fdbc index
arrays corresponds to a keyword which can be ended
with a colon (":"), the two halves of the entry are
considered separately. If the keyword matches and
Page 15
fdbc_setup, com_graph: parsing commands all at once
the user typed the colon (or the colon was filled in
automatically because escape recognition was used),
the next fdbc index is taken from the left halfword
of the array entry. If the keyword matches and the
colon was not typed (and not escape-recognized), the
next fdbc entry is taken from the right halfword.
Thus, each fdbc tells where in the graph to go if
that fdbc fails, each fdb tells where in the graph
to go if that fdb succeeds, and any keyword-matching
fdb tells where in the graph to go for each possible
matched keyword, including possibly different places
to go depending upon whether the keyword was parsed
with a colon or not.
The only field in the fdbc which we have not yet
discussed is the pointer to a long-form GTJFN%
argument block. The use of this field is discussed
in the description of function COM_GRAPH.
FDBC_SETUP(fdbc_addr, fdbs, next_indices,
gtj_argtab_addr, fail_index)
FDBC_SETUP sets up an fdbc, always returning zero
(no failures are recognized). FDBC_SETUP is called
once for each fdbc in the array of fdbcs for a given
command graph.
Obviously, fdbc_addr is the address of the fdbc to
fill in.
Fdbs is the address of an fdb (possibly the first in
a chain of fdbs).
Next_indices is the address of an array of fdbc
array indices, and each entry is the index of the
fdbc to go to when the corresponding fdb matches a
token. Thus, there are the same number of entries
in this array as there are fdbs in the chain
described in the previous paragraph.
Gtj_argtab_addr is the address of a long-form GTJFN%
argument table, and may be NULL if none is needed.
Fail_index is the array index of the fdbc to go to
when the one being set up is used to attempt to
match the current token, and fails to do so.
COM_GRAPH(csb_addr, fdbc_heads, auto_reparse,
match_entries, me_size, me_count_addr,
ret_err_addr)
Page 16
fdbc_setup, com_graph: parsing commands all at once
COM_GRAPH is used to "execute" a command graph. It
takes an entire command graph (array of fdbcs), and
matches the current input by performing multiple
calls to COMND_, filling in an array of matched fdb
addresses as it matches each token of the command.
It also has the ability to do automatic reparsing of
the input when the user deletes already-parsed
input.
Csb_addr is the address of a command state block, as
initialized by CSB_SETUP.
Fdbc_heads is the address of an array of fdbcs (a
command graph), as initialized by FDBC_SETUP.
Auto_reparse is a boolean flag (pass either TRUE or
FALSE) which controls automatic reparsing of the
input when the user deletes back over already-parsed
tokens. If the flag is TRUE, such reparsing is done
automatically; if it is FALSE, COM_GRAPH returns
COMGR_REPARSE when such reparsing is needed.
Match_entries is an array of objects of type
fdb_match_entry. Every time COM_GRAPH matches a
token, the next entry of match_entries is filled in;
the field fcm_fdb receives the address of the
matching fdb, and the field fcm_extra_info receives
the extra information returned by COMND_ (i.e., the
information returned in AC2 after a successful
COMND% JSYS call).
Me_size is the number of entries available in
match_entries, and COM_GRAPH returns the number of
entries it filled in in *me_count_addr.
If the passed command graph (fdbc_heads) fails to
match the input, *ret_error_addr receives the
most-recent system error code returned by COMND_.
Starting with the first fdbc in the passed array,
COM_GRAPH attempts to match the current input by
executing successive calls to COMND_ with the
information out of the current fdbc. If both the
current fdbc and the command state block contain
non-NULL pointers to GTJFN% long-form argument
tables, COM_GRAPH copies the contents of the table
pointed to by the current fdbc to the table pointed
to by the csb, before calling COMND_. COMND% JSYS
uses the GTJFN% table in the csb as an aid to
matching filespecs (with fdb function codes _CMIFI,
_CMOFI, and _CMFIL). Note that because the GTJFN%
table is pointed to by the csb, instead of by an
fdb, it is difficult to gracefully parse for two
Page 17
fdbc_setup, com_graph: parsing commands all at once
different possible filespecs in one call to COMND_
(this is true of the COMND% JSYS, also).
When a call to COMND_ succeeds, COM_GRAPH fills in
the next entry of match_entries with the matched
fdb's address and the returned extra information,
then attempts to match the next token by using the
fdbc whose array index is given by the matched fdb.
Successful matching of a command occurs when the
index of the next fdbc to use is -1; in this case
COM_GRAPH returns COMGR_SUCCESS.
When a call to COMND_ fails with some fdbc,
COM_GRAPH tries to match the current token again,
using the fdbc whose array index is the "fail index"
given by current (failing) fdbc. Failure to match a
command occurs when that index is -1; in this case
COM_GRAPH returns COMGR_ERROR, with *ret_error_addr
filled in with the system error code returned by the
failed call to COMND_.
Two other return values are possible from COM_GRAPH.
COMGR_REPARSE is discussed above in the description
of the auto_reparse parameter. COMGR_FULL is
returned when parsing has been successful so far,
but input still waits (the command has not yet been
completely parsed) and the match_entries array is
full.
MATCHING USER-ENTERED COMMANDS
Parsing user-entered commands is relatively
straightforward using these functions. In fact, it
is generally true that the amount of code necessary
to set up everything in a command graph (which code
only has to be executed once) will be greater than
that which must be executed to actually parse a
command.
The easiest way to proceed is to have two command
graphs: one which only does the _CMINI
(initialization) function, and another which
actually parses commands. The command state block
should specify _PRIIN for the input jfn and _PRIOU
for the output jfn.
The initializer should be executed before parsing
each new command, and after any error, to provide
the user with the ability to use the ctrl/H error
recovery feature of COMND% JSYS. When used before
parsing a command, the initializer should never
fail, unless there is some internal inconsistency in
the csb or an fdb. Experience seems to show that
Page 18
fdbc_setup, com_graph: parsing commands all at once
when the user types a ctrl/H to recover the original
input up to the point of some error in a previous
command, the initializer will always fail with the
same error as caused the original failure. However,
when this happens the reparse bit will be set in the
csb flags halfword after the initializer is
performed, and the error can be ignored if that bit
is on.
When COM_GRAPH returns COMGR_REPARSE, the
initializer should NOT be re-executed. Simply redo
the main command-parsing graph. Best of all, let
COM_GRAPH do automatic reparsing for the main
command graph, and ignore this problem entirely.
MATCHING STRING COMMANDS
Parsing string commands (i.e., commands which are
strings and are not coming from a terminal) is
somewhat different than parsing user-entered
commands.
In this case, there is no need for an initialization
graph (_CMINI function). Instead, initialize (with
CSB_SETUP) the command state block with _NULIO for
both the input and output jfns, and with the command
buffer (the command string) for parameter
textbuf_ptr and the length of the command for
parameter remain_count. Then, set fields csb_cmptr
and csb_cminc in the csb to be the same as csb_cmbfp
and csb_cmcnt, respectively. This essentially does
the _CMINI for the command string. The difference
is that _CMINI, when performed for a command coming
from a terminal, also reads in the command. When
the command is a string, it is already in the
buffer, so no read is necessary.
Reparsing a string command should never be
necessary, since characters will never be deleted
out of it while parsing is in progress. Also, if an
error occurs, there is no opportunity to do a ctrl/H
recovery. Thus there is no need for an initializer,
and COM_GRAPH should be told not to do automatic
reparsing (needing a reparse should be a quite
unexpected error).
SEE ALSO
TOPS-20 Monitor Calls Reference Manual, gtjfn.h, tb.h,
------- ------- ----- --------- ------
tb_build, g_errstring, Introduction to DECSYSTEM-20
------------ -- ------------
Assembly Language Programming (Gorin)
-------- -------- -----------
Page 19
comnd.h, csb_setup, flddb_, comnd_, fdbc_setup, com_graph
DIAGNOSTICS
No failures are discovered by CSB_SETUP, FLDDB_, or
FDBC_SETUP.
COMND_ returns
COMND_SUCCESS (1) for a successful parse;
COMND_REPARSE (0) if a reparse is needed;
COMND_ERROR (-1) if an error occurred, in which case
*extra_info_addr contains a TOPS-20 error code.
COM_GRAPH returns
COMGR_SUCCESS (1) for a successful parse;
COMGR_FULL (2) for a successful parse so far, but
match_entries[] is full and input still waits;
COMGR_REPARSE (0) if a reparse was needed and
auto_reparse was FALSE;
COMGR_ERROR (-1) if an error occurred, in which case
*ret_error_addr contains a TOPS-20 error code
filled in by COMND_.
For error reporting purposes, the string corresponding
to a given TOPS-20 error code can be obtained using
G_ERRSTRING.
BUGS
Long-form GTJFN% JSYS argument tables which contain
pointers to default strings must have pointers which
point one byte BEFORE the string, instead of AT it (C
character pointers point AT strings; JSYS's expect
pointers which point one byte BEFORE them).
Page 20
creat
creat: create a new file
SYNOPSIS
int creat(name, prot)
char *name;
int prot;
DESCRIPTION
CREAT creates a new file or prepares to rewrite an
existing file called name, given as a null-terminated
string. If the file did not exist, it is given
protection prot. If the file did exist, a new
generation of the file is created with the same
protection as the old generation. CREAT returns a file
descriptor for the created file, which is OPEN'ed.
SEE ALSO
open, close
DIAGNOSTICS
CREAT returns a file descriptor if successful, -1 if
not.
Page 21
date, daytime, adate, idate, walltime, cputime
date, daytime, adate, idate, walltime, cputime: date and
time handling
SYNOPSIS
int date()
int daytime(internal_date)
int internal_date;
int adate(buf, internal_date, conv_flags)
char buf[];
int internal_date;
int conv_flags;
int idate(idate_addr, buf, conv_flags)
int *idate_addr;
char buf[];
int conv_flags;
int walltime()
int cputime(code)
int code;
DESCRIPTION
These functions manipulate dates and times.
Internal_date, in the above synopsis, is an integer
containing a date in TOPS-20 internal date format; this
contains a day number (since November 17, 1858) in the
left half, and a fraction of a day in the right half.
Any of the above functions which take an internal-format
date as an argument will accept zero to indicate the
current date.
DATE returns the current date in internal format.
DAYTIME takes the given internal-format date, and
returns the number of seconds since midnight on the
given date.
ADATE converts from the given internal-format date to an
ASCII string, which it places in buf[] (without checking
for overflow of the string). Conv_flag contains the
value which will be given to the TOPS-20 jsys Odtim% to
control how the conversion should be done (see the
Monitor Calls Reference Manual for further information;
conv_flag is placed unchanged in AC3). Two common
values for conv_flag are: zero (0), which causes
conversion to the form "dd-mmm-yy hh:mm:ss", and
negative one (-1), which causes conversion to the form
"weekday, month day, year hh:mm:ss".
Page 22
date, daytime, adate, idate, walltime, cputime
IDATE converts from the given ASCII date and time (in
buf[]) to the corresponding internal-format date, which
it places in *idate_addr. Conv_flag contains the value
which will be given to the TOPS-20 jsys Idtim% to
control how the conversion should be done (see the
Monitor Calls Reference Manual for further information;
conv_flag is placed unchanged in AC2). The normal value
is zero (0).
WALLTIME returns the number of milliseconds for which
the calling job has been logged in.
With code equal to zero, CPUTIME returns the number of
milliseconds of cpu time used so far by the calling
process. With code not equal to zero, it returns the
number of milliseconds of cpu time used so far by the
calling job.
DIAGNOSTICS
ADATE and IDATE both return zero for success, or a
TOPS-20 error code for failure.
Page 23
defsic
defsic: define an interrupt handler for the programmable
software interrupt system
SYNOPSIS
int defsic(fork, channel, level, fun)
int fork;
int channel;
int level;
void (*fun)();
DESCRIPTION
Defsic is used to define a handler for PSI system
interrupts. Fork is the handle for the process for
which the handler is being defined (-1 for the calling
process), channel is the PSI channel (-1 to 35), level
is the interrupt level (1 to 3), and fun is the address
of the handler function.
Channel -1 actually is not a PSI channel; defining a
handler for this channel (and then enabling it with
enasic()) allows one to catch arithmetic errors via the
SWTRP% jsys. Level is ignored in this case. Catching
arithmetic errors via SWTRP% is usually more efficient
than catching them via PSI system interrupts on channel
6 or 7.
DIAGNOSTICS
Returns zero for success, -1 for illegal channel number,
-2 for illegal level number (except when channel is -1),
otherwise a TOPS-20 error code.
SEE ALSO
Enapsi(), dispsi(), enasic(), dissic(), intrpt(),
TOPS-20 Monitor Calls Reference Manual (section 2.6,
SWTRP%, RIR%, XRIR%).
Page 24
_docall
_docall: call a function (or other addressable object)
SYNOPSIS
int _docall(f_ptr)
int (*f_ptr)();
DESCRIPTION
_DOCALL calls the given pointed-to function (with no
arguments) and returns whatever that function returns.
It can actually be used to call any addressable object
(including, for example, an array of integers filled
with executable code).
SEE ALSO
execs, which uses _docall to call an array of integers
filled with executable code to perform the final acts of
running a program in the current process
DIAGNOSTICS
_DOCALL returns whatever the thing it calls returns.
BUGS
Use this function carefully. You can call your own
stack if you want, but nobody in the world is going to
be responsible for what happens.
Page 25
enapsi, dispsi
enapsi, dispsi: enable/disable the programmable software
interrupt system
SYNOPSIS
int enapsi(fork)
int fork;
int dispsi(fork)
int fork;
DESCRIPTION
Enapsi() and dispsi() respectively enable and disable
the PSI system for the process represented by the given
fork handle (-1 means the calling process).
DIAGNOSTICS
Both routines return zero for success, -1 if the PSI
system was already in the desired state (on when
enapsi() was called; off when dispsi() was called), or
a TOPS-20 error code. Note that the FORTRAN run-time
system turns on the PSI system by default; this may
cause -1 returns from enapsi() in programs which call
FORTRAN subroutines or functions.
SEE ALSO
Defsic(), enasic(), dissic(), intrpt(), TOPS-20 Monitor
Calls Reference Manual (section 2.6, SKPIR%, SIR%,
XSIR%, EIR%, DIR%).
Page 26
enasic, dissic
enasic, dissic: enable/disable a programmable software
interrupt system channel
SYNOPSIS
int enasic(fork, channel)
int fork;
int channel;
int dissic(fork, channel)
int fork;
int channel;
DESCRIPTION
Enasic() and dissic respectively enable and disable
interrupts on PSI system channels. Fork is the handle
for the process for which interrupts are being enabled
or disabled (-1 for the calling process), and channel
(-1 through 35) is the channel for which to enable or
disable; 0 through 35 are the PSI system channels.
-1 is a special channel, which enables or disables
arithmetic interrupts via the SWTRP% jsys. Catching
arithmetic errors via SWTRP% is usually more efficient
than catching them via PSI system interrupts on channel
6 or 7.
DIAGNOSTICS
Both functions return zero for success, -1 for illegal
channel (outside of range -1 to 35), otherwise a TOPS-20
error code.
SEE ALSO
Enapsi(), dispsi(), defsic(), intrpt(), TOPS-20 Monitor
Calls Reference Manual (section 2.6, AIC%, DIC%,
SWTRP%).
Page 27
execl, execs
execl, execs: executing processes
SYNOPSIS
execl(prog_file, argline, visible)
char *prog_file;
char *argline;
int visible;
int execs(prog_name, offset, err_count, allow_uuos)
char *prog_name;
int offset;
int err_count;
int allow_uuos;
DESCRIPTION
These two functions are used to execute programs in
either a subprocess or the current process.
EXECL executes the named program in a subprocess,
placing the given argument line into the Rscan% buffer
for the process. If visible is TRUE, the primary input
and output designators for the program will both be the
terminal; if it is false, they will both be the null
device (NUL:).
EXECS executes the named program in the current process;
thus, if it is successful, it does not return. Offset
is the offset past the start address at which to start
the program (offset can be only zero or one). Err_count
is a value to be placed in word .JBERR of low memory
before starting the program; this is primarily so
programs like LINK can tell if the compiler that invoked
them saw errors, indicating that they should not
continue. Allow_uuos may be either TRUE to allow the
program to perform Uuos (TOPS-10 monitor calls), or
FALSE to not allow it to do so.
DIAGNOSTICS
EXECL returns 1 for success, -1 for failure. EXECS
returns 0 if the given offset is illegal (not zero or
one), otherwise a TOPS-20 error code. If successful,
EXECS does not return, because the new program replaces
the calling one.
BUGS
Because of extreme limitations on the amount of code to
be run to unmap the calling program and to get and start
the new program (which code has to fit in the
accumulators), EXECS can fail quite imaginatively and
unrecoverably when given ridiculous arguments; giving
"tty:" for the executable file is an example. It is
best to avoid mistakes when dealing with powerful
functions.
Page 28
exit, _exit, halt
exit, _exit, halt: terminate execution
SYNOPSIS
int exit(status)
int status;
int _exit(status)
int status;
int halt()
DESCRIPTION
These functions are the normal means of terminating a
program. _EXIT terminates the program immediately;
EXIT flushes and closes any open files obtained via
FOPEN before terminating. The
@CONTINUE
--------
command to the EXEC is ineffective after an EXIT or
_EXIT.
Although it may be used in the future, for now the
status argument is ignored by both EXIT and _EXIT.
HALT just halts the program; it is like _EXIT except
that the
@CONTINUE
--------
command to the EXEC causes it to return.
Page 29
fclose, fflush
fclose, fflush: close or flush a stream
SYNOPSIS
#include <stdio.h>
int fclose(stream)
FILE *stream;
int fflush(stream)
FILE *stream;
DESCRIPTION
FFLUSH causes any buffered output data for the given
stream to be sent to the associated file.
FCLOSE causes the given stream, as returned by FOPEN, to
be closed; it also reclaims any buffer space allocated
to the stream. If any buffered output data is present
for the stream, it is FFLUSH'ed before the stream is
closed.
FCLOSE is called automatically by EXIT for all FOPEN'ed
streams.
SEE ALSO
fopen, close, exit
Page 30
feof, ferror, fileno, clrerr
feof, ferror, fileno, clrerr: stream status inquiries
SYNOPSIS
#include <stdio.h>
int feof(stream)
FILE *stream;
int ferror(stream)
FILE *stream;
int fileno(stream)
FILE *stream;
int clrerr(stream)
FILE *stream;
DESCRIPTION
FEOF returns non-zero when end-of-file has been read
(and not cleared) on the named stream, otherwise it
returns zero.
FERROR returns non-zero when an error has occurred
reading or writing the named stream, otherwise it
returns zero. Unless it is cleared by CLRERR, the error
indication lasts until the stream is closed.
FILENO returns the integer file descriptor associated
with the named stream; see also OPEN.
CLRERR resets the error indication on the named stream.
These functions are all implemented as macros; as such
they can cause side effects (e.g., post-incrementing of
an argument) to occur more than once.
SEE ALSO
fopen, open
Page 31
fgetc, getc, getchar, fgetw, getw
fgetc, getc, getchar, fgetw, getw: get a character or word
from a stream
SYNOPSIS
#include <stdio.h>
int fgetc(stream)
FILE *stream;
int getc(stream)
FILE *stream;
int getchar()
int fgetw(stream)
FILE *stream;
int getw()
DESCRIPTION
FGETC returns the next character from the named input
stream.
GETC behaves like FGETC, but it is a macro, not a
function, and will thus cause any side effects (e.g.,
post-incrementation of its argument) to occur more than
once.
GETCHAR() is equivalent to FGETC(stdin).
FGETW returns the next word (36-bit integer on the
DEC-20) from the named input stream. It returns the
constant EOF upon end-of-file or error, but since that
is a valid integer value, FEOF or FERROR should be used
to check the success of FGETW. FGETW assumes no special
alignment in the stream.
GETW() is equivalent to FGETW(stdin).
SEE ALSO
fopen, putc, fgets, scanf, ungetc
DIAGNOSTICS
These functions return the constant EOF at end-of-file
or upon any error.
BUGS
FGETW and GETW do not, at the present, work properly;
the reason being that seven-bit characters do not fit
properly in 36-bit words, and both routines do character
input.
Page 32
fgets, gets
fgets, gets: get a string from a stream
SYNOPSIS
#include <stdio.h>
int fgets(s, n, stream)
char *s;
int n;
FILE *stream;
int gets(s, n)
char *s;
int n;
DESCRIPTION
FGETS reads characters from the named input stream and
places them into the string s. If the value passed for
the integer argument n is zero, FGETS stops reading when
it sees a newline character. If the value passed for n
is greater than zero, FGETS stops when it sees a newline
or has read (n - 1) characters, whichever comes first;
if the value passed is less than zero, it stops when it
has read -(n - 1) characters. End-of-file or a file
error will also cause FGETS to stop reading characters.
If a newline character caused FGETS to stop reading,
that newline is included in the returned string. A null
character is placed in the string after the last
character read.
GETS() is equivalent to FGETS(stdin).
Both FGETS and GETS return their first arguments; both
return NULL if end-of-file or a file error occurred on
the first attempt to read a character.
SEE ALSO
puts, getc, scanf, ferror
Page 33
filnam, getname, fgetname
filnam, getname, fgetname: determine real file name
SYNOPSIS
int filnam(fildes, fields, name)
int fildes;
char *fields;
char *name;
int getname(fildes, name)
int fildes;
char *name;
int fgetname(stream, name)
FILE *stream;
char *name;
DESCRIPTION
FILNAM fills in name with pieces of the filename
associated with the given file descriptor fildes.
Fields is string of descriptors for specifying which
parts of the filename are to be returned; each
descriptor is two characters "fw", where "f" can be:
Char Corresponds to Field
---- --------------------
v(V) device
d(D) directory
n(N) name
e(E) extension
g(G) generation number
f(F) all of the above five
p(P) protection
a(A) account
t(T) ";T" for temporary files
and where "w" can be:
Char Means
---- -----
a(A) return this field
d(D) return this field if it is not the default
n(N) do not return this field
The returned string is terminated with a null character;
FILNAM does not check for overflow of the target string.
GETNAME(fildes, name) is equivalent to FILNAM(fildes,
"fata", name).
FGETNAME(stream, name) is equivalent to
GETNAME(fileno(stream), name).
Page 34
filnam, getname, fgetname
SEE ALSO
open, close, creat, fileno
DIAGNOSTICS
FILNAM returns 0 for success, -1 for failure. GETNAME
returns buffer for success, -1 for failure. FGETNAME
returns buffer for success, 0 for failure.
Page 35
filsiz, filpcnt, filpused, filpfree
filsiz, filpcnt, filpused, filpfree: determine file size
SYNOPSIS
int filsiz(fildes)
int fildes;
int filpcnt(fildes)
int fildes;
int filpused(fildes, page)
int fildes;
int page
int filpfree(fildes, page)
int fildes;
int page
DESCRIPTION
These four routines return information related to the
size and usage of the file associated with the given
file descriptor.
FILSIZ returns the size of the file in bytes.
FILPCNT returns the size of the file in pages.
FILPUSED returns the page number of the first used page
in the file at or after the given page (page numbers
start at zero).
FILPFREE returns the page number of the first free page
in the file at or after the given page. This page could
represent either a hole in the file or the page after
the last one.
SEE ALSO
fileno
DIAGNOSTICS
FILSIZ and FILPCNT both return -1 for errors. FILPUSED
(FILPFREE) returns -1 both for errors and for no more
used (free) pages.
Page 36
fopen, fdopen, freopen
fopen, fdopen, freopen: open (or reopen) a stream
SYNOPSIS
#include <stdio.h>
FILE *fopen(filename, mode)
char *filename;
char *mode;
FILE *fdopen(fildes, mode)
int fildes;
char *mode;
FILE *freopen(filename, mode, fp)
char *filename;
char *mode;
FILE *fp
DESCRIPTION
FOPEN opens the file named by filename and associates a
stream with it. FOPEN returns a pointer to be used in
subsequent operations to identify the file.
Mode is a character string having one of the following
values:
"r" open for reading
"w" open for writing
"a" append: open for writing at end of file, or
create for writing
In addition, each type may be followed by a '+' to have
the file opened for reading and writing. "r+" positions
the stream at the beginning of the file, "w+" creates or
truncates it, and "a+" positions it at the end. Both
reads and writes may be used on read/write streams, with
the limitation that an FSEEK, REWIND, or reading an
end-of-file must be used between a read and a write or
vice-versa.
FDOPEN associates a stream with a file descriptor
obtained from OPEN or CREAT. The mode of the stream
must agree with the mode of the open file.
FREOPEN(filename, mode, fp) is equivalent to FCLOSE(fp)
(if the stream is associated with an open file),
followed by FOPEN(filename, mode), except that the FOPEN
is constrained to reuse the given stream pointer fp.
That is, the stream is closed if it is open, then the
given file is opened and associated with the given
stream.
Page 37
fopen, fdopen, freopen
SEE ALSO
open, fclose
DIAGNOSTICS
FOPEN returns the pointer value NULL if filename cannot
be accessed. FDOPEN returns NULL if there are no more
stream pointers available. FREOPEN returns fp for
success, NULL for failure (in which case any previous
file associated with fp has been closed).
Page 38
fputc, putc, putchar, fputw, putw
fputc, putc, putchar, fputw, putw: put a character or word
on a stream
SYNOPSIS
#include <stdio.h>
int fputc(ch, stream)
char ch;
FILE *stream;
int putc(ch, stream)
char ch;
FILE *stream;
int putchar(ch)
char ch;
int fputw(i, stream)
int i;
FILE *stream;
int putw(i)
int i;
DESCRIPTION
FPUTC appends the character ch to the named output
stream. It returns the character written.
PUTC behaves like FPUTC, but it is a macro, not a
function. As such, it can cause side effects associated
with its arguments (e.g., post-incrementing) to occur
more than once.
PUTCHAR(ch) is equivalent to PUTC(ch, stdout).
FPUTW appends word (integer) i to the output stream. It
returns the word written. It neither assumes nor causes
any special alignment in the associated file.
PUTW(i) is equivalent to FPUTW(i, stdout).
The standard stream stdout is normally buffered if and
only if the output does not refer to a terminal; this
default may be changed by SETBUF. The standard stream
stderr is by default unbuffered unconditionally, this
again can be changed by SETBUF. When an output stream
is unbuffered information appears on the destination
file or terminal as soon as it is written; when it is
buffered many characters are saved up and written as a
block. FFLUSH can be used to force the block out early.
Page 39
fputc, putc, putchar, fputw, putw
SEE ALSO
fopen, fclose, getc, puts, printf
DIAGNOSTICS
These functions return the constant EOF upon error.
Since this is a valid integer, FERROR should be used to
detect FPUTW and PUTW errors.
BUGS
If an output stream is buffered, errors associated with
the file to which it is can occur long after a call to
one of these functions.
FPUTW and PUTW do not, at the present, work properly;
the reason being that seven-bit characters do not fit
properly in 36-bit words, and both routines do character
output.
Page 40
fputs, puts
fputs, puts: put a string on a stream
SYNOPSIS
#include <stdio.h>
int fputs(s, stream)
char *s;
FILE *stream;
int puts(s)
char *s;
DESCRIPTION
FPUTS copies the null-terminated string s to the named
output stream.
PUTS(s) is equivalent to FPUTS(s, stdout).
Neither routine copies the terminal null character.
SEE ALSO
fopen, gets, putc, printf, ferror
BUGS
If an output stream is buffered, errors associated with
the file to which it is connected to can occur long
after the call to one of these functions.
Page 41
fread, fwrite
fread, fwrite: buffered block input/output
SYNOPSIS
#include <stdio.h>
int fread(buf, sizeof(*buf), count, stream)
int count;
FILE *stream;
int fwrite(buf, sizeof(*buf), count, stream)
int count;
FILE *stream;
DESCRIPTION
FREAD reads, into a block beginning at buf, count items
of data of the size of *buf from the named input stream.
It returns the number of items actually read. This
function cannot be used to read words, since it does
character input. Although five characters fit in a
word, they do not do so evenly.
If the stream is stdin and the standard output is line
buffered, then any partial output will be flushed before
any call to READ to satisfy the FREAD.
FWRITE appends at most count items of data of the size
of *buf beginning at buf to the named output stream. It
returns the number of items actually written. This
function cannot be used to write words, since it does
character output. Although five characters fit in a
word, they do not do so evenly.
SEE ALSO
read, write, fopen, getc, gets, scanf, putc, puts,
printf
DIAGNOSTICS
It generally indicates an error if either function
returns a number other than the requested count; use
FEOF and/or FERROR to be sure.
Page 42
fseek, ftell, rewind
fseek, ftell, rewind: reposition a stream
SYNOPSIS
#include <stdio.h>
int fseek(stream, offset, origin)
FILE *stream;
long offset;
int origin;
long ftell(stream)
FILE *stream;
int rewind(stream)
FILE *stream;
DESCRIPTION
FSEEK sets the position of the next input or output
operation on stream. The new position is at the signed
distance offset bytes from the beginning, the current
position, or the end of the file, according as origin
has the value 0, 1, or 2.
FSEEK undoes the effects of UNGETC.
FTELL returns the current value of the offset relative
to the beginning of the file associated with the named
stream. It is measured in bytes (first byte numbered 0)
on the DEC-20.
REWIND(stream) is equivalent to
FSEEK(stream, (long) 0, 0).
SEE ALSO
lseek, fopen
DIAGNOSTICS
FSEEK returns -1 for improper seeks.
Page 43
gtjfn.h
gtjfn.h: long-form GTJFN% JSYS argument table
SYNOPSIS
#include <gtjfn.h>
DESCRIPTION
<Gtjfn.h> is an #include file which defines a typedef'ed
structure for a long-form GTJFN% JSYS argument table,
and #define's all of the various named offsets and bits
for such a table. In combination with the TOPS-20
-------
Monitor Calls Reference Manual, it is self-documenting.
------- ----- --------- ------
SEE ALSO
TOPS-20 Monitor Calls Reference Manual, comnd.h
------- ------- ----- --------- ------
(csb_setup, etc.), _getjfn, _reljfn
Page 44
_getjfn, _open, __open
_getjfn, _open, __open: lowest-level file opening
SYNOPSIS
int _getjfn(file, new, defname, defext, prot, is_temp)
char *file;
int new;
char *defname;
char *defext;
int prot;
int is_temp;
int __open(fildes, access, bsize)
int fildes;
int access;
int bsize;
int _open(file, access, bsize, defname, defext, pmode,
new, is_temp)
char *file;
int access;
int bsize;
char *defname;
char *defext;
int pmode;
int new;
int is_temp;
DESCRIPTION
_Getjfn gets a jfn (file descriptor) for the named file,
which may either be a non-existent file (new == TRUE) or
an existing one (new == FALSE). Defname and defext are
strings containing the default filename and extension,
respectively, for use when the given file name does not
specify them. Prot, if non-zero, is the default
protection for the file when none is specified. If prot
is passed as zero, the default protection will be that
of the next-lowest generation of the file, or that
specified by the directory. Is_temp should be TRUE if
it is desired that the returned jfn be for a temporary
file, otherwise it should be false.
__Open opens the given jfn (file descriptor). Access
gives the desired access to the file; bit 32 (octal
010) on specifies that read access is desired, bit 33
(octal 04) on specifies that write access is desired,
bit 34 (octal 02) on specifies that execute access is
desired, and bit 35 (octal 01) on specifies that append
access is desired. Bsize gives the byte size (1 through
36, 0 also means 36) at which to open the file.
_Open(file, access, bsize, defname, defext, pmode, new,
is_temp) is equivalent to
Page 45
_getjfn, _open, __open
__open(_getjfn(file, defname, defext, pmode, new,
is_temp), access, bsize).
SEE ALSO
open, close, _close, _reljfn
DIAGNOSTICS
_Getjfn returns -1 for failure, otherwise a jfn. __Open
returns TRUE for success, FALSE for failure. _Open
returns -1 for failure, otherwise a jfn.
Page 46
g_prargs
g_prargs: get process storage block entry
SYNOPSIS
g_prargs(flag_string, buffer)
char *flag_string;
char *buffer;
DESCRIPTION
G_prargs looks in the current process' process storage
block for an argument block whose label (sixbit left
half of first word) is the given flag_string. If it
finds such an argument block, it puts the ascii argument
in the given buffer (null-terminated) and returns TRUE.
Otherwise, the buffer is unmodified, and g_prargs
returns FALSE.
SEE ALSO
_st_fl
Page 47
index, rindex
index, rindex: finding characters in strings
SYNOPSIS
int index(s, ch)
char *s;
char ch;
int rindex(s, ch)
char *s;
char ch;
DESCRIPTION
INDEX (RINDEX) returns a pointer to the first (last)
occurrence of character ch in string s, or the NULL
pointer (zero) if ch does not occur in s. INDEX
(RINDEX) is identical to STRCHR (STRRCHR).
SEE ALSO
strchr, strrchr
Page 48
intrpt
intrpt: cause a programmable software interrupt system
interrupt
SYNOPSIS
int intrpt(fork, channel)
int fork;
int channel;
DESCRIPTION
Intrpt() causes an interrupt to be generated on the
given PSI system channel. Fork is the handle for the
process for to cause the interrupt (-1 for the calling
process), and channel (0 through 35) is the channel on
which the interrupt should occur.
DIAGNOSTICS
Intrpt() returns 0 for success, -1 for illegal channel
(not in the range zero through 35), otherwise a TOPS-20
error code.
SEE ALSO
Enapsi(), dispsi(), defsic(), enasic(), dissic(),
TOPS-20 Monitor Calls Reference Manual (section 2.6,
IIC%).
Page 49
isadsk, isatty
isadsk, isatty: help determine device type of a file
SYNOPSIS
int isadsk(fildes)
int fildes;
int isatty(fildes)
int fildes;
DESCRIPTION
ISADSK returns 1 if fildes is associated with a disk
device, 0 otherwise.
ISATTY returns 1 if fildes is associated with a terminal
device, 0 otherwise.
SEE ALSO
fileno
Page 50
itoa, _itoa
itoa, _itoa: convert numbers to strings
SYNOPSIS
int _itoa(buf, num, base, magnitude, sign_plus,
columns, lead_fill, fill_zero)
char *buf;
int num;
int base;
int magnitude;
int sign_plus;
int columns;
int lead_fill;
int fill_zero;
int itoa(num, buf)
int num;
char *buf;
DESCRIPTION
_ITOA converts the integer num to a string
representation and stores the result in the character
buffer buf.
Base is the base for the conversion (2 means binary, 8
means octal, etc.). If magnitude is TRUE, the number is
treated as if it were unsigned (in any base); otherwise
it is treated as if it were signed. If signed
conversion is requested, a '-' is prepended to all
negative converted numbers. If sign_plus is TRUE, a '+'
is prepended to converted positive numbers; otherwise
converted positive numbers have no sign.
Columns is the minimum number of columns into which the
converted number is printed; the routine will print
more than this many columns if the converted number
requires it. If lead_fill is TRUE, the number is
printed right-justified in the given number of columns,
and any unused columns on the left can be filled with
spaces (fill_zero == FALSE) or zeros (fill_zero ==
TRUE). If lead_fill is FALSE, the number is printed
left-justified in the given number of columns, and any
unused columns on the right are filled with spaces. No
filling takes place if the converted number requires the
same or greater number of printed positions than were
passed in the columns argument.
Itoa(num, buf) is the same as _itoa(buf, num, 10, FALSE,
FALSE, 0, FALSE, FALSE)
Both routines append a null character to the converted
string, and both return the length of the converted
string.
Page 51
itoa, _itoa
Neither _ITOA nor ITOA checks for overflow of the target
buffer.
SEE ALSO
atoi, sprintf
Page 52
_jsys
_jsys: do an arbitrary JSYS (system call)
SYNOPSIS
#include <jsys.h>
int _jsys(jsys_num, ac1_addr, ac2_addr, ac3_addr, ac4_addr)
int jsys_num;
int *ac1_addr, *ac2_addr, *ac3_addr, *ac4_addr;
DESCRIPTION
_JSYS performs an arbitrary JSYS (TOPS-20 system call),
where jsys_num is the number of the JSYS to perform (see
the TOPS-20 Monitor Calls Reference Manual or
------- ------- ----- --------- ------
equivalent). Ac1_addr through ac4_addr are the
addresses of the words (integers) whose contents are to
be placed in accumulators 1 through 4 before the JSYS is
performed, and which will receive the contents of
accumulators 1 through 4 after the JSYS finishes. The
constant NULL can be passed for any of these addresses,
in which case the corresponding accumulator is not set
to any value before the JSYS, and the contents of said
accumulator are not available after the JSYS.
<Jsys.h> #define's all of the JSYS codes; the code for
any given JSYS is defined as the uppercased JSYS name
(exactly as given in the TOPS-20 Monitor Calls Reference
------- ------- ----- ---------
Manual) followed by a '_' (underbar). An example (taken
------
directly from <jsys.h>) is:
#define PSOUT_ 076
<Jsys.h> also #define's several common constants used
with JSYS's, such as _PRIIN. Look through <jsys.h> to
see what is available.
DIAGNOSTICS
If an error return is taken by the JSYS, this function
determines and returns the DEC-20 error code (which can
be found in the TOPS-20 Monitor Calls Reference Manual)
------- ------- ----- --------- ------
which describes the error that occurred.
Page 53
lseek
lseek: move read/write pointer
SYNOPSIS
long lseek(fildes, offset, origin)
int fildes;
long offset;
int origin;
DESCRIPTION
LSEEK sets the position of the next input or output
operation on the file associated with fildes. The new
position is at the signed distance offset bytes from the
beginning, the current position, or the end of the file,
according as origin has the value 0, 1, or 2.
The returned value is the resulting pointer location.
SEE ALSO
open, creat, fseek
DIAGNOSTICS
-1 is returned upon any error (undefined file
descriptor, improper seek offset and/or origin, etc.).
Page 54
malloc, calloc, realloc, free, cfree
malloc, calloc, realloc, free, cfree: dynamic memory
allocation
SYNOPSIS
char *malloc(size)
int size;
char *calloc(num, size)
int num;
int size;
char *realloc(blk, size)
char *blk;
int size;
int free(blk)
char *blk;
int cfree(blk)
char *blk;
DESCRIPTION
MALLOC and FREE provide a simple general-purpose memory
allocation package. MALLOC returns a pointer to a block
at least size bytes big beginning on a word boundary.
The argument to FREE is a pointer to a block previously
allocated by MALLOC; this space is made available for
further allocation, but its contents are left
undisturbed.
Needless to say, grave disorder will result if the space
assigned by MALLOC is overrun or if some random number
is handed to FREE.
MALLOC allocates the first big-enough reach of
contiguous free space found in a circular search from
the last block allocated or freed, coalescing adjacent
free blocks as it searches. It obtains more memory from
the system when there is no suitable space already free.
REALLOC changes the size of the block pointed to by blk
to size bytes and returns a pointer to the (possibly
moved) block. The contents will be unchanged up to the
lesser of the new and old sizes. REALLOC also works if
blk points to a block freed since the last call to
MALLOC, REALLOC, or CALLOC; thus sequences of FREE,
MALLOC, and REALLOC can exploit the search strategy of
MALLOC to do storage compaction.
CALLOC allocates space for an array of num elements of
size size, which space is initialized to zeros.
Page 55
malloc, calloc, realloc, free, cfree
CFREE is equivalent to FREE.
Each of the allocation routines returns a pointer to
space suitably aligned (after possible pointer coercion)
for storage of any type of object.
DIAGNOSTICS
MALLOC, REALLOC, and CALLOC return a NULL pointer (0) if
there is no available memory or if the arena has been
detectably corrupted by storing outside the bounds of a
block. MALLOC may be recompiled to check the arena very
stringently on every transaction; see the source code.
BUGS
When REALLOC returns NULL (0), the block pointed to by
blk may have been destroyed.
The current incarnation of the allocator is unsuitable
for direct use in a large virtual environment where many
small blocks are to be kept, since it keeps all
allocated and freed blocks on a single circular list.
Just before more memory is obtained from the operating
system, all allocated and freed blocks are referenced;
this can cause a huge number of page faults.
Page 56
mbyt_pointer
mbyt_pointer: make a magic DEC-20 byte pointer
SYNOPSIS
int mbyt_pointer(size, location, address)
int size;
int location;
int address;
DESCRIPTION
MBYT_POINTER builds a magic DEC-20 byte pointer to a
byte of the given size, at the given location in the
word at the given address.
The size may range from 1 through 36.
The location specifies the byte number (within the word)
of the byte to which the returned byte pointer should
point, and may range from -1 (to specify the byte
preceding the first one at the given address) through 1
less than the number of bytes of the given size that can
fit in a word. Thus, for example, for 7-bit bytes
location can be any of -1, 0, 1, 2, 3, 4.
DIAGNOSTICS
Returns -1 for unreasonable size (less than 1 or greater
then 36) or unreasonable location.
Page 57
open
open: open a file
SYNOPSIS
int open(name, mode)
char *name;
int mode;
DESCRIPTION
OPEN opens the file name for reading (if mode is 0),
writing (if mode is 1), or for both reading and writing
(if mode is 2). Name points to a null-terminated string
containing a filename.
The file is positioned at the beginning (byte 0). The
returned file descriptor must be used for subsequent
calls for other input-output functions on the file.
SEE ALSO
creat, read, write, close, fopen
DIAGNOSTICS
The value -1 is returned if the file cannot be found or
is inaccessible in the given mode.
Page 58
perror, serror, gerrstring, _error, _warn
perror, serror, gerrstring, _error, _warn: exception
handling
SYNOPSIS
int perror(msg)
char *msg;
int serror(msg, ecode)
char *msg;
int ecode;
int g_errstring(buffer, ecode)
char *buffer;
int ecode;
int _error(msg)
char *msg;
int _warn(msg)
char *msg;
DESCRIPTION
PERROR prints the string "msg: errorstring\n" on the
terminal, where "errorstring" is the error message
corresponding to the last error that occurred in the
program.
SERROR is the same as PERROR, except that the
"errorstring" is the one corresponding to the given
TOPS-20 error code (give -1 to get the most recent
error).
G_ERRSTRING fills in the given buffer with the
"errorstring" corresponding to the given TOPS-20 error
code (give -1 to get the most recent error). It does
not check for overflow of the buffer.
The first time _ERROR is called, it prints msg on the
terminal, then tries to EXIT from the program. The
second and all succeeding times it is called, it just
tries to _EXIT.
_WARN prints msg on the terminal and returns (it does
not exit the program).
SEE ALSO
exit
Page 59
printf, fprintf, sprintf
printf, fprintf, sprintf: formatted output conversion
SYNOPSIS
#include <stdio.h>
printf(format [, arg ] )
char *format;
int fprintf(stream, format [, arg ] )
FILE *stream;
char *format;
int sprintf(s, format [, arg ] )
char *s;
char *format;
DESCRIPTION
PRINTF places output on the standard output stream
stdout. FPRINTF places output on the named output
stream. SPRINTF places "output" into the string s, with
a null character appended.
Each of these functions converts, formats, and prints
its args under the control of the given format, which is
a character string containing two types of objects:
plain characters, which are simply copied to the output
stream, and conversion specifications, each of which
causes conversion and printing of the next successive
arg.
Each conversion specification is introduced by the
character '%'. Following the '%', there may be:
o an optional minus sign '-', which specifies left
adjustment of the converted value in the indicated
field;
o an optional digit string specifying a field width;
if the converted value has fewer characters than
the field width it will be blank-padded on the
right (or the left, if the left-adjustment
indicator has been given) to make up the field
width; if the field width begins with a zero,
zero-padding will be done instead of
blank-padding;
o an optional period '.', which serves to separate
the field width from the next digit string;
o an optional digit string specifying a precision
which tells the maximum number of characters to be
printed from a string;
Page 60
printf, fprintf, sprintf
o the character 'l' (or 'L'), specifying that a
following 'd', 'o', 'x', or 'u' corresponds to a
long integer arg instead of an integer one;
o a character which specifies the type of conversion
to be done.
The conversion characters and their meanings are:
dox The integer arg is converted to decimal, octal, or
hexadecimal notation, respectively.
c The character arg is printed.
s Arg is taken to be a string (character pointer),
and characters from the string are printed until a
null character is found or the number of
characters indicated by the precision
specification is reached; if the precision
specification is zero or missing then all
characters up to a null are printed.
u The unsigned integer arg is converted to decimal
(unsigned) and printed.
% A '%' is printed; no argument is converted.
In no case does a non-existent or small field width
cause trucation of a field; padding takes place only if
the specified field width exceeds the actual width.
Characters generated by PRINTF are printed by PUTC.
SEE ALSO
itoa, putc, scanf
Page 61
read
read: read from a file
SYNOPSIS
int read(fildes, buf, count)
int fildes;
char *buf;
int count;
DESCRIPTION
READ causes at most count characters to be taken from
the file associated with fildes and placed in buffer (no
terminating null character is appended to the characters
read). The number of characters read is returned; zero
is returned if no characters remain in the file.
Several events can cause READ to read fewer characters
than were specified; among them are reaching
end-of-file and (eventually, but not at present) reading
a newline character when the file is a terminal.
READ does not check for overflow of buf.
SEE ALSO
open, write
DIAGNOSTICS
As mentioned, zero is returned if the file pointer is at
the end of the file. -1 is returned for a variety of
file errors.
Page 62
_reljfn, _close
_reljfn, _close: lowest-level file closing
SYNOPSIS
int _reljfn(jfn)
int jfn;
int _close(jfn, do_expunge)
int jfn;
int do_expunge;
DESCRIPTION
_Reljfn releases the given jfn (file descriptor).
_Close closes the given jfn (file descriptor), and
optionally (if do_expunge is TRUE) expunges the
associated file.
Close(fildes) is equivalent to _close(fildes, FALSE).
SEE ALSO
open, close, _getjfn, __open, _open
DIAGNOSTICS
Both routines return 0 for success, and a TOPS-20 error
code for failure.
Page 63
scanf, fscanf, sscanf
scanf, fscanf, sscanf: formatted input conversion
SYNOPSIS
#include <stdio.h>
int scanf(format [, pointer ] )
char *format;
int fscanf(stream, format [, pointer ] )
FILE *stream;
char *format;
int sscanf(s, format [, pointer ] )
char *s;
char *format;
DESCRIPTION
SCANF reads from the standard input stream stdin.
FSCANF reads from the named stream. SSCANF "reads" from
the string pointed to by s. Each function reads
characters, interprets them according to the format, and
stores the results in the objects pointed to by its
pointer arguments.
The control string usually contains conversion
specifications, which are used to direct interpretation
of input sequences. The control string may contain:
o Blanks, tabs, or newlines, which match optional
white space in the input.
o An ordinary character (not '%'), which must match
the next character of the input stream.
o Conversion specifications, consisting of the
character '%', an optional assignment suppression
character '*', an optional numerical maximum field
width, and a conversion character.
A conversion specification directs the conversion of the
next input field; the result is placed in the variable
pointed to by the corresponding argument, unless
assignment suppression was indicated by '*'. An input
field is defined as a string of non-space characters;
it extends to the next inappropriate character or until
the field width, if specified, is exhausted.
The conversion character indicates the interpretation of
the input field; the corresponding pointer argument
must usually be of a restricted type. The following
conversion characters are legal:
Page 64
scanf, fscanf, sscanf
dox a decimal, octal, or hexadecimal integer is
expected, respectively; the corresponding
argument should be an integer pointer.
c a character is expected; the corresponding
argument should be a character pointer. The
normal skip over white space characters is
suppressed in this case; to read the next
non-white character, use "%1s". If a field width
is given, the corresponding argument should refer
to a character array, and the indicated number of
characters is read.
s a character string is expected; the corresponding
argument should be a character pointer pointing to
an array of characters large enough to accept the
string and a terminating null, which will be
added. The input field is terminated by a white
space character.
[ indicates a string not to be delimited by white
space characters. The left bracket is followed by
a set of characters and a right bracket; the
characters between the brackets define a set of
characters making up the string. If the first
character is not circumflex '^', the input field
is all characters up to the first character not in
the bracketed set; if the first character after
the left bracket is '^', the input field is all
characters up to the first character in the
bracketed set (not counting the initial '^'). The
corresponding argument must point to a character
array.
% a single '%' is expected in the input at this
point; no assignment is done.
The conversion characters 'd', 'o', and 'x' may be
preceded by 'l' ('h') to indicate that a pointer to a
long (short) integer, rather than to an integer, is the
corresponding argument.
The SCANF functions return the number of successfully
matched and assigned input items. This can be used to
decide how many input items were found. The constant
EOF is returned upon end-of-input; note that this is
different from zero, which means that no conversion was
done; if conversion was intended, it was frustrated by
an inappropriate character in the input.
Page 65
scanf, fscanf, sscanf
SEE ALSO
atoi, getc, printf
Page 66
setbuf
setbuf: assign buffering to a stream
SYNOPSIS
#include <stdio.h>
int setbuf(stream, buf)
FILE *stream;
char *buf;
DESCRIPTION
SETBUF is used after a stream has been opened but before
it is read or written. It causes the character array
buf to be used instead of an automatically allocated
buffer. If buf is the constant pointer NULL, input
and/or output will be completely unbuffered.
A manifest constant BUFSIZ (#define'd in <stdio.h>)
tells how big an array is needed:
char buf[BUFSIZ];
A buffer is normally obtained from MALLOC upon the first
GETC or PUTC on the file, except that the standard
output stream stdout is line buffered when it is
directed to a terminal. Other output streams directed
to terminals, and the standard error stream stderr, are
normally not buffered. If the stdout is line buffered,
then it is flushed each time data is read from stdin by
GETC.
SEE ALSO
fopen, getc, putc, malloc
Page 67
stdio
stdio: standard buffered input/output package
SYNOPSIS
#include <stdio.h>
FILE *stdin;
FILE *stdout;
FILE *stderr;
DESCRIPTION
The functions of the standard input/output package
constitute an efficient user-level buffering scheme.
The in-line macros GETC and PUTC handle characters
quickly. The higher-level routines (F)GETS, FREAD,
(F,S)SCANF, (F)PUTS, FWRITE, and (F,S)PRINTF all use
GETC and PUTC; they can be freely intermixed.
A file with associated buffering is called a stream, and
is declared to be a pointer to a defined type FILE.
FOPEN creates certain descriptive data for a stream and
returns a pointer to designate the stream in all further
transactions. There are three normally-open streams
with constant pointers declared in the include file and
associated with the standard open files:
stdin standard input file
stdout standard output file
stderr standard error file
A constant "pointer" NULL (0) designates no stream at
all.
An integer constant EOF (-1) is returned upon
end-of-file or error by integer functions that deal with
streams.
Any routines that uses the standard input/output package
must include the header file <stdio.h> of pertinent
macro definitions. The functions and constants
mentioned in the sections of this document describing
the various functions are declared in the header file
and need no further declaration. The constants and the
functions GETC, GETCHAR, PUTC, PUTCHAR, FEOF, FERROR,
and FILENO are implemented as macros; redeclaration of
these names is perilous.
SEE ALSO
fopen, getc, fread, printf, putc, fwrite, scanf, open,
read, write
Page 68
stdio
DIAGNOSTICS
The value EOF is returned uniformly to indicate that a
FILE pointer has not been initialized with FOPEN, input
(output) has been attempted on an output (input) stream,
or a FILE pointer designates corrupt or otherwise
unintelligible FILE data.
For purposes of efficiency, this implementation line
buffers output to a terminal by default and attempts to
do so transparently by flushing the output whenever a
READ from the standard input is necessary. This almost
always works, but may cause confusion or malfunctioning
of programs which use standard i/o routines, but use
READ themselves to read from the standard input.
In cases where a large amount of computation is done
after printing part of a line on an output terminal, it
may be necessary to FFLUSH stdout before going off and
computing so that the output will appear.
Page 69
_st_fl
_st_fl: how did this program start running?
SYNOPSIS
extern int _st_fl;
DESCRIPTION
_St_fl is an integer variable in the standard library
whose value is zero if the program was started at it
REENTER address, and non-zero if it was started at its
START address.
SEE ALSO
g_prargs
Page 70
strlen, strcpy, strucpy, strcat, strcmp, strucmp, strchr, strrchr
strlen, strcpy, strucpy, strcat, strcmp, strucmp, strchr,
strrchr: string operations
SYNOPSIS
int strlen(s)
char *s;
int strcpy(s, t)
char *s;
char *t;
int strucpy(s, t)
char *s;
char *t;
int strcat(s, t)
char *s;
char *t;
int strcmp(s, t)
char *s;
char *t;
int strucmp(s, t)
char *s;
char *t;
int strchr(s, ch)
char *s;
char ch;
int strrchr(s, ch)
char *s;
char ch;
DESCRIPTION
These functions operate on null-terminated strings.
They do not check for overflow of any receiving string.
STRLEN returns the number of characters before the first
null in s.
STRCPY copies string t to string s, stopping after the
null terminating character has been moved, and returns
s.
STRUCPY behaves exactly like STRCPY, except that it
uppercases lowercase letters as it copies (yes, you can
give the same string as both the source and the target;
the effect is to uppercase the string in place).
STRCAT appends a copy of string t to the end of string
s, and returns s.
Page 71
strlen, strcpy, strucpy, strcat, strcmp, strucmp, strchr, strrchr
STRCMP compares its arguments and returns an integer
greater than, equal to, or less than zero, according as
s is lexicographically less than, equal to, or greater
than t.
STRUCMP behaves excatly like STRCMP, except that the
strings are compared without regard for the case of
letters (i.e., 'A' == 'a').
STRCHR (STRRCHR) returns a pointer to the first (last)
occurrence of character ch in string s, or the NULL
pointer (zero) if ch does not occur in s. STRCHR
(STRRCHR) is identical to INDEX (RINDEX).
SEE ALSO
strncpy, strncat, strncmp, index, rindex
Page 72
strncpy, strncat, strncmp
strncpy, strncat, strncmp: size-limited string operations
SYNOPSIS
int strncpy(s, t, n)
char *s;
char *t;
int n;
int strncat(s, t, n)
char *s;
char *t;
int n;
int strncmp(s, t, n)
char *s;
char *t;
int n;
DESCRIPTION
These functions operate on null-terminated strings, and
are roughly equivalent to the functions strcpy, strcat,
and strcmp, respectively, except that their behavior may
be length-limited. They do not check for overflow of
any receiving string.
STRNCPY copies n characters to string s. If the length
of string t is less than n, then all of t, followed by
(n - length(t)) null characters, is copied to s. If the
length of t is greater than or equal to n, then exactly
n characters of t are copied to s. Note that s will not
be null-terminated unless the length of t is less than
n.
STRNCAT appends at most n characters from string t to
the end of string s, and returns s. If the length of t
is less than n, then all of t is appended to s. The new
string is null-terminated.
STRNCMP compares its arguments and returns an integer
greater than, equal to, or less than zero, according as
the first n characters of s are lexicographically less
than, equal to, or greater than the first n characters
of t. If either string has length less than n, then the
strings are only compared up to the end of the shorter
of the two.
SEE ALSO
strcpy, strcat, strcmp
BUGS
STRNCPY's failure to null-terminate the target string
when the length of the source string is greater than or
equal to the given length is a little weird; it is the
Page 73
strncpy, strncat, strncmp
only string-handling function which exhibits this
behavior.
Page 74
strspn, strcspn, strpbrk
strspn, strcspn, strpbrk: search for characters (not) in a
string
SYNOPSIS
int strspn(string, charset)
char *string;
char *charset;
int strcspn(string, charset)
char *string;
char *charset;
int strpbrk(string, charset)
char *string;
char *charset;
DESCRIPTION
These routines search the given string for a character
in or not in the given set of characters.
STRSPN counts the number of characters in the string
before the first occurence of a character not in the
given set; that is, it counts the number of leading
characters in the string which are in the given set. It
returns the count, which obviously can range from zero
through the length of the string.
STRCSPN is the complement of STRSPN; it counts the
number of characters in the string before the first
occurence of a character that is in the given set. It
returns the count.
STRPBRK returns a pointer to the position of the first
character in the given string which is also in the given
set; it returns NULL if no character in the string is
also in the set.
SEE ALSO
index, rindex
Page 75
tb.h, tb_build
tb.h, tb_build: access to TBxxx% JSYS table handling
SYNOPSIS
#include <tb.h>
int tb_build(comtab_addr, arg_blocks, curr_tab_size,
max_tab_size)
tb_comtab *comtab_addr;
tbb_entry arg_blocks[];
int curr_tab_size;
int max_tab_size;
DESCRIPTION
<Tb.h> and TB_BUILD provide access to the TOPS-20
table-handling capabilities (TBxxx% JSYS).
<Tb.h> provides a host of type and #define definitions
to be used in building and maintaining keyword tables.
A careful perusal of it, as well as a good reading of
the TBxxx% JSYS definitions in the TOPS-20 Monitor Calls
------- ------- -----
Reference Manual, is recommended before launching off
--------- ------
into this particular fog.
TB_BUILD builds a keyword table at comtab_addr with the
given current and maximum sizes, filling it in from the
table-building blocks in arg_blocks[]. The value given
as the current size should be the number of entries in
arg_blocks[]. The value given as the maximum size
should be this large or larger.
When the tbbe_flags field of a tbb_entry is zero, the
keyword string in tbbe_string should be exactly what is
desired for the keyword; when tbbe_flags is non-zero,
the keyword string in tbbe_string must begin with five
spaces (which is one word), followed by the desired
keyword. In the second case, TB_BUILD uses that word
(the five spaces) as the flags word, and automatically
turns on CM_FW in it; if the first word is not five
spaces, it still uses the word and builds the remainder
of the table, but will return TBB_OVERWRITE instead of
TBB_SUCCESS.
If a keyword table is being built for use by COMND% JSYS
and the CM_ABR bit is turned on in the flags for some
entry, the user must set the abbreviation address
herself. This is the right half of the keyword table
entry for the abbreviation, which is the address of the
entry for which this one is an abbreviation. As an
example, if one had a keyword table called key_table, in
which the keyword whose table index was A_KW_INDEX was
an abbreviation for the keyword whose table index was
Page 76
tb.h, tb_build
ABC_KW_INDEX, the following statement could be used to
set the abbreviation pointer in the table:
key_table.tbc_entry[A_KW_INDEX] |=
((int) &(key_table.tbc_entry[ABC_KW_INDEX]))
& 0777777;
This is the most straightforward way to set an
abbreviation pointer. It can be done either before or
after calling TB_BUILD to build the table, because
TB_BUILD only modifies the left halfword of each table
entry to point to the appropriate keyword, and the above
statement only modifies the right halfword to contain
the abbreviation pointer.
The strings pointed to by the tbbe_string fields of
arg_blocks[] should be static and should begin at word
boundaries (this will be true if they are string
constants or array contents), because the table built in
comtab_addr will point directly at these original
strings (they are not copied anywhere else). For the
same reason, the space occupied by the strings should
not be modified after the table is built. Note that the
strings should also not occupy automatic (stack) space,
since if the function owning the space return()'s, the
strings will be lost.
The keyword strings in arg_blocks[] MUST be in
alphabetic order (disregarding letter case and any
leading groups of five spaces for flags); TB_BUILD
checks this, and returns TBB_UNSORTED if the strings are
not in ascending order. If TB_BUILD has the option of
returning either TBB_OVERWRITE or TBB_UNSORTED, it will
return TBB_OVERWRITE on the supposition that the keyword
strings would have been in sorted order if the keywords
which had their first five characters overwritten with
flags had begun with five blanks. The check for
ordering of strings is done without regard for the case
of letters in the strings.
The case of letters in a TBxxx% table is insignificant,
with the associated advantages and disadvantages.
SEE ALSO
TOPS-20 Monitor Calls Reference Manual, comnd.h,
------- ------- ----- --------- ------
_csb_setup, _flddb, _comnd, _com_graph
DIAGNOSTICS
TB_BUILD returns
TBB_SUCCESS (0) if the table was built successfully;
TBB_BADSIZ (-1) if the given table sizes were
somehow illogical (e.g., current size greater
Page 77
tb.h, tb_build
than maximum);
TBB_OVERWRITE (1) if some keyword's flags overwrote
nontrivial (non-space) characters in that
keyword's text;
TBB_UNSORTED (2) if the keyword strings were not in
ascending order.
All four of these return values are #define'd in <tb.h>.
BUGS
We need a TB_ADD and a TB_DEL; neither should be
particularly difficult to write.
Page 78
_trace
_trace: control runtime function tracing
SYNOPSIS
int _trace(code, stream)
int code;
FILE *stream;
DESCRIPTION
_TRACE provides control over run-time reporting of
function entries and exits, in conjunction with the
/Traceable-code switch of the C compiler. _TRACE has no
effect in programs not compiled with /Traceable-code. A
program compiled with that switch has code inserted at
the beginning of each function and before each return()
to call library functions which keep track of the
dynamic call nesting level and report function entries
and exits.
_TRACE controls the behavior of call/return tracking and
reporting via the code argument. If code is zero, calls
and returns are not reported, and the call nesting level
is ignored.
If code is negative, trace reporting is still turned
off, but the call nesting level is kept track of.
A positive code has the same effect as a negative one,
except that each function entry and exit now causes a
line of the form
<indentation>[enter x with arguments d (o) ...]
or
<indentation>[exit x, returning d (o)]
respectively to be sent to the trace reporting stream,
where "x" is the name of the function being entered or
left, and "d" and "o" are the decimal and octal argument
and return values for the reported function. The
<indentation> reflects the call nesting level of the
functions traced. The "enter"'s and "exit"'s are
indented two spaces on each entry, and exdented two
spaces on each exit.
The function entry message may also look like
<indentation>[enter x with no arguments]
if the entered function was called without any
arguments, or like
<indentation>[enter x with unknown arguments]
Page 79
_trace
if the entered function was called by a function which
is in a module that was not compiled with
/Traceable-code.
Initially, the call nesting level is set to zero and
nesting is not kept track of, nor is reporting done.
The call nesting level is reset to zero whenever a call
to _TRACE with a non-zero code follows a call with code
equal to zero.
If a non-NULL stream argument is passed, it will be used
for subsequent trace reporting (it is recommended that
it be for an unbuffered (via SETBUF) stream). If no
non-NULL stream argument is ever passed, the standard
error stream stderr is used for trace reporting.
SEE ALSO
fopen, setbuf
Page 80
ungetc
ungetc: put a character back into an input stream
SYNOPSIS
#include <stdio.h>
ungetc(ch, stream);
int ch;
FILE *stream;
DESCRIPTION
UNGETC pushes the character ch back into the named input
stream (note that the argument ch is actually an int, as
returned by GETC). The character will be returned by
the next GETC call on that stream. UNGETC returns ch.
One character of pushback is guaranteed provided that
something has been read from the stream and that the
stream is buffered. Attempts to UNGETC EOF are
rejected.
FSEEK erases all memory of pushed-back characters.
SEE ALSO
getc, setbuf, fseek
DIAGNOSTICS
UNGETC returns EOF if it can't push a character back.
Page 81
unlink
unlink: delete a file
SYNOPSIS
int unlink(name)
char *name;
DESCRIPTION
Name points to a null-terminated string, which is the
name of the file to delete. UNLINK deletes the file,
but does not expunge it.
SEE ALSO
creat
DIAGNOSTICS
Normally, zero is returned. -1 is returned if the file
could not be deleted, the reasons for which being the
same things that can cause the TOPS-20 DELETE command to
fail.
Page 82
write
write: write to a file
SYNOPSIS
int write(fildes, buf, count)
int fildes;
char *buf;
int count;
DESCRIPTION
Fildes is a file descriptor, as returned by OPEN or
CREAT. Buf is the address of count bytes of contiguous
data, which are written on the output file. The number
of characters actually written is returned. It should
be regarded as an error if this is not the same as the
number requested to be written.
SEE ALSO
open, creat, read
DIAGNOSTICS
Returns -1 on error: bad descriptor, buffer address, or
count; physical i/o errors.
Page Index-1
INDEX TO FUNCTIONS
Abs . . . . . . . . . . . . 2
Adate . . . . . . . . . . . 21
Atoi . . . . . . . . . . . . 3
Atol . . . . . . . . . . . . 3
Ator50 . . . . . . . . . . . 4
Atosix . . . . . . . . . . . 4
Calloc . . . . . . . . . . . 54
Cfree . . . . . . . . . . . 54
Chdir . . . . . . . . . . . 5
Chmod . . . . . . . . . . . 6
Close . . . . . . . . . . . 7
Clrerr . . . . . . . . . . . 30
Comnd.h . . . . . . . . . . 8
Comnd_ . . . . . . . . . . . 8
Com_graph . . . . . . . . . 8
Cputime . . . . . . . . . . 21
Creat . . . . . . . . . . . 20
Csb_setup . . . . . . . . . 8
Date . . . . . . . . . . . . 21
Daytime . . . . . . . . . . 21
Defsic . . . . . . . . . . . 23
Dispsi . . . . . . . . . . . 25
Dissic . . . . . . . . . . . 26
Enapsi . . . . . . . . . . . 25
Enasic . . . . . . . . . . . 26
Execl . . . . . . . . . . . 27
Execs . . . . . . . . . . . 27
Exit . . . . . . . . . . . . 28
Fabs . . . . . . . . . . . . 2
Fclose . . . . . . . . . . . 29
Fdbc_setup . . . . . . . . . 8
Fdopen . . . . . . . . . . . 36
Feof . . . . . . . . . . . . 30
Ferror . . . . . . . . . . . 30
Fflush . . . . . . . . . . . 29
Fgetc . . . . . . . . . . . 31
Fgetname . . . . . . . . . . 33
Fgets . . . . . . . . . . . 32
Fgetw . . . . . . . . . . . 31
Fileno . . . . . . . . . . . 30
Filnam . . . . . . . . . . . 33
Filpcnt . . . . . . . . . . 35
Filpfree . . . . . . . . . . 35
Filpused . . . . . . . . . . 35
INDEX TO FUNCTIONS Page Index-2
Filsiz . . . . . . . . . . . 35
Flddb_ . . . . . . . . . . . 8
Fopen . . . . . . . . . . . 36
Fprintf . . . . . . . . . . 59
Fputc . . . . . . . . . . . 38
Fputs . . . . . . . . . . . 40
Fputw . . . . . . . . . . . 38
Fread . . . . . . . . . . . 41
Free . . . . . . . . . . . . 54
Freopen . . . . . . . . . . 36
Fscanf . . . . . . . . . . . 63
Fseek . . . . . . . . . . . 42
Ftell . . . . . . . . . . . 42
Fwrite . . . . . . . . . . . 41
Gerrstring . . . . . . . . . 58
Getc . . . . . . . . . . . . 31
Getchar . . . . . . . . . . 31
Getname . . . . . . . . . . 33
Gets . . . . . . . . . . . . 32
Getw . . . . . . . . . . . . 31
Gtjfn.h . . . . . . . . . . 43
G_prargs . . . . . . . . . . 46
Halt . . . . . . . . . . . . 28
Idate . . . . . . . . . . . 21
Index . . . . . . . . . . . 47
Intrpt . . . . . . . . . . . 48
Isadsk . . . . . . . . . . . 49
Isatty . . . . . . . . . . . 49
Itoa . . . . . . . . . . . . 50
Lseek . . . . . . . . . . . 53
Malloc . . . . . . . . . . . 54
Mbyt_pointer . . . . . . . . 56
Open . . . . . . . . . . . . 57
Perror . . . . . . . . . . . 58
Printf . . . . . . . . . . . 59
Putc . . . . . . . . . . . . 38
Putchar . . . . . . . . . . 38
Puts . . . . . . . . . . . . 40
Putw . . . . . . . . . . . . 38
R50toa . . . . . . . . . . . 4
Read . . . . . . . . . . . . 61
Realloc . . . . . . . . . . 54
Rewind . . . . . . . . . . . 42
Rindex . . . . . . . . . . . 47
Scanf . . . . . . . . . . . 63
Serror . . . . . . . . . . . 58
Setbuf . . . . . . . . . . . 66
Sixtoa . . . . . . . . . . . 4
Sprintf . . . . . . . . . . 59
Sscanf . . . . . . . . . . . 63
Stdio . . . . . . . . . . . 67
Strcat . . . . . . . . . . . 70
Strchr . . . . . . . . . . . 70
Strcmp . . . . . . . . . . . 70
Strcpy . . . . . . . . . . . 70
Strcspn . . . . . . . . . . 74
Strlen . . . . . . . . . . . 70
Strncat . . . . . . . . . . 72
Strncmp . . . . . . . . . . 72
Strncpy . . . . . . . . . . 72
Strpbrk . . . . . . . . . . 74
Strrchr . . . . . . . . . . 70
Strspn . . . . . . . . . . . 74
Strucmp . . . . . . . . . . 70
Strucpy . . . . . . . . . . 70
Tb.h . . . . . . . . . . . . 75
Tb_build . . . . . . . . . . 75
Ungetc . . . . . . . . . . . 80
Unlink . . . . . . . . . . . 81
Walltime . . . . . . . . . . 21
Write . . . . . . . . . . . 82
_close . . . . . . . . . . . 62
_docall . . . . . . . . . . 24
_error . . . . . . . . . . . 58
_exit . . . . . . . . . . . 28
_getjfn . . . . . . . . . . 44
_itoa . . . . . . . . . . . 50
_jsys . . . . . . . . . . . 52
_open . . . . . . . . . . . 44
_reljfn . . . . . . . . . . 62
_st_fl . . . . . . . . . . . 69
_trace . . . . . . . . . . . 78
_warn . . . . . . . . . . . 58
__open . . . . . . . . . . . 44