DECUS C LANGUAGE SYSTEM
Compiler & Library
Software Support Manual
by
Martin Minow
Edited by
Robert B. Denny
This document describes the RSX/VMS/RSTS/RT11 DECUS
C
language
system
runtime
support library.
It also contains all
internal
functions
is
available.
and
such
compiler
internal
information
as
DECUS Structured Languages SIG
Version of 15-Oct-81
NOTE
This software is made available without any support
whatsoever.
The
person
responsible
for
an
implementation of this system should expect to have to
understand and modify the source code if any problems
are encountered in implementing or maintaining the
compiler or its run-time library. The DECUS 'Structured
Languages Special Interest Group' is the primary focus
for communication among users of this software.
UNIX is
a
trademark
RSTS/E,
RT11
of
Bell
Telephone
Laboratories.
RSX,
Equipment
Corporation.
and
VMS
are
trademarks
of
Digital
CHAPTER 1
INTRODUCTION
The C support library contains three major groups of functions:
o
Functions called by
the
compiler
to
perform
certain
mathematical operations (such as floating-point
multiply
or function entrance) that are not performed in-line.
o
Functions that may be called by C
programs
to
operations,
string, that are
perform
such
as
copying
a
more
efficiently performed
by
optimized
assembly
language
subroutines.
o
An implementation of (most of)
the
Unix
Standard
I/O
library.
The standard installation procedure yields two
documents.
The
Runtime
Support
Library
Reference Manual describes how to
use
the C library.
The Compiler and Library Software Support
Manual
contains
all
user documentation plus additional information
on
the internals of both the library and the C compiler.
is
the Software Support Manual.
This
CHAPTER 2
THE STANDARD LIBRARY
WARNING
This version of the library is somewhat incompatible
with previous versions of the Decus C compiler. This
incompatibility allows greater compatibility with Unix
Version 7, and the capability of generating global
references and definitions containing the radix-50 '$'
and '.' characters.
All C programs should
be
linked
together
with
the
run-
time
support
library.
On
systems
that
support
logical
device
descriptors, this will generally be stored in
the
C:
will
be
logical
device/account.
On
RSX-11M,
the
library
found
in
LB:[1,1].
To link a C program, proceed as follows:
RSX
TKB
TKB> task/CP,map=objects,LB:C/LB
TKB> /
ENTER OPTIONS:
TKB> STACK=2000
TKB> //
RT11
R LINK
*save,map=objects,C:SUPORT,C:CLIB/B:2000
*^C
Note that, on RSX-11M, the task should be built
checkpointable.
This is automatic on RSTS/E and VMS emulated modes. On
native
RSX-11M, the task-builder may be rebuilt with '/CP' as
the
default.
If the '/CP' switch is not given, the task may
abort
(no memory) when started.
Stack extension is needed
if
subroutines locally allocate large amounts of data.
On RT11, note that the '/B' (bottom) switch
must
be
given
to
increase
the
size
of
the
run-time stack.
This is needed
as
local variables are allocated on the stack.
size
If the
stack
C Compiler and Library
Page
2-2
Software Support Manual
is
not
increased,
the
program
may
abort
without any
error
message.
The
standard
I/O
interface
header
file
is
in
C:STDIO.H
(LB:[1,1]STDIO.H
on
native RSX-11M implementations) and
should
be included in all C programs as follows:
#include <stdio.h>
2.1 Introduction to Unix-style Stream I/O
____________ __ __________ ______ ___
This
section
presents
an
overview
of
the
'standard'
I/O
interface
for
C
programs.
These routines have proven easy
to
use and, while they do not provide the full functionality of
RSX
or
RMS,
they give the programer essentially all that is
needed
for everyday use.
The discussion includes the following:
- Opening and closing files
- Reading data from files
- Writing data to files
Note that this file system is
limited:
files
are
sequential
with
only
a limited amount of random-access capability.
Also,
little of the power of RMS/FCS is available.
On the other
hand,
the
limitations
make
C programs easily transportable to
other
operating systems.
When a C program is started,
three
files
and
opened:
stdin
stdout
The 'standard' input file
The 'standard' output file
are
predefined
stderr
The 'standard' error file
Stderr is always assigned to the command
terminal.
Stdin
and
stdout are normally assigned to the command terminal, but may
be
reassigned or closed when the program starts.
2.2
_______ _____
Opening and Closing Files
The fopen and fclose functions control access
_______ ___
to
files.
They
are normally used as follows:
#include <stdio.h>
/* Define standard I/O */
FILE
*ioptr;
/* Pointer to file area */
...
if ((ioptr = fopen("filename", "mode")) == NULL)
error("Can't open file");
C Compiler and Library
Page
2-3
Software Support Manual
All information about an open file is stored in a
buffer
whose
address is returned by fopen().
The buffer is
dynamically
allocated when the file is opened and deallocated when the
file
is closed. Its format is described under the heading IOV.
The
mode string contains flags defining how the file is to
be
accessed:
r
w
a
Read only
Write new file
Append to existing file (or write new)
(Doesn't work on RT11 modes).
It also defines some record-control information:
n
u
No newlines mode ('binary' files)
RSX: The user program allocates record buffers
RT11: Console output is done using .ttyout
If mode 'n' is specified, the RSX I/O routines do not
interpret
the
end
of
a
RMS
logical
record
as
defining the end of
a
human-readable line.
This
is
necessary
to
process
'binary'
information.
On
RT11,
the
I/O
routines
do
not
remove
carriage-returns
from
input
files,
nor
do
they
insert
carriage-returns when newlines are output.
Mode 'u' is treated differently on RSX and RT11.
If
specified
on RSX the user maintains the file's record buffer.
The
program
may only call the fget() and fput() routines.
Each
such
call
will
be
translated
directly
to an RMS/FCS GET$ or PUT$
call.
(In RT11 mode, fput() may be used to write binary records
which
are subsequently read by fget().
with
'n' mode.)
The file should be opened
If mode 'u' is specified on RT11 mode when opening
the
console
terminal,
single
character output will be performed (using
the
RT11 monitor routine .ttyout).
If not specified, output will
be
one
line
at
a
time
(using the monitor routine .print).
The
library initialization process opens
stderr
in
mode
'u'
and
stdout in normal mode.
This means that mixing I/O to both
units
will
result
in
synchronization
problems.
To
obtain
single-character
output
on
stdout,
the
program
need
simply
execute:
if (freopen("tt:", "wu", stdout) == NULL) error("");
The program calls fclose(ioptr) to
terminate
processing
on
a
file.
This
closes
the
file
and
reclaims system-
controlled
buffer space.
an
open file.
fmkdl(ioptr) may be called to close and delete
C Compiler and Library
Page
2-4
Software Support Manual
2.3
Reading Data from a File
_______ ____ ____ _
____
The simplest way to read a file is
to
call
the
getchar()
or
getc()
routines which read the next character from a file.
For
example, the following program counts the number
of
characters
in a file:
#include <stdio.h>
main()
{
register int
ccount;
register int
lcount;
register int
c;
FILE
*ioptr;
if ((ioptr = fopen("foo.bar", "r")) == NULL)
error("Cannot open file");
ccount = 0;
lcount = 0;
while ((c = getc(ioptr)) != EOF) {
ccount++;
if (c == '\n') lcount++;
}
printf("%d characters, %d lines.\n",
ccount, lcount);
}
Other input routines include:
gets
fgets
fgetss
ungetc
fseek
Read a line from the standard input
Read a line from a file
Read a line from a file, remove terminator
Push one character back on a file
Position the file to a specific record
These routines are used together
with
the
ferr()
functions
for
error
and
and
feof()
which
allow
testing
end
of
file
conditions, respectively.
The package assumes
error
conditions are lethal and force end of file.
that
all
2.4
Writing Data to a File
_______ ____ __ _
____
There are several routines for data output
which
are
directly
analagous to the data input routines:
putchar
putc
puts
fputs
fputss
ftell
Write a character to standard output
Write a character to a specified file
Write a string to the standard outpt
Write a string to a specified file
Write a record to a specified file
Return record location (for fseek)
In addition, the printf() or fprintf() routine is used to
format
C Compiler and Library
Page
2-5
Software Support Manual
and print data (as was shown in the previous example).
Printf()
is flexible, powerful, and easy to
use;
and
is
perhaps
the
single most important routine in the file system.
2.5 Interaction with the Operating System
___________ ____ ___ _________ ______
The support library attempts to provide a
consistant
operating
system
interface
on several implementations of quite
different
operating systems.
The possiblities include:
o
Native RT11
o
Native RSX-11M or IAS
o
RT11
o
RSX-11M emulated on RSTS/E
o
RSX-11M emulated on VAX/VMS
emulated on RSTS/E
This section mentions the inconsistencies and random
bugs
that
are more or less intentionally present.
2.5.1
Logical Unit Numbers
_______ ____
_______
RT11, RSTS/E, and RSX-11M use small integers to number
all
I/O
channels.
Unfortunately,
the
numbering is not consistent
and
channel usage differs
among
the
various
systems.
has
resulted in several quirks:
o
.ttyout
On RT11, console terminal interaction uses
the
This
and .print monitor functions.
While no device is
opened
by the fopen() function, a channel number is reserved.
o
On RSX-11M, a channel must be allocated to
the
console
terminal.
When
a
C
program
starts,
the
'command
terminal' is opened on logical unit 1
and
assigned
to
stderr.
This
is
not
done
using the fopen()
routine
(although the stderr IOV
structure
fopen()
Also,
is
defined
as
if
were
called).
fclose()
cannot
close
stderr.
In addition to the standard I/O routines, there are
two
routines,
msg()
and
regdmp(),
that
direct output
to
logical unit 1.
These routines were used to
debug
the
library,
and
are
otherwise
useful for disasters.
On
RT11,
msg()
monitor
function.
and
regdmp()
use
the
.print
C Compiler and Library
Page
2-6
Software Support Manual
o
On both systems, the first
true
files
are
stdin
and
stdout.
These
are
opened
on
logical
units 0 and
1
(RT11) or 2 and 3 (RSX).
Code in fclose() double-
checks
that
the
logical
unit number of the file being
closed
corresponds to the
proper
slot
in
the
logical
unit
table.
o
Since the standard I/O routines know
little
about
the
operating
system, they do not deal with certain
special
features.
For example, on RT11, the 'user service
routine'
(USR)
is
used
to open files.
The file open routine does
not
attempt to locate IOV areas so that
the
USR
does
not
swap
over
them.
This can be a problem for very
large
programs.
On RSX, logical unit numbers are
assigned
dynamically.
This
means
that
'LUN
assignment'
cannot be
reliably
performed
by
task-build
control
files
(or
task
initiation).
2.5.2
The
Wild-Card Files
fwild()
and
_________ _____
fnext()
routines
can
be
used
process
'wild-card' files.
On RSX-11M and VMS/RSX
extension,
emulation,
the
file
name,
to
and/or
file
version
may
be
expressed
as
'*'
to
indicate
wild-card support.
Due to restrictions in the
RSX-11
Files-
structure
the ' ', ';0' and ';-1' version numbers
11
(ODS1),
will
NOT function properly on native RSX-11.
This means that
'*.MAC'
will
not
work, for instance.
The algorithm in fwild()
depends
on the directory being sorted, as in
the
ODS2
file
structure
used
on
VAX/VMS.
If
you sort the directory to be used in
an
fwild() operation (use the SRD program available from DECUS
with
the
/WB
switch)
in
order of decreasing file version
numbers,
then the " ", ";0", and ";-1" versions will work.
Wild-card devices, units, or UIC codes are not supported.
Note
that,
on
RSX11
emulated
on VMS, the ';-1' (earliest
version)
requires special processing by the user program, as noted in
the
description of fwild().
On RSX-11M emulated on RSTS/E, the file
name
and/or
extension
may contain '*' or '?' wild-cards.
Wild-card devices, units,
or
UIC (PPN) codes are not supported.
On RT-11, the file name and/or extension may contain '*', '%'
or
'?'
wild
cards.
The
'?'
wild-card
is synonymous with
'%'.
Wild-card devices, or units are not supported.
card
Since
wild-
C Compiler and Library
Page
2-7
Software Support Manual
support is not an RT-11 system service, the file
specification
parsing and directory operations are handled by the C
library
fwild() and fnext() functions. The fwild/fnext module
requires
about 480 words of storage. Also, a file opened by wildcard
uses a 1024 byte buffer, twice the normal size, which is
shared
between data and directory operations.
2.5.3
Memory allocation
Memory is allocated
using
______ __________
the
malloc()
function.
It
works
correctly
on all operating systems, expanding memory on RSX
and
RT11/RSTS.
On 'native' RT11, all available memory is
allocated
by
invoking
the monitor .settop function with a '-2'
argument.
Neither library supports extended memory (PLAS) directives.
The sbreak() routine may be used
for
permanent
allocation
of
memory.
Once
memory
has
been
allocated
using sbreak(),
it
cannot be freed.
2.5.4
Global symbols
______ _______
Global symbols defined or referenced by
C
programs
may
cause
unexpected
parts
of the operating-system support library to
be
loaded,
with
undesirable
consequences.
There
are
several
aspects to this problem:
o
resolved
A symbol refered to by a C program which is not
by
the
object modules or libraries may cause some
part
of the system library to be loaded.
For example, if a
C
program
refers
to
the
sqrt()
function (which is
not
present in the standard library), the linker may
attempt
to
load
the
function from the Fortran library.
Since
the Fortran sqrt() function contains a reference to
the
Fortran run-time error message routine, the load map
may
contain many strange global symbols.
o
Another problem occurs when a C program defines a
global
symbol
that
duplicates a global in the system
library.
This may prevent loading
some
necessary
part
of
the
system library, causing the link to fail with
unresolved
global symbols.
For example,
on
RSX-11M
on
RSTS/E V7.0, the following will fail:
int eof;
main () {
}
/* Global
*/
emulated
CHAPTER 3
SUPPORT INFORMATION
The C system has been implemented on
VMS
V2.0,
RSX-11M
V3.2,
RSTS/E
V7.0, and RT11 V03B.
All installations should expect
to
have to modify the command procedures
to
suit
their
specific
needs.
While the compiler has been built from scratch on
RT11,
the procedures unrealistically assume
a
system
with
no
disk
storage
limitations.
The C system has not been tested on
IAS,
RSX11-D, RSX11M-PLUS, or HT11.
The C system is
distributed
on
9-track
magtape
in
'DOS-
11'
format.
The
full
distribution requires a 2400 foot (or
three
600 foot) tapes.
Please Note
This is a DECUS 'product';
there is no
support
available from the authors. The person responsible for
an implementation of this system should expect to have
to understand and modify the source code if any problems
are encountered in implementing or maintaining the
compiler or its run-time library. The DECUS 'Structured
Languages Special Interest Group' is the primary focus
for communication among users of this software.
This section
the
contains
information
on
the
internals
of
compiler,
assembler,
and
run-time
libraries.
It
is
not
complete;
3.1
it is probably not accurate either.
The C Compiler
___ _ ________
The compiler source is distributed on account [5,3].
There
are
four groups of files in this account:
o
The C compiler source is
in
modules
named
CC???.MAC.
The
root
code
is
in CC0RT.MAC, while overlays are
in
CC00?.MAC, CC10?, CC20?, and CC3??.
have
the following functions:
The
overlays
C Compiler and Library
Page
3-2
Software Support Manual
0. Pass 0
reads
the
input
source
file,
writing
a
temporary
file
after processing #define,
#include,
and #ifdef statements.
1. Pass 1 reads the expanded source
file,
parses
the
language and writes an 'intermediate code' file.
In
the
intermediate
file
all
operations
have
been
converted
into 'low-level' constructions.
Variable
and structure references are compiled into
absolute
expressions.
All
information
needed
by the
file.
Except
code
generator is contained in
this
for
compiler
flags
and file names, nothing is
retained
in memory.
2. Pass 2 reads the code file, writing PDP-11
assembly
language
(in
the
format
requested
by
the
AS
assembler).
3. Pass 3 contains
some
end
of
processing
code
to
delete work files.
All internal files are in Ascii.
In order to
make
the
compiler
portable
between
RSX,
RSTS/E, and RT11,
the
file system is simple and inefficient.
RT11
users
may
run
into
intermediate
file
size
problems.
The
only
(software) solution requires
invoking
the
compilation
with explicit size arguments for the output files:
#out.s[N1],interm.tm1[N2],expand.tmp[N3]=in.c
The expanded source file should be less than the size
of
the
input
file
plus
all
#include
files.
The
intermediate file size may be as much as twice the
size
of the expanded source file.
o
C programs are assembled into PDP-11 object code by
the
AS assembler, whose source files are named
'AS????.MAC'.
The AS assembler is described in AS.DOC.
o
A support library for the two compilers is included in
a
group of files labeled A?????.MAC.
The C compiler
build
process also builds the support library.
This
library
is
similar
--
but
not
identical
-- to the run-
time
support library.
The compiler and assembler are installed
by
executing
command
files.
There
are
several groups of command files supplied
to
assist in implementation on the various operating
systems.
It
is
highly
likely that the files will have to be edited to
suit
each individual installation's needs.
VMS, RSX, and RT11
files
are
run
by
the
indirect command file processor, while
RSTS/E
files are run by the ATPK system program.
RSTS/E
installation
requires must be run from a privileged account.
C Compiler and Library
Page
3-3
Software Support Manual
The following file conventions
are
used:
VMS
command
files
begin with the letter 'V', RSTS/E RT11 mode with the letter
'R',
and RSTS/E RSX mode with the letter 'X'.
Native
RT11
command
files
begin
with
'T'
and native RSX-11M files begin with
the
letter 'M'.
Thus, XMAKCC.CMD builds the CC compiler for
RSTS/E
RSX-11M
mode.
The '.TKB' files are indirect command files
for
the task-builder.
Warning
As distributed, the compiler and run-time libraries
assume
hardware support for the SXT (sign-extend)
instruction. This is present on all PDP-11 CPU's with
EIS, and on all versions of the LSI-11 (11/03, LSI-11,
11/23). If the compiler is to generate code that will
run on the 11/04, 11/05, 11/10, 11/20, or on an 11/40
without EIS; all RSX.MAC and RT11.MAC configuration
files must be edited to define symbol C$$SXT equal to
zero. Note that the compiler must be build with C$$SXT
set correctly.
As distributed, the RSX configuration files assume
hardware EIS support. If this is not the case (hardware
EIS is not needed for RSX-11M) edit the RSX.MAC control
files to define symbol C$$EIS equal to zero. There are
two RT11 configuration files, and the RSTS/E library
build procedure builds an EIS library, CLIB.OBJ, as well
as a library without EIS support, CLIBN.OBJ.
The default 'native' RT11 command file builds a non-EIS
library, naming it CLIB.OBJ. Programs linked against
the non-EIS library will run on machines with EIS.
Also, save-images linked on RT11 will run on RSTS/E and
vice-versa without relinking.
There are certain differences in task-image format
between native RSX-11M and RSX-11M as emulated on
RSTS/E.
Thus, only source or
object
files
are
transportable between the two operating systems.
3.2 The C Run-time Support Library
________ _______ _______
___ _
The C support library is distributed on two accounts, [5,4]
and
[5,5].
Account [5,4] contains only those routines which have
no
I/O dependencies, while account [5,5] contains the standard
I/O
library.
Many routines are conditionally compiled to select RT11
RSX
mode.
either
All
routines
should
be
compiled together with
or
C Compiler and Library
Page
3-4
Software Support Manual
RT11.MAC (no EIS support), RT11.EIS (hardware EIS
support),
or
RSX.MAC, identical copies of which are present in each account.
To build the libraries, execute one
of
the
following
command
files:
RMAKLB.CMD
VMAKLB.COM
XMAKLB.CMD
MMAKLB.CMD
TMAKLB.COM
RT11
RSX
RSX
RSX
RT11
library
library
library
library
library
on
on
on
on
on
RSTS/E
VMS
RSTS/E
RSX-11M
RT11
Account [5,1] contains a program, GETCMD.C
which
was
used
to
build
assembler
command
files.
On
RSTS/E,
a command
file,
[5,1]RLBCMD.CMD, may be used
to
rebuild
all
library
command
files.
All library source code is in PDP-11 MACRO.
3.3 The RSTS/E Interface Library
_________ _______
Account [5,6] contains a library of
___ ______
subroutines
that
allow
programs access to all RSTS/E executive functionality.
There
C
is
no documentation other than the source code and
[5,6]README.506.
3.4 The RSX-11 Extensions Library
__________ _______
Account [5,7] contains a library of
___ ______
subroutines
that
C
programs
access
to
all RSX-11M executive
functionality,
including AST's. Refer to [5,7]CX.DOC for more
information.
allow
This
library
has
not
been completely tested, nor has it
been
tested on 'emulated' RSX-11M modes (under VMS or RSTS/E), nor
on
IAS or RSX11-PLUS.
3.5
RT11 Extensions Library
____ __________
_______
Access to RT11 executive functionality may be had by calling
the
system
library
(SYSLIB).
The C library call() routine may
be
used to generate the necessary
calling
sequences.
Note
that
SYSLIB
routines that depend on Fortran I/O conventions must
not
be called.
C Compiler and Library
Page
3-5
Software Support Manual
3.6
C Tools and Toys
_ _____ ___ ____
The distribution kit contains
several
accounts
[6,*]
with
C
programs
and
subroutines.
Account [6,1] contains a library
of
'software tools' which should be useful for all C
installations.
Among these are the following:
echo
Echo arguments onto the standard
output.
This
program
serves
as
the
primary
test
'Get regular expression pattern.'
This
of
the
run-time library.
grep
program
reads
one
or
more
files, printing text
lines
that match a given pattern.
kwik
'Key word in context' utility.
sortc
A file sort utility.
sorts
Sort-merge subroutines
for
incorporation
into
other programs.
wc
Count bytes, words, and lines
in
one
or
more
files.
ccxrf
Cross-referenced listings for C source files.
Please refer to README.???
files in
the
appropriate
accounts
for more information.
3.7
_____________
Building the Documentation
Compiler and assembler documentation is
AS.RNO
________ ___
in
CC.RNO
and
respectivly.
These
files,
stored in [5,1] or [.COMMAND],
are
compiled into .DOC files by using Runoff.
The
documentation
build control file appends the current problem list CBUGS.RNO
to
CC.RNO before building the documentation.
NOTE
In order to create titles properly on VMS "Standard
Runoff," a command line is present which may cause a
non-fatal error message to be printed by other versions
of Runoff, notably RNO.TSK. This error message should
be ignored.
The source of the library documentation is included
the
library source (Macro) files.
within
C Compiler and Library
Page
3-6
Software Support Manual
To build the library documentation, the following programs
must
have been built and installed on the system:
getrno
This program
reads
the
library
header
file,
breaking out wizard and non-wizard sections.
It
then reads a set of macro files (specified
using
a wild-card convention).
Each file contains
its
own documentation in
the
form
of
commentary.
This
follows
a
specific,
rigid
format
as
described in the documentation of getrno.c.
The output of getrno is
a
runoff
source
file
which is then merged with the various
appendices
to the library documentation.
The source of getrno.c is
stored
in
[5,1]
or
[.COMMAND].
The
running
program
is
normally
stored in C:.
getkwk
This program
reads
the
library
macro
files,
searching
for
"Index"
entries
in
the
documentation.
The output of getkwk
is
passed
directly to kwik.
The source of getkwk.c is
stored
in
[5,1]
or
[.COMMAND].
The
running
program
is
normally
stored in C:.
kwik
This is the keyword in context program which
is
used to build the library index.
as
It is built
part of the tools build procedure.
The source of
kwik.c
is
stored
in
program
is
[6,1]
or
[.TOOLS].
The
running
generally
written to a public library,
PUB:
on
RSTS/E,
BIN:
fixdoc
on VMS.
On RSTS/E RNO.TSK
and
VMS
"Standard
RUNOFF",
page
numbers are put at the "page right
margin"
(column 80) instead of the
text
right
margin,
column
72.
As a workaround, getrno is used
to
mark runoff .title lines.
Fixdoc is then run
to
straighten
out
the
titles.
Note that this
is
needed for RSTS/E RNO and VMS RUNOFF only.
The source of fixdoc.c is
stored
in
[5,1]
or
[.COMMAND].
The
running
program
is
noramlly
stored in C:.
Note that
is
is
used
on
only
____
RSTS/E.
The control files [5,1]RGTRNO.CMD and [5,1]RGTDOC.CMD
illustrate
the
process
on
RSTS/E
while
and
VGTDOC.COM illustrate it on VMS.
VGTRNO.COM
CHAPTER 4
COMPILER INTERNAL INFORMATION
As noted above, compiler work files are in human-readable
Ascii.
The
parser
generates
a
temporary
file
with
an
internal
pseudo-code.
The code generator converts
this
pseudo-code
to
PDP-11
assembly
language.
Except
for
compiler
flags,
all
communication between passes is via intermediate files.
4.1 Intermediate Code File Format
____ ____ ______
____________
The intermediate code file consists of single line
entries
for
each
operation.
The
first
byte
is an operator, followed
by
parameter entries as needed.
Numeric values are transmitted
in
octal.
The following operators are defined:
Location counter control:
C
Switch to the string
P-section
(c$strn)
O
Switch to the data
P-section
P
Switch to the program P-section
(c$data)
(c$code)
Ux[name] [attr] Define program section (x == P or D)
Flow control:
L [number]
J [number]
Define a local label
Jump to a local label
X
N
Function exit
Function entry
Data reservation, etc.:
A
Generate
B [number]
Generate
D
Generate
G
Generate
H
Generate
I
Generate
Y
Generate
a
a
an
a
a
a
a
.even pseudo-op
.blkb [number]
external label
.globl
.byte
.word as a local pointer
.word
Special operations:
@
No-op: generate a comment
W
Generate a switch table
Q
Dump symbol table entry (-t switch)
C Compiler and Library
Page
4-2
Software Support Manual
M
Transmit a line number between passes
Tree (expression) operators:
R
Return
S
Switch
E
Compile for effect
T
Jump if true
F
Jump if false
K
Initialize variable
Z
Tree item
Note that 'trees' are the result of compiling expressions,
such
as
(a + b * (c & 4)) * d
Each non-terminal node of a tree generally consists
of
a
left
part,
an
operation, and a right part.
Operator precedence
has
been resolved.
The above example thus becomes:
|
-----------------|
|
--------|
|
|
|
|
-------|
|
|
|
|
|
|
----|
|
|
|
|
|
((a + (b * (c & 4))) * d)
Trees
are
described
by
'Z'
records.
Tree
elements
are
variable-length records, the first value describing the
operator
(and, hence, the length).
All numeric
values
are
encoded
as
octal ascii strings.
The tree types are as follows:
OP.EOF
Used to signal a null tree element.
OP.CON
Constant, followed by 4 values.
OP.REG
Register, followed by type and register number.
OP.INX
Offset from register, followed by type, register
number,
and offset value.
OP.ID
Global identifier,
followed
by
type,
and
identifier
name.
OP.LID
Local identifier (label), followed by number.
other
An operator (OP.ADD, etc.) followed by
the
type
code.
Subsequent
records
contain
the left subtree, then
the
right
subtree.
null
subtree.)
(OP.EOF
is
used
to
signal
a
C Compiler and Library
Page
4-3
Software Support Manual
For example, here is a simple subroutine and the
intermediate
code it generates (the trees have been compressed):
fact(n)
{
if (n == 0)
D fact
N 0 4
F 1
Z [n == 0]
return(1); R
Z [1]
J 2
return(n * fact(n - 1));
L 1
R
Z [n * fact(n L 2
X
G fact
}
The C source code is parsed by
a
|
|
|
|
|
|
|
define function fact
enter function
if false, goto L1
compile expr. value
return
compile expr. value
goto L2
| Label L1, N != 0
| return
1)]
| compile expr. value
| label L2
| Exit from function
| .globl fact
top-down,
recursive
parser.
Expressions
are
parsed bottom-up, by priority.
Casts of
types
are
processed
by
special
routines.
The
parser
does
some
optimizations,
such
as
constant folding.
Also, all
automatic
variables (local to a function), are assigned
absolute
offsets
from
the
argument frame (Register 5), while structure
elements
are assigned absolute offsets from the base of the structure.
4.2
The Code Generator
___ ____ _________
The code generator consists of a top-level
input
file
reader,
which processes 'easy things' directly.
It calls subroutines
to
compile
switch
statements
and
expressions.
The
expression
compiler
performs
various
optimizations, calls a Sethi-
Ullman
register allocator, then a
Ullman
code
generator.
The
Sethi-
algorithm
was
described
in the Journal of the ACM, Volume
17,
No.
4, October 1970.
pp.
715-728.
4.2.1 Optimizations and Register Allocation
_____________ ___ ________ __________
The following optimizations are performed:
o
Expressions are reordered.
o
Constant expressions are folded.
o
Dummy operations are eliminated, including -(-A),
!(!A),
~(~A), (A & A) and (A | A).
o
and
Dummy address expressions
are
eliminated:
*(&A)
C Compiler and Library
Page
4-4
Software Support Manual
&(*A) all become A.
o
Constant address arithmetic is performed in
expressions
such as &A + const.
o
Constant offsets from registers become index
operations
in
expressions
such
as
*(reg
+ constant) or *(reg
constant).
o
PDP11
autoincrement
and
autodecrement
are
used
in
expressions such as *p++ and *--p.
o
Conversion between integer
and
pointer
datatypes
are
converted to multiply and divide operations.
o
Multiply by 1 is deleted.
o
The and operator is converted to BIC.
o
Null operations are deleted, including +0, -0, &-1,
|0,
^0, |=0, etc.
o
If the compiler has
been
built
for
in-line
floating
point
(i.e.,
the
machine
on
which the compiler
runs
supports floating point), floating point
constants
are
folded.
Register allocation is as follows:
o
R0 and R1 are always scratch registers.
o
R2, R3, and R4 may be reserved by the C program by
using
the
'register
...' construction.
The parser tells
the
coder the highest register it can use (in
the
function
initialization intermediate code operation).
o
The
Sethi-Ullman
algorithm
stores
the
number
of
registers
needed
into
each tree node.
This number
is
always >= 2 to insure that R0 and R1 are
available
for
scratch usage.
o
'A tree is easy
if
the
other
tree
uses
few
enough
registers and there is a free register available.'
o
The GETREG subroutine claims
registers.
If
the
code
table is modified, be sure that GETREG isn't called on
a
tree that isn't easy.
C Compiler and Library
Page
4-5
Software Support Manual
4.2.2
Code generation
____ __________
Almost all code is generated by expanding macro operators out
of
the code tables.
There are four tables (CTAB, ETAB, STAB,
RTAB)
and
a
pseudo-table,
TTAB.
Only
RTAB
is
complete,
If
an
expansion
which
was
attempted
in
CTAB
or ETAB fails, it
is
retried in RTAB followed by a test (CTAB), move (ETAB), or
push
(STAB)
operation.
For
example,
if
an
expansion
which
was
attempted in STAB fails, it is done by:
[Rtab]
mov
Reg,-(sp)
The code body is in Ascii;
bytes with the parity
(eighth)
bit
set
are used macro operators:
'address of left', 'push
right',
etc.
Code table entries are selected by the
type
of
the
arguments
(int,
char,
long, unsigned, float, double, and pointer) and
by
kind (constant, address, easy, and any).
Here is a typical code table (for addition):
int
any
[LL]
int
con1
inc
[R]
any
[LL]
int
add
[AR],[R]
any
[SRV]
int
; Add 1 to any integer
; Compile left
(subtree)
int
; INC Rx
addr
; Add var. to anything
; Compile left
(subtree)
int
address
; ADD var,Rx
easy
; Setup right value,
; NOP if it's an
[LL]
; Compile left
(subtree)
int
add
[AR],[R]
any
[PR]
int
; Add var,Rx
any
; Compile right to
stack
[LL]
add
(sp)+,[R]
; Compile left to reg.
; ADD (sp)+,Rx
Here is another example, '= for effect' (as in 'A = B;'):
int
char
any
int
any
int
[SLAC]
clr[TL] [AL]
con0
con0
int
char
addr
int
any
addr
int
any
[LR]
mov[TL] [R],[AL]
;
;
;
;
I = 0;
C = 0;
Get left op. address
CLR(B) var
; Compile right subtree
; MOV(B) Rx,var
C Compiler and Library
Page
4-6
Software Support Manual
int
char
int
char
any
int
easy
any
int
easy
[SRV]
[SLAC]
mov[TL] [AR], [AL]
any
int
any
any
int
any
[PLA]
[LR]
mov[TL] [R],@(sp)+
Note that the "easy" storage
will
; Setup right value
; Setup left address
; Push left address
; Compile right value
handle
indirect
addressing
"(rx)", as well as autoincrement "@(rx)+" and
autodecrement
"@-(rx)". If the datum is long, the <ALN> and <ARN>
code
operators perform the address computation without sideeffects.
For example, the following computation performs "i <<= 8",
where
'i' is an integer:
swab
clrb
mov
[ALN]
[ALN]
[AL],[R]
4.2.3 Macros used in code generation
____ __ ____ __________
The following are defined in the code generator:
[M]
[F]
[F.1]
[R]
[R.1]
[AL]
[AL.2]
[AL.4]
[AL.6]
[ALN]
[AR]
[AR.2]
Set modulo return
Set function return
Result value is in r1
Current register
Current register + 1
Address of left
Address of left+2 (long int)
Address of left+4, double
Address of left+6, double
Address of left, no side effect
Address of right
Address of right, long
______
[ARN]
[OP.0]
[OP.1]
[TL]
[T]
[SRVA]
[SRV]
[SRAA]
[SRA]
[SLVA]
[SLV]
[SLAA]
Address of right, no side effect
Opcode
Opcode
Type of left
Type of right or left
Set right value anywhere
Set right value
Set right address anywhere
Set right address
Set left value anywhere
Set left value
Set left address anywhere
C Compiler and Library
4-7
Software Support Manual
[SLA]
[SLAC]
[LL]
[LL.1]
[LL.O]
[LLP.O]
[LLP.E]
[LR]
[LRP.E]
[PL]
[PLA]
[PR]
[V]
[FPI]
[FPL]
[FPF]
[FPD]
[GO.TO]
[IFEIS]
[IFFPU]
[IFOP]
[ELSE]
[ENDIF]
[DEBUG]
Set left address
Set left address current reg.
Load left
Load left into [R+1]
Load left into odd register
Load left into odd of pair of registers
Load left into even of pair or registers
Load right
Load right into even of pair of registers
Push left
Push left address
Push right
ADC or SBC for longs
Set floating point to I mode
Set floating point to L mode
Set floating point to single precision
Set floating point to double precision
Branch within code table
Compile if hardware EIS support
Compile if hardware FPU support
Compile if specifed opcode
Compile if IF... test was false
End IF... block
Write debug record to .S file
Page
CHAPTER 5
LIBRARY FUNCTION DESCRIPTIONS
This chapter contains descriptions of
each
of
the
C-
callable
runtime
library
functions.
In
addition,
descriptions
of
internal routines are provided.
In most cases the I/O functions match those of UNIX V7
closely,
with differences normally called out.
information,
consult "The C Programming Language" by
and
Dennis
Ritchie
(Englewood
Cliffs,
Hall,
ISBN 0-13-110163-3).
Routines and global symbols beginning with
For more
Brian
Kernighan
NJ:
Prentice-
'$$'
are
used
for
communication
among the I/O routines.
Routines whose names
are
of the form 'ABC$X' implement the 'ABC' instruction for the
'X'
data
type.
For example, 'ASL$LI' implements an arithmetic
left
shift of a long value by an integer argument.
C Compiler and Library
Page
5-2
$$abuf
Allocate memory for i/o buffers
5.1 Allocate memory for i/o buffers
______ ___ ___ _______
________
**********
* $$abuf *
**********
File name:
ioabuf.mac
Usage
mov
call
bcs
#iov,r4 ;file data block
$$abuf ;Allocate it
error
;Exit on errors
Description
A block of memory is allocated.
If it succeeds, the
iov
record
buffer is correctly setup and $$abuf returns
the
buffer address in r0.
If it fails,
an
error
code
is
stored
in
$$ferr,
the
error
bit set in the iov
flag
word, r0 is set to 0, and $$abuf returns with the
bit
set.
In RSX mode, the record gets padding that may be
needed
by $$put.
Bugs
C-
C Compiler and Library
Page
5-3
$$c5ta
5.2
Convert Radix-50 to Ascii
Convert Radix-50 to Ascii
_______ ________
__ _____
**********
* $$c5ta *
**********
File name:
c5ta.mac
Usage
mov
mov
call
rad50_word, r1
out_ptr, r0
$$c5ta
Return:
r0 updated
r1 random
other registers preserved.
Description:
Convert one radix-50 word to
three
Ascii
bytes.
All
letters
will
be in upper-case.
The output buffer
will
not be null-trailed, nor will blank fields be
supressed.
Bugs
C Compiler and Library
Page
5-4
$$cl16
5.3
Close all channels
Close all channels
_____ ___ ________
**********
* $$cl16 *
**********
File name:
iocl16.mac
Usage
$$cl16();
/* Close all channels
*/
Description
This module closes all I/O channels.
on
exit from C programs.
Diagnostics
Bugs
It
is
called
C Compiler and Library
Page
5-5
$$clfu
Flush last record before closing
5.4 Flush last record before closing
______ ______ _______
_____ ____
**********
* $$clfu *
**********
File name:
ioclfu.mac
Usage
mov
call
#iov,r4
$$cflu
;r4 -> i/o vector
;Flush buffers for close
Description
Flush the output buffer if the file is open for
output.
On
RSX,
the code may be conditionally compiled so
that
the last buffer is fixed so it is SEE compatible.
Bugs
C Compiler and Library
Page
5-6
$$ctim
Convert $$rtim Buffer to Ascii
5.5 Convert $$rtim Buffer to Ascii
______ ______ __ _____
_______
**********
* $$ctim *
**********
File name:
rctime.mac
Usage
char *
$$ctim(buffer);
struct TIME {
int
int
int
int
int
int
int
int
} buffer;
year;
month;
day;
hour;
minute;
second;
tick;
tsec;
/*
/*
/*
/*
/*
/*
/*
/*
G.TIYR
G.TIMO
G.TIDA
G.TIHR
G.TIMI
G.TISC
G.TICT
G.TICP
year - 1900
Jan. = 1
*/
*/
*/
00 .. 23
*/
00 .. 59
*/
00 .. 59
*/
00 .. tsec-1 */
tick/second */
dayofweek(buffer);
struct TIME buffer;
Description
$$ctim() converts the time information in buffer such
as
returned
by
$$rtim()
to
a
character
string
in
the
format:
Sun Sep 16 01:03:52 1973\0\0
All the fields have constant width.
Note that there
are
two
trailing
<null>'s
for
the
benefit
of
programs
converted from Unix (where the year
a
is
followed
by
<newline>).
$$ctim(0) returns
the
current
time
of
day,
calling
$$rtim() internally.
The format of the returned information is
identical
to
the
Unix function of the same name except that the
Unix
function has a trailing newline which is omitted here.
dayofweek() returns the day of the week (Sunday = 0)
for
the date information in the argument buffer.
C Compiler and Library
Page
5-7
$$ctim
Convert $$rtim Buffer to Ascii
Bugs
There is no range checking on the information passed.
C Compiler and Library
Page
5-8
$$div2
5.6
______ _____
Unsigned divide (Macro only)
Unsigned divide (Macro only)
________ ______
**********
* $$div2 *
**********
File name:
div2.mac
Usage
mov
mov
mov
jsr
mov
mov
mov
hi_div,r0
lo_div,r1
divisor,r2
pc,$$div2
r0,hi_quotient
r1,lo_quotient
r2,remainder
;High-order dividend
;Low-order dividend
;Divisor
;Perform the division
;High-order quotient
;Low-order quotient
;Remainder
Description
Perform an unsigned double-precision division.
This
is
needed for one of the library conversion routines.
Bugs
C Compiler and Library
Page
5-9
$$dtoa
5.7
Convert floating to ASCII
Convert floating to ASCII
_______ ________
__ _____
**********
* $$dtoa *
**********
File name:
dtoa.mac
Usage
char *
$$dtoa(buff, conv, field, dplace, value)
char
*buff;
/* Where it goes
char
conv;
/* Conversion type
int
field;
/* Maximum field width
int
dplace;
/* Decimal part width
double value;
/* What to convert
*/
*/
*/
*/
*/
Description
$$dtoa() is called to do the
conversion
to
Ascii
text
$$dtoa() returns a
The
is
written to buff[].
pointer
to the trailing null byte.
Field and dplace are the conversion parameters
"f"
and
"d"
in the format string "%f.df".
Conv is 'e', 'f',
or
'g' to define the
format.
Note
that
the
conversion
character must be in lower-case.
$$dtoa()
is
called
by
printf
to
convert
a
double-precision value to Ascii.
The text is written
to
buff[].
Field and dplace are the conversion
parameters
"f"
'e',
and
"d"
in the format string "%f.df" Conv is
'f', or 'g' to define the format.
Note:
the
conversion
character must be in lower-case.
To use
floating
point
conversion,
the
program
must
reference the $$fpu global as follows:
extern
If this is not
int
done,
$$fpu;
attempting
to
convert
floating
point will result in your program crashing.
Bugs
Only single precision conversion is done so far.
The machine
which
must
support
FPU
floating
point,
C Compiler and Library
Page
5-10
$$dtoa
Convert floating to ASCII
implies EIS.
Note:
No compile-time test for C$$EIS is done.
This routine uses the table in the DOUTAB module
C Compiler and Library
Page
5-11
$$fadd
Floating-point support, add/subtract
5.8 Floating-point support, add/subtract
______________ ________ ____________
**********
* $$fadd *
**********
File name:
fadd.mac
Usage
double
$$fadd(a, b)
/* Floating add a + b
*/
double
$$fsub(a, b)
/* Floating sub a - b
*/
double
double
a;
b;
Description
Called by the compiler to compile floating-point.
Bugs
BEWARE:
Untested
C Compiler and Library
Page
5-12
$$falo
Allocate memory for i/o subroutines
5.9 Allocate memory for i/o subroutines
______ ___ ___ ___________
________
**********
* $$falo *
**********
File name:
iofalo.mac
Usage
mov
call
size,r0 ;Memory needed
$$falo ;Allocate it
;return, r0 -> allocation
;no room: return to caller via $$fope
Description
A block of memory is
allocated.
If
this
fails,
the
return
is
to the caller of fopen (or fwild/fnext)
with
i/o control blocks deleted as necessary.
Bugs
C Compiler and Library
Page
5-13
$$fcsi
5.10
Scan file name for fopen
Scan file name for fopen
____ ____ ____
___ _____
**********
* $$fcsi *
**********
File name:
iocsi.mac
Usage
mov
call
iov,r4
$$fcsi
;r4 -> iov
;C$PMTR+0(r5) => file name
;file name is parsed and fdb setup.
;r0-r3 random
;error: return to caller via $$fope
Description
Parse the file name argument, initializing the file
data
block.
Bugs
Used on RSX only.
C Compiler and Library
Page
5-14
$$flsh
5.11
Flush output buffers
Flush output buffers
_____ ______ _______
**********
* $$flsh *
**********
File name:
ioflsh.mac
Usage
mov
call
#iov,r4
$$flsh
;r4 -> i/o vector
;Internal flush routine
Return, all registers preserved.
Description
$$flsh is called by other file I/O routines to flush
the
current
record buffer.
If this is the first call to
an
output routine for this file, $$flsh will be called
and
will allocate a buffer.
On RSX, if the file is open to the
terminal",
the flush is to stderr.
Bugs
"command
C Compiler and Library
Page
5-15
$$flun
Allocate a logical unit for fopen
5.12 Allocate a logical unit for fopen
_ _______ ____ ___ _____
________
**********
* $$flun *
**********
File name:
ioflun.mac
Usage
mov
call
iov,r4
$$flun
;r4 -> iov if any, else r4 := 0
;Get a Lun slot, initialize fdb
;return, r4 -> iov, r3 := lun
;r0, r1 random
;error: return to caller via $$fope
;Note: available RSX luns start at 2,
;while RT11 luns start at zero.
Description
Perform all initialization needed to allocate a new
file
descriptor.
Bugs
In RSX modes, the maximum number of files
that
may
be
simultaneously
open
macro (FSRSZ$)
which
is
defined
at assembly time by
a
is
expanded
when
fopen.mac
is
assembled.
The default FSRSZ$ parameter is 4.
This
may
be modified by using the task builder /ACTFIL=n
option.
The
default
FSRSZ$ value may be specified when the
RSX
library is built by editing assembly parameter N$$FIL
in
RSX.MAC.
C Compiler and Library
Page
5-16
$$fmul
Floating-point multiply/divide
5.13 Floating-point multiply/divide
______________ _______________
**********
* $$fmul *
**********
File name:
fmul.mac
Usage
double
$$fmul(a, b);
double
double
/* Floating multiply
*/
a;
b;
Description
Called
by
the
compiler
point
multiply.
Bugs
BEWARE:
untested
to
execute
floating-
C Compiler and Library
Page
5-17
$$fopa
5.14
Open file (RT11 only)
Open file (RT11 only)
____ ____ _____
_____
**********
* $$fopa *
**********
File name:
iofopa.mac
Usage
mov
mov
jmp
iov,r4
lun,r3
$$fopa
;r4 -> iov
;r3 := lun
;RT11 file open (ascii file spec.)
;C$PMTR+0(r5) => ASCII file spec.
;(may include file size for writes)
;Parse the file using .CSISPC, open it,
;returning to the caller via cret$ or
;$$fope if error.
mov
mov
mov
iov,r4 ;r4 -> iov
lun,r3 ;r3 := lun
dblk,r1 ;r1 -> Rad50 device descriptor,
jmp
$$fopr
followed
;by filesize word if write reqeust.
;open by Rad50 device descriptor
;RT11 only -- used to open the device
;for directory processing. Exit via
;cret$$ or $$fope if error.
;If successful, the number of blocks in
;the file is stored in the first word
of
;the block buffer.
Description
Actually
open
the
RT11
file,
buffer
management and post-open cleanup.
Bugs
doing
data
C Compiler and Library
Page
5-18
$$fopt
Scan options parameter for fopen
5.15 Scan options parameter for fopen
_______ _________ ___ _____
____
**********
* $$fopt *
**********
File name:
iofopt.mac
Usage
mov
call
iov,r4
$$fopt
;r4 -> iov
;C$PMTR+2(r5) => options string
;return: option flags in fdb
;r0 random
;error: return to caller via $$fope
Description
$$fopt parses the options argument in
calls
to
fopen,
freopen(),
or
fwild().
It returns to the caller
(via
$$fope) if the argument was incorrect.
Bugs
C Compiler and Library
Page
5-19
$$fsav
Floating-point support routines
5.16 Floating-point support routines
______________ _______ ________
**********
* $$fsav *
**********
File name:
fis.mac
Usage
$$fsav
$$frta
$$frtb
/* Floating save
/* Return to caller a
/* Return to caller b
*/
*/
*/
Description
These routines are used internally by the floatingpoint
simulation
package.
They
are
never
called by the
C
program.
Bugs
BEWARE:
untested.
Note also
that
whereas
C
these
routines
are
single-
precision,
requires
double
precision.
When/if
floating-point becomes a reality, something better
will
have to be done.
C Compiler and Library
Page
5-20
$$gcmd
5.17
Parse command line
Parse command line
_____ _______ ____
**********
* $$gcmd *
**********
File name:
getcmd.mac
Usage
argc = $$gcmd(text, in,
char
*text;
char
**in;
char
**out;
char
***avp;
char
*task;
out, avp, task)
/* Command line */
/* stdin filename
/* For stdout filename
/* Gets argv[] location
/* Task name if nonnull
*/
*/
*/
*/
Description:
Parse the command line, building the argv[]
table.
If
I/O
redirection is encountered, in and out are
modified
accordingly.
NOTE:
$$gcmd will modify
text.
argv[]
entries
will
point to bytes in text.
If not NULL, the task name
will
become argv[0].
Unquoted arguments will
be
forced
to
lowercase, duplicating the action of Vax-11 C.
$$gcmd() returns the number of arguments encountered.
$$gcmd() is called in the following fashion:
/*
* Default input is on tty
*/
char
**infile = &def_in;
char
*def_in = "tt:";
/*
* Default output is on tty
*/
char
**outfile = &def_out;
char
*def_out = "tt:";
/*
* Define argv[] pointer and dummy command
* line.
*/
char
**argvp;
char
*dummy = "main";
int
argc;
C Compiler and Library
Page
5-21
$$gcmd
Parse command line
...
argc = $$gcmd((strlen(cmdlin) == 0) ?
dummy : cmdlin,
&infile, &outfile, &argvp, $$task);
if (argc < 0)
error("Bad command line");
stdin = fopen(infile, "r");
if (**outfile == ">")
stdout = fopen(*outfile + 1, "a");
else
stdout = fopen(*outfile, "w");
Bugs
In order to compensate for a problem with
native
RT11,
the "parity" bit is erased from the argument text.
This
will need modification to
Internation
character set.
handle
the
Dec
C Compiler and Library
Page
5-22
$$get
5.18
Get a record
Get a record
___ _ ______
*********
* $$get *
*********
File name:
ioget.mac
Usage
RSX:
mov
mov
mov
call
#iov,r4
#buffer,r0
buflen,r1
$$get
;r4 ->
;r0 ->
;r1 :=
;Get a
i/o vector
buffer
max. buffer size
record
VF$EOF and/or VF$ERR are set on error or end of file.
r0 := actual record length, -1 on error or end of file.
Other registers preserved.
RT11:
mov
call
#blknbr,r0
$$get
;r0 := block to read
;Get block (.gtline record)
VF$EOF and/or VF$ERR are set on error or end of file.
r0 is zero if success, -1 on error or end of file.
Other registers preserved.
clr
jmp
r0
$$geof
;End of file error
;(called by $$getc)
Description
$$get is the internal "get a record" routine.
Note
that
the
maximum record size (r1) is only needed on RSX.
On
RT11, it is fixed at
512.
82.
bytes for terminal lines.
bytes
for
files
and
If the file is defined as "stream" (the "n" flag was
not
set
when the file was opened using fopen()), the end
the
line
of
will
be
represented
by
the
(\n)
character, and NULL's will be removed.
Bugs
newline
C Compiler and Library
Page
5-23
$$getc
5.19
Get characters
Get characters
___ __________
**********
* $$getc *
**********
File name:
iogetc.mac
Usage
mov
call
#iov,r4
$$getc
;r4 -> i/o vector
;Get a character
Description
$$getc is the internal "get a byte" routine.
The
byte in the indicated file is returned in r0.
All
next
other
registers are preserved.
$$getc will allocate a
buffer
if necessary.
This routine
removes
all
NULL
bytes
and
<CR>
from
<CR><LF>
sequences
unless the file was opened with
the
'n' (nostream) option.
Bugs
RT11 uses .gtline to read from the user's terminal
(thus
tracking
indirect
command
files).
To
read from
the
physical terminal, fopen "TT:" using "n" mode.
RSTS/RT11 has problems reading using
either
.ttyin
or
.gtline.
There
is
force
"native" system calls.
thus
special
case
code to
C Compiler and Library
Page
5-24
$$init
One-time initialization code
5.20 One-time initialization code
______________ ____
________
**********
* $$init *
**********
File name:
init.mac
Usage
Internal
$$init()
Description
When a C program is started, a command line is parsed
to
form
the
argv[]
array and the standard input,
output,
and error files are opened.
main() may be
declared
as
follows:
main(argc, argv)
int
argc;
char
*argv[];
{
register int
i;
/* Arg counter
*/
for (i = 1; i < argc; i++) {
printf("arg[%d] == %s\n", i, argv[i]);
}
}
Note the following:
On RSX11/M (even emulated), argv[0] will be set
to
the
task
name.
a
dummy value.
On
RT11
modes,
argv[0] will be set to
If no command line is passed to
the
program,
it
will
prompt
the
task
name (or "Argv") and read a line
from
the command terminal.
To disable this, the user
program
may define a global flag as follows:
$$narg = 1;
main (argc, argv)
{
...
}
C Compiler and Library
Page
5-25
$$init
One-time initialization code
If $$narg is initialized non-zero and no command line
is
passed to the program, or if the initialization
sequence
fails to read an argument, main() will
be
called
with
one argument.
The command line prompt may be
changed
from
the
task
name (or "Argv") by defining a global string as
follows:
char *$$prmt = "Command line prompt"
main(argv, argc) {
...
On Vax VMS, the program may be installed as
a
"foreign
command" by a command such as:
$ command :== $disk:[dir]filename
and executed by typing:
$ command arg1 arg2
Internal
MAINTAINERS, Please Note
This
module
contains
code
that
is
sensitive
to
particular
releases
of
the various operating
systems.
Also, there is code that is
sensitive
to
the
various
types
of
operating
system
emulators.
The
maintainer
should strive to keep all such code in this module.
This module has been tested on VMS V3.0 and V3.1,
RSTS/E
V7.1,
RT11
V4.0,
and
RSX-11M
V4.0.
work
correctly on earlier (or later) releases.
It may not
Note especially the "secret patch" to allow Decus
C
to
read
stream
files
on
VMS
V3.0
(and
V3.1), and
the
command line parser for VMS version 3.0 and later.
This
code will require examination on every release of VMS.
Diagnostics
Can't parse command line
?C-Standard input, [filename]:
?C-Standard output, [filename]:
error text
error text
?C-No memory.
The "can't parse" message is given if the
command
line
format
is
incorrect
quotation
marks, for example).
(because
of unbalanced
C Compiler and Library
Page
5-26
$$init
One-time initialization code
The "standard input" or "standard output" messages are
a
user
error
if
input
or output are redirected and
the
associated files cannot be opened.
The text
should
be
self-explanatory.
The "no
memory"
message
program
immensity.
suggests
a
severe
case
of
On
RSX systems, it probably
means
that the task was not built /CP (checkpointable).
All errors are fatal.
Bugs
On RSTS/RSX, command lines
are
limited
to
80
bytes,
although
128
byte
commands are feasable.
On VMS
V3.0
and V3.1, the command name includes the expanded form
of
the
command
name.
This
means that long command
with
long
name
translations coupled
argument
strings
may
cause
the
total
argument
string
to exceed 80
bytes.
Such arguments will be truncated by the operating
system
without
warning.
The
work-around
is
to make use
of
logical names:
$ assign $disk[directory.subdirectory] bin
$ program :== $bin:prog
The expanded form
of
the
"program"
command
is
just
"bin:prog".
On VMS V3.0 and V3.1, the distributed RSX
file
service
(FCS) refuses to open "stream Ascii" files.
module
This
contains
a
dynamically-installed
patch
to
the
open
routine.
An error message will be printed if the
patch
cannot be installed correctly.
The VMS3.0
switch
There
compile-
time
enables
this
patch.
is
also
code
in
fopen.mac that is affected by this patch.
It might be reasonable to make error messages
non-
fatal
so $$init could be called by a user program.
On
RSX,
the
program
aborts
(by
executing
a
BPT
instruction)
if
the
program
or
obtain partition parameters.
fails
to open stderr
C Compiler and Library
Page
5-27
$$link
5.21
Print memory list
Print memory list
_____ ______ ____
**********
* $$link *
**********
File name:
malink.mac
Usage
$$link();
/* Print memory list
*/
Return: all registers preserved
Description
Subroutine $$link()
writes
the
allocation
list
onto
stderr.
It
was
written
to debug malloc() but may
be
useful for debugging programs
that
write
in
memory.
Note that it preserves all registers.
Diagnostics
Bugs
randomly
C Compiler and Library
Page
5-28
$$ltoa
5.22
Convert long to Ascii
Convert long to Ascii
_______ ____ __
_____
**********
* $$ltoa *
**********
File name:
ltoa.mac
Usage
$$ltoa(buff, radix, value);
char
*buff; /* Where it goes
int
radix; /* Conversion radix
long
value; /* What to convert
*/
*/
*/
Description
Called by printf to convert a long integer
from
binary
to
Ascii,
storing
the
result
in
radix
argument determines the conversion:
d
o
u
X
x
Bugs
Signed decimal
Octal
Unsigned decimal
Hex (10-15 = A-F)
Hex (10-15 = a-f)
buffer.
The
C Compiler and Library
Page
5-29
$$main
5.23
Start of C programs
Start of C programs
_____ __ _ ________
**********
* $$main *
**********
File name:
suport.mac
Usage
$$main::
extern
extern
extern
extern
extern
extern
extern
extern
extern
/* Start of C programs
*/
/*
/*
/*
/*
/*
/*
/*
/*
/*
Operating system
Non-zero if RSTS/E
Non-zero if VMS
Non-zero if P/OS
RSX: Default uic
Stack end point
RT11: .scca control
RSX: task name
Clock interrupt rate
*/
*/
*/
*/
*/
*/
*/
*/
*/
/* Profile printer
Argument count
Argument list ptr.
Free memory start
Free memory end
*/
*/
*/
*/
*/
int
int
int
int
int
int
int
char
int
$$opsy;
$$rsts;
$$vms;
$$pos;
$$uic;
$$stnd;
$$scca;
$$task[];
$$tick;
int
int
int
char
char
(*$$pptr)();
$$argc;
/*
*$$argv[]; /*
*$$mtop;
/*
*$$mend;
/*
Internal
extern
extern
extern
extern
extern
Description
This
module
contains
the
run-time
startoff
for
C
programs.
It intializes the C environment and calls
the
main() subroutine.
On return
from
the
main
exit()
to close all files and return to
program,
is
called
the
operating system.
The following globals are defined in this module:
$$opsy
Operating
system
unique
value.
value
7 on RT11, and set as per
This
is
the
GTSK$ directive on RSX-based systems:
RSX11-D
0.
RSX11-M
1.
RSX11-S
2.
IAS
3.
RSTS/E V7
4.
VMS
5.
C Compiler and Library
Page
5-30
$$main
Start of C programs
RSX11-M+
RT11
P/OS
$$rsts
6.
7.
9.
This value is non-zero if the program
is
running
on
RSTS/E.
program
is
running
It is zero if
the
native
RSX,
RT11,
P/OS or VMS compatibility mode.
$$vms
This value is non-zero if the program
is
running
(in
compatibility mode) on
Vax
VMS.
It
is
zero
if
the
program
is
running
native
RSX,
RT11,
P/OS or
on
RSTS/E.
$$pos
This value is non-zero if the program
is
running on the Professional P/OS.
It
is
zero if the program
is
running
native
RSX, RT11, or on RSTS/E or VMS.
$$stnd
The (top) end of the stack on entrance.
$$scca
On RT11, the .scca control
word.
This
is
needed
to
allow RSTS/E programs
to
trap end of file.
$$task
On RSX, the task name in Ascii.
$$tick
The clock interrupt rate.
This
is
set
at
initialization
on
RT11
and on
the
first call to time() or ftime() on RSX.
$$uic
GTSK$.
On RSX, the default UIC word from
Internal
All $$
values
are
for
internal
communication
among
runtime library routines.
I.e., let them alone.
Diagnostics
On RSX, the task aborts with a BPT if the standard
error
file
did
not
open.
error
messages are printed.
Bugs
Otherwise,
explanatory
C Compiler and Library
Page
5-31
$$mchk
Verify memory allocation pointers
5.24 Verify memory allocation pointers
______ __________ ________
______
**********
* $$mchk *
**********
File name:
mamchk.mac
Usage
$$mchk();
/* Check memory list
Description
Subroutine $$mchk()
checks
allocation
list
pointers.
The
program
is
crashed
by calling error if
something
goes wrong.
Bugs
$$mchk preserves all registers.
*/
C Compiler and Library
Page
5-32
$$narg
5.25
Define default for $$narg
Define default for $$narg
______ _______
___ ______
**********
* $$narg *
**********
File name:
narg.mac
Usage
int
$$narg
...
main() {
...
}
= <value>;
Description
If no command line is provided when the program
starts,
the program will print a prompt on the command
terminal,
read one line and build the argv[] vector.
If
this
is
undesirable,
include
a
global definition of $$narg
in
your C program as follows:
int
$$narg
=
1;
This will supress the command terminal
read
operation.
The argv[] vector will be set to a dummy value.
If the user program does not define $$narg, it
will
be
defined so as to enable the prompt.
Note that $$narg must be initilized at compilation
time.
It
the
is
tested
by
the
initialization
code before
main() program is called.
Bugs
C Compiler and Library
Page
5-33
$$prmt
5.26
Null prompt pointer
Null prompt pointer
____ ______ _______
**********
* $$prmt *
**********
File name:
prmt.mac
Usage
char *$$prmt = "Prompt string";
Description
This pointer is checked in $$init and if
the
user
has
defined
$$prmt
then it will be used as the task
prompt
instead of using the task name
on
RT-11.
on
RSX
or
"Argv:"
C Compiler and Library
Page
5-34
$$prnt
5.27
Print formatter
Print formatter
_____ _________
**********
* $$prnt *
**********
File name:
doprnt.mac
Usage
$$prnt(format, argvec, iov)
char
*format;
int
*argvec[];
FILE
*iov;
Description
$$prnt()
performs
all
formatting
operations
for
printf(),
sprintf(),
and
fprintf().
The
formatting
options are described int the documentation of
printf().
Bugs
$$prnt() is
functionally
identical
to
the
_doprnt()
module
in
Unix and Vax-11 C libraries.
Unfortunately,
the '_' conflicts with RSX FCS library conventions.
C Compiler and Library
Page
5-35
$$put
5.28
__ ___ ____
Write a record -- RSX only
Write a record -- RSX only
_____ _ ______
*********
* $$put *
*********
File name:
ioput.mac
Usage
mov
mov
mov
call
#bufadr,r0
nbytes,r1
#iov,r4
$$put
;r0 -> buffer start
;r1 := number of bytes
;r4 -> i/o vector
;Internal put buffer routine
Return, r1..r4 preserved.
Description
$$put is called by RSX-mode routines to write a
record.
$$put
only
runs
under
the
RSX library.
Using it
in
RT11-mode will cause the job to abort with a
BPT
trap.
The byte count may be zero for RSX Terminal I/O.
If output is to
flushed
(first).
Bugs
a
terminal,
stderr
will
be
C Compiler and Library
Page
5-36
$$putc
Output one character to a file
5.29 Output one character to a file
_________ __ _ ____
______ ___
**********
* $$putc *
**********
File name:
ioputc.mac
Usage
mov
mov
call
#iov,r4
byte,r0
$$putc
; r4 -> I/O vector
; r0 := byte to output
Description
$$putc is the internal call to write one character to
an
indicated file.
On return, all registers are
preserved,
even r0.
$$putc
will
allocate
a
record
buffer
if
necessary.
If an error is detected, $$putc will
return
to the original (C-language) caller.
Bugs
C Compiler and Library
Page
5-37
$$qiow
Call RSX executive service
5.30 Call RSX executive service
_________ _______
____ ___
**********
* $$qiow *
**********
File name:
ioqiow.mac
Usage
mov
mov
mov
call
bcs
<I/O function code>,r0
IOV pointer,r4
<iopl parameters> onto the stack, right to left
$$qiow
<error>
Description
Issue a qio$ directive
for
all
I/O
requests
needing
such.
Uses r0, r1.
This routine is used only in the RSX library.
Using
it
in the RT11 library will cause the program to abort
with
by executing a BPT instruction.
Bugs
C Compiler and Library
Page
5-38
$$rtim
5.31
Date and time conversion
Date and time conversion
____ ___ ____
__________
**********
* $$rtim *
**********
File name:
rtime.mac
Usage
$$rtim(buffer);
struct TIME {
int
int
int
int
int
int
int
int
} buffer;
year;
month;
day;
hour;
minute;
second;
tick;
tsec;
/*
/*
/*
/*
/*
/*
/*
/*
G.TIYR
G.TIMO
G.TIDA
G.TIHR
G.TIMI
G.TISC
G.TICT
G.TICP
year - 1900
Jan. = 1
*/
*/
*/
00 .. 23
*/
00 .. 59
*/
00 .. 59
*/
00 .. tsec-1 */
tick/second */
Description
Stores the current time
of
day
in
the
buffer.
The
format
is
executive
service.
Bugs
compatible
with the RSX11-M GTIM$
C Compiler and Library
Page
5-39
$$scan
5.32
Formatted input conversion
Formatted input conversion
_________ _____
__________
**********
* $$scan *
**********
File name:
doscan.mac
Usage
$$scan(fmt, args, iov)
char
*fmt;
/* Format string
int
*arg[]; /* Arg vector
FILE
*iov;
/* File descriptor
*/
*/
*/
Description
$$scan()
does
parsing
for
scanf(),
etc.
See
the
description of scanf() for more details.
Bugs
$$scan() is
functionally
identical
to
the
_doscan()
routine
in Unix and Vax-11 C libraries.
Unfortunately,
the leading '_' conflicts
name
conventions.
with
RSX
FCS
library
C Compiler and Library
Page
5-40
$$svr1
Save registers r1-r5 on the stack
5.33 Save registers r1-r5 on the stack
_________ _____ __ ___ _____
____
**********
* $$svr1 *
**********
File name:
savr1.mac
Usage
jsr
...
return
caller
r5,$$svr1
;Save r1-r5 on the stack
;Restore r1-r5 and return to
Description
Save general registers r1-r5 on the stack and return
to
the
caller.
When
the
caller executes an return
(rts
pc), it will cause the original r1-r5 to be restored
and
the program will return to the original caller.
On return, the caller's registers are as follows:
R1
R2
R3
R4
R5
PC
02(SP)
04(SP)
06(SP)
10(SP)
12(SP)
14(SP)
Return to original user
Bugs
Except for the C-bit, condition codes are not
preserved.
C Compiler and Library
Page
5-41
$$tens
Conversion table for dtoa, atof
5.34 Conversion table for dtoa, atof
_____ ___ _____ ____
**********
* $$tens *
**********
File name:
doutab.mac
Usage
extern double $$tens[];
Description
$$tens[i] has 10^i for the range 0..35
__________
C Compiler and Library
Page
5-42
$$utim
Convert $$rtim buffer to Unix time
5.35 Convert $$rtim buffer to Unix time
______ ______ __ ____ ____
_______
**********
* $$utim *
**********
File name:
utime.mac
Usage
long
$$utim(buffer);
struct TIME {
int
int
int
int
int
int
int
int
} buffer;
year;
month;
day;
hour;
minute;
second;
tick;
tsec;
/*
/*
/*
/*
/*
/*
/*
/*
G.TIYR
G.TIMO
G.TIDA
G.TIHR
G.TIMI
G.TISC
G.TICT
G.TICP
year - 1900
Jan. = 1
*/
*/
*/
00 .. 23
*/
00 .. 59
*/
00 .. 59
*/
00 .. tsec-1 */
tick/second */
Description
The user calls $$rtim() to initialize a
buffer.
Then,
$$utim
will
convert
buffer
contents to the number
of
seconds since Jan 1, 1970.
Note:
$$utim() does not compensate for
timezone
or daylight savings time.
Bugs
This routine works only in the range:
1970 <= year < 2100
local
C Compiler and Library
Page
5-43
abort
Abort program with a BPT trap
5.36 Abort program with a BPT trap
_______ ____ _ ___ ____
_____
*********
* abort *
*********
File name:
abort.mac
Usage
abort()
Description
After closing all files, the program exits by
executing
a BPT trap.
Bugs
C Compiler and Library
Page
5-44
abs
5.37
Integer absolute value
Integer absolute value
_______ ________
_____
*******
* abs *
*******
File name:
abs.mac
Usage
abs(val)
int
val;
Description
Return absolute value of the integer argument.
Bugs
C Compiler and Library
Page
5-45
alloc
5.38
Allocate memory
Allocate memory
________ ______
*********
* alloc *
*********
File name:
alloc.mac
Usage
char *
alloc(n);
/*
-1 if no space
*/
Description
Allocate the requested
number
of
bytes,
returning
a
pointer
to
the
first.
The
program
image
will
be
expanded as needed.
alloc() returns -1 if the requested space could
not
be
allocated.
free() is used to return the buffer to free space.
See also the
description
of
malloc(),
realloc()
and
sbrk().
Diagnostics
Bugs
alloc() is obsolete.
Use malloc() for new programs.
C Compiler and Library
Page
5-46
ascr50
Ascii to Radix-50 conversion
5.39 Ascii to Radix-50 conversion
________ __________
_____ __
**********
* ascr50 *
**********
File name:
ascr50.mac
Usage
ascr50(count, input, output)
int
count;
int
*output;
char
*input;
Description
Convert 'count' characters from ascii to Radix
50.
If
there
aren't
a
multiple
of
3 characters, blanks
are
padded on the end.
The ascii string
is
moved
to
the
output when finished.
The input and output areas may
be
the same since three input characters are read for
every
two bytes of output.
Bugs
C Compiler and Library
Page
5-47
asl$l
5.40
Shift long << long
Shift long << long
_____ ____ __ ____
*********
* asl$l *
*********
File name:
asll.mac
Usage
long
asl$l(l, n)
long
long
l;
n;
long
asr$l(l, n)
long
long
l;
n;
Description
Performs shifting of long by long.
Only
the
low-
order
six
bits
of
the shift argument are examined.
is
compatible with the hardware ASH instruction.
Note that, if n is negative:
(l << n) == (l >> (-n))
Bugs
This
C Compiler and Library
Page
5-48
asl$li
5.41
Shift long << integer
Shift long << integer
_____ ____ __
_______
**********
* asl$li *
**********
File name:
aslli.mac
Usage
long
asl$li(l, n)
long
int
l;
n;
long
asr$li(l, n)
long
int
l;
n;
Description
Performs
arithmetic
shifting
for
integer
shift
arguments.
Note that only the low-order six bits of
the
shift argument are examined.
This
with
the hardware shift instruction.
Bugs
is
compatible
C Compiler and Library
Page
5-49
asr$u
Right shift unsigned >> integer
5.42 Right shift unsigned >> integer
_____ ________ __ _______
_____
*********
* asr$u *
*********
File name:
asru.mac
Usage
unsigned
asr$u(u, n)
unsigned
int
u;
n;
Description
Performs u >> n for
unsigneds.
Note
that,
if
is
negative, it acts as if (u << (-n)) were executed.
Bugs
n
C Compiler and Library
Page
5-50
atod
Convert Ascii to double floating
5.43 Convert Ascii to double floating
_____ __ ______ ________
_______
********
* atod *
********
File name:
atod.mac
Usage
double
atod(buffer)
char
*buffer;
Description
Converts
a
double-precision
floating
point
number
written
in scientific notation from ASCII to a
number.
The BNF for numbers which can decoded
"double"
by
this
routine follows:
<number> := <sign> <real number>
<real number> :=
<decimal number>
| <decimal number> <exponent>
| <exponent>
<decimal number> :=
<integer>
| <integer> .
| . <integer>
| <integer> . <integer>
<integer> := <digit> | <integer> <digit>
<exponent> :=
{ E | e | D | d } <sign> <integer>
<digit> := 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
<sign> := + | - | <empty>
The conversion stops on the first
character.
non-legal
(Note:
if this routine is declared type char *, it
will
return a pointer to the first non-legal character.)
Bugs
Internal
If
the
C
library
is
compiled
using
"inline
EIS"
(C$$EIS=1), hardware floating point is also required.
Note:
module.
This routine uses the table in the DOUTAB
C Compiler and Library
Page
5-51
atof
Convert Ascii to double floating
5.44 Convert Ascii to double floating
_____ __ ______ ________
_______
********
* atof *
********
File name:
atof.mac
Usage
double
atof(buffer)
char
*buffer;
Description
Converts
a
double-precision
floating
point
number
written
in scientific notation from ASCII to a
number.
The BNF for numbers which can decoded
"double"
by
this
routine follows:
<number> := <sign> <real number>
<real number> :=
<decimal number>
| <decimal number> <exponent>
| <exponent>
<decimal number> :=
<integer>
| <integer> .
| . <integer>
| <integer> . <integer>
<integer> := <digit> | <integer> <digit>
<exponent> :=
{ E | e | D | d } <sign> <integer>
<digit> := 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
<sign> := + | - | <empty>
The conversion stops on the first
character.
non-legal
(Note:
if this routine is declared type char *, it
will
return a pointer to the first non-legal character.)
Bugs
Internal
If
the
C
library
is
compiled
using
"inline
EIS"
(C$$EIS=1), hardware floating point is also required.
Note:
module.
This routine uses the table in the DOUTAB
C Compiler and Library
Page
5-52
atofd
Convert ASCII to floating -- dummy
5.45 Convert ASCII to floating -- dummy
_____ __ ________ __ _____
_______
*********
* atofd *
*********
File name:
atofd.mac
Usage
double
atof(buffer)
char
*buffer;
Description
This is a dummy routine that is always
present
in
the
Decus
C
run-time
library.
If
a program attempts
to
convert an ASCII string to a floating
point
value
(by
calling
scanf()
with
a
'%f'
format
effector),
the
program will crash.
If floating point conversion is needed,
the
conversion
routine
must be named in the link or task-build
command
line as follows:
RSX: TKB file=file,c:atof,c:c/lb
RT11: LINK file,c:atof,c:suport,c:clib/bot:2000
Bugs
C Compiler and Library
Page
5-53
atoi
5.46
Convert Ascii to integer
Convert Ascii to integer
_______ _____ __
_______
********
* atoi *
********
File name:
atoi.mac
Usage
atoi(p)
char
*p;
Description
Convert
string
to
integer.
No
data
checking
is
performed.
The
conversion
non-integer.
Leading spaces,
stops
at
the
first
tabs,
plus-signs
and/or
newlines are ignored.
a
minus sign.
Bugs
The integer may be preceeded by
C Compiler and Library
Page
5-54
atol
5.47
Convert Ascii to long
Convert Ascii to long
_______ _____ __
____
********
* atol *
********
File name:
atol.mac
Usage
long
atol(p)
char
*p;
Description
Convert
string
to
integer.
No
data
checking
is
performed.
The
conversion
non-integer.
Leading spaces,
stops
at
the
first
tabs,
plus-signs
and/or
newlines are ignored.
a
minus sign.
Bugs
The integer may be preceeded by
C Compiler and Library
Page
5-55
brk
5.48
Change memory allocation
Change memory allocation
______ ______
__________
*******
* brk *
*******
File name:
brk.mac
Usage
char *
brk(addr);
int
*addr;
Description
brk()
sets
the
run-time
library's
"top
of
memory"
pointer
to
addr.
This value should have been
returned
by a previous call
to
sbrk().
Intervening
calls
malloc()
open routines may cause memory to
to
or
file
be
corrupted by calling brk().
Diagnostics
Returns 0 if the brk() argument is reasonable.
Returns
-1
if
it
is
greater
than the current top of
memory.
(Use sbrk() to increase memory allocation.)
Bugs
C Compiler and Library
Page
5-56
call
Call (Fortran) subroutine from C
5.49 Call (Fortran) subroutine from C
_________ __________ ____ _
____
********
* call *
********
File name:
call.mac
Usage
return_value = call(routine, count, &arg1, ... &argN);
extern int routine();
/* PDP-11 function name */
int
count;
/* Number of arguments */
Description
C Library user-callable interface between C programs
and
subroutines
which
follow
the
standard
PDP11
calling
sequence.
Note that call() saves and restores
registers
r2-r5.
The arguments are as follows:
routine
The name of the PDP11 routine
to
be called.
count
The number of arguments
the
calling sequence.
arg1
The first argument.
For example:
extern int
int
int
sort();
data_to_sort[NDATA];
ndata = NDATA;
in
call(sort, 2, &data_to_sort, &ndata);
Note that, if the called
function
returns
some
other
datatype
such as a long, the routine and call() must
be
correctly declared:
long
long
long
long
call();
myfun();
larg;
result;
result = call(myfun, 1, &larg);
C Compiler and Library
Page
5-57
call
Call (Fortran) subroutine from C
If call() is being
used
to
return
several
different
datatypes, type coersion may be effective:
int
long
long
long
call();
myfun();
larg;
result;
result = (long)call(myfun, 1, &larg);
Bugs:
WARNING:
watch out for trouble if
the
PDP-11
routine
does
any
I/O.
been
implemented.
Floating-point data return has not
C Compiler and Library
Page
5-58
callc
Call (Fortran) subroutine from C
5.50 Call (Fortran) subroutine from C
_________ __________ ____ _
____
*********
* callc *
*********
File name:
callc.mac
Usage
integer callc
ivalue = callc(routine, arg1, ... argN)
Description
User-callable interface
between
Fortran
programs
and
subroutines written in C.
The arguments are as follows:
routine
The name of the C routine to
be
called.
arg1
The
(location
of
the)
first
argument.
For example:
call callc(sort, table, nelement)
Bugs
There will be I/O library conflicts since C
files
have
not been initialized.
The following problem will occur if a
is
C
subroutine
called from a Fortran main program:
The C subroutine refers to
the
save
register
routine
(CSV$)
which
refers to the C main program.
This
pulls
in a large amount of I/O dependent code, which may
cause
conflicts.
What is worse is that there will be two main programs.
It is therefore recommended
that
there
be
a
C
main
program
that
calls
Fortran
in
turn, call C subroutines.
subroutines
that may,
C Compiler and Library
Page
5-59
callc
Call (Fortran) subroutine from C
The programmer can also
define
a
dummy
program
that
resolves
the
globals
referenced
by
CSV$
modify
callc.mac to provide the necessary globals.
or
C Compiler and Library
Page
5-60
caller
Return name of profiled caller
5.51 Return name of profiled caller
__ ________ ______
______ ____
**********
* caller *
**********
File name:
caller.mac
Usage
char
*
caller();
Description
If the routine which called
the
current
function
was
compiled
using
the
profile option, caller() returns
a
pointer to the name of the
calling
function.
If
the
calling
function
was
not
compiled
with
profiling
enabled, a pointer to the null string is returned.
Example:
foo()
{
foobar();
}
foobar()
{
extern char *caller();
printf("foobar was called by %s\n",
caller());
}
Internal
Warning -- this routine is sensitive to
the
format
of
the
environment
frame
and profile information
layout.
If csv$, pcsv$, or $$prof change, this may
be
modified.
Bugs
have
to
C Compiler and Library
Page
5-61
calloc
Allocate and Initialize Memory
5.52 Allocate and Initialize Memory
___ __________ ______
________
**********
* calloc *
**********
File name:
calloc.mac
Usage
char *
calloc(n, m);
int
int
/* NULL if no space
/* Number of elements
/* Size of an element
n;
m;
*/
*/
*/
Description
Calloc() allocates space for n elements,
each
m
bytes
long.
On
return,
the
space is zero'ed.
The
program
image will be expanded as needed.
If the requested space
cannot
be
allocated,
calloc()
returns NULL.
See also the
description
of
malloc(),
and
sbrk().
The space is returned by calling free().
Diagnostics
Bugs
realloc()
C Compiler and Library
Page
5-62
calltr
5.53
Trace Path to the Caller
Trace Path to the Caller
_____ ____ __ ___
______
**********
* calltr *
**********
File name:
calltr.mac
Usage
calltrace(outfd);
FILE
*outfd;
Description
calltrace() prints the calling path (from main()) to
the
routine
that called calltrace()) on the indicated
file.
The path is printed on one line as:
[ main sub1 sub2 ]
If a subroutine within the path was
not
compiled
with
profiling,
or
does
not
start
with
a
call to the
C
register register save routine, it will
be
printed
as
<nnnnnn>
(where
<nnnnnn>
is
the octal address of
the
entry to the routine).
Note that the last entry on
the
line is the routine that invoked calltrace().
A call trace will be printed on
exit
if
profiling
is
enabled and the program aborts or calls error().
Internal
Warning -- this routine is sensitive to
the
format
of
the
environment
frame
and profile information
layout.
If csv$, pcsv$, or $$prof change, this may
have
to
be
modified.
A special entry for error() is
provided,
which
allows
the
proper
"bug"
address to be displayed, rather
than
the return address of error() itself.
Bugs
C Compiler and Library
Page
5-63
clearerr
5.54
Clear file error flags
Clear file error flags
_____ ____ _____
_____
************
* clearerr *
************
File name:
cleare.mac
Usage
clearerr(iop);
FILE
*iop;
Description
Clear the error flags for an open
file.
This
be
needed for interaction with the user's console
terminal.
Bugs
may
C Compiler and Library
Page
5-64
concat
5.55
Concatenate strings
Concatenate strings
___________ _______
**********
* concat *
**********
File name:
concat.mac
Usage
char *
concat(out, in0, in1, ..., inN, 0);
char
*out;
char
*in0, in1, ... inN;
Description
Concat concatenates the argument strings.
a
pointer to the first byte of out.
Bugs
It returns
C Compiler and Library
Page
5-65
copy
Copy a given number of bytes
5.56 Copy a given number of bytes
______ __ _____
____ _ _____
********
* copy *
********
File name:
copy.mac
Usage
char *
copy(out, in, nbytes)
char
*out;
char
*in;
unsigned int
count;
/* Output vector
/* Input vector
/* Bytes to copy
*/
*/
*/
Description
Copy the indicated number of bytes from the
input
area
to
the output area.
Return a pointer to the first
free
byte in the output area.
The copying will be faster if out and in are either
both
even or both odd addresses.
Bugs
C Compiler and Library
Page
5-66
cpystr
5.57
String copy
String copy
______ ____
**********
* cpystr *
**********
File name:
cpystr.mac
Usage
char *
cpystr(out, in);
char
*out;
char
*in;
Description
Copy "in" to "out".
Return a pointer to the end of
out.
This allows the following usage:
char
char
extern char
*ptr;
buffer[BUFSIZ];
*cpystr();
ptr = cpystr(buffer, text);
ptr = cpystr(ptr, more_text);
The above sequence appends more_text to the copy of
text
already moved into the buffer.
Bugs
C Compiler and Library
Page
5-67
csv$
C register save and restore
5.58 C register save and restore
____ ___ _______
_ ________
********
* csv$ *
********
File name:
csv.mac
Usage
jsr
...
jmp
r5,csv$
cret$
Description
C program Run-time Environment
Each C subroutine starts with a call to CSV$
and
exits
by
jumping
to CRET$.
Upon exit, the stack need not
be
equal to its value on entrance.
During the execution of all C subroutines,
register
R5
points
to
the
current
"environment."
Within
a
subroutine, it appears as follows:
_______________
|
|
SP -> | 1st loc. var. | -10(R5)
|_______________|
|
|
| Saved R2
| -6(R5)
|_______________|
|
|
| Saved R3
| -4(R5)
|_______________|
|
|
| Saved R4
| -2(R5)
C$AUTO-2(R5)
|_______________|
|
|
R5 -> | Saved R5
|
|_______________|
|
|
| Return add.
|
|_______________|
|
|
| First arg.
|
|_______________|
|
|
+2(R5)
+4(R5)
C$PMTR+0(R5)
C Compiler and Library
Page
5-68
csv$
C register save and restore
| Second arg.
|
|_______________|
+6(R5)
C$PMTR+2(R5)
Within a subroutine, Registers R0-R4 and the top of
the
stack,
(sp) are available for use.
Registers R0 and
R1
are not preserved by subroutines and may be used to
pass
a return value.
R5 must not be modified by a subroutine.
All
variable
addressing
must
be
done by offsets to R5.
Subroutine
arguments must
be
accessed
by
reference
to
C$PMTR.
Subroutine local variables must be accessed by
reference
to
C$AUTO.
This
permits
modification
of
calling
sequences without rewriting all subroutines.
CSV$ refers to global symbol $$main to call the runtime
startup program from the (RSX) library.
Internal
The
global
symbols
needed
C
compiler are also included.
Bugs
for
the
Whitesmith's
C Compiler and Library
Page
5-69
ctime
5.59
_____ __ _____
Convert time value to ascii
Convert time value to ascii
_______ ____
*********
* ctime *
*********
File name:
ctime.mac
Usage
#include <time.h>
char *
ctime(tvecp)
long
*tvec;
/* Time value pointer
*/
char *
asctime(tm)
struct tm
*tm;
/* Time buffer pointer
*/
Description
ctime() converts a time value, as returned by time()
to
an
ascii
string.
For
compatibility
with
previous
versions, ctime(0) obtains and converts the current
time
of day.
Note, however, that ctime(0) is not portable.
asctime()
converts
a
time
vector,
as
returned
by
localtime() to an ascii string.
The string is statically allocated.
It has the format
Sun Sep 16 01:03:52 1973\n\0
012345678901234567890123 4 5
0
1
2
All the fields
the
have
constant
width.
To
remove
trailing newline, just:
char
extern char
int
*tp;
*ctime();
tvec[2];
time(&tvec);
tp = ctime(&tvec);
tp[24] = '\0';
Bugs
/* Get time
/* in Ascii
/* Fix newline
*/
*/
*/
C Compiler and Library
Page
5-70
ctime
Convert time value to ascii
There is no range checking on the information passed.
C Compiler and Library
Page
5-71
ctype
Character classification type table
5.60 Character classification type table
_________ ______________ ____ _____
*********
* ctype *
*********
File name:
ctype.mac
Usage
#include <ctype.h>
mov
jmp
#MASK,r0
$$ctype
Description
This module contains the bit-mask table and common
code
for the is...
and to...
functions.
Bugs
No provisions are made for national letters.
Maintainers note that
is
included.
source
for
a
test
program
C Compiler and Library
Page
5-72
ddtoa
Convert floating to ASCII -- dummy
5.61 Convert floating to ASCII -- dummy
________ __ _____ __ _____
_______
*********
* ddtoa *
*********
File name:
dtoad.mac
Usage
$$dtoa(buff, value, field, dplace)
char
*buff;
/* Where it goes
double value;
/* What to convert
int
field;
/* Maximum field width
int
dplace;
/* Decimal part width
*/
*/
*/
*/
Description
This is a dummy routine that is always
present
in
the
Decus
C
run-time
library.
If
a program attempts
to
convert a floating point
value
to
ascii
(by
calling
printf()
with a '%f' format effector), an error
message
will be generated.
If floating point conversion is needed,
the
conversion
routine
must be named in the link or task-build
command
line as follows:
RSX: TKB file=file,c:dtoa,c:c/lb
RT11: LINK file,c:dtoa,c:suport,c:clib/bot:2000
Bugs
C Compiler and Library
Page
5-73
delete
5.62
Delete a named file
Delete a named file
______ _ _____ ____
**********
* delete *
**********
File name:
delete.mac
Usage
delete(filename)
char
*filename;
Description
Delete the named file.
Returns 1 on success, 0 on
error
(such
as
file
not found).
If an error occurs,
$$ferr
can be checked for the error code.
On RSX modes, the filename as passed need not include
an
explicit
version
number.
file.nam;0 will be
deleted.
If
none
is
Note
that
the
provided,
filename
returned
by
fgetname()
always
includes
an
explicit
version.
On RT modes, the only error ever returned is
"File
not
found".
Bugs
On RSX/VMS, the file must be in the user's current
("SET
DEFAULT") directory.
On RSTS, "SY0:" cannot be distinguished from "SY:".
C Compiler and Library
Page
5-74
div$li
5.63
___ _______
Long division and modulus
Long division and modulus
____ ________
**********
* div$li *
**********
File name:
divl.mac
Usage
div$li(long, integer)
div$l(long, long)
mod$li(long, integer)
mod$l(long, long)
Description
Division with long result.
Called by the compiler
when
the appropriate code sequences are encountered.
Bugs
Warning -- an internal
present.
Change one, change both.
version
of
cret$
is
C Compiler and Library
Page
5-75
eis$i
5.64
EIS emulator module
EIS emulator module
___ ________ ______
*********
* eis$i *
*********
File name:
eis.mac
Usage
asl$i(a,
asr$i(a,
mul$i(a,
div$i(a,
mod$i(a,
b);
b);
b);
b);
b);
/*
/*
/*
/*
/*
Execute
Execute
Execute
Execute
Execute
a
a
a
a
a
<< b
>> b
* b
/ b
% b
*/
*/
*/
*/
*/
Description
All arguments are integers.
These routines
are
called
by the C compiler to perform the indicated operations.
The module may be conditionally
compiled
to
generated
hardware
EIS
operations.
Edit RT11.MAC or RSX.MAC
to
define C$$EIS as needed:
0
1
Emulate EIS operations
Generate EIS operations
C$$EIS is defaulted zero for RT11, non-zero for RSX.
If n is negative, x << n == x >> (-n) and v.v.
Note:
div$i returns the remainder in r1.
This
may
be
useful for assembly-language programs that need both
the
quotient and remainder.
To
overlay
explicitly
position
this
module
in
an
structure, refer to the title, EIS$I.
Bugs
Divide
by
and
remainder.
zero
yields
zero
for
the
quotient
C Compiler and Library
Page
5-76
envsave Multi-level function return
5.65 Multi-level function return
________ ______
___________
***********
* envsave *
***********
File name:
envset.mac
Usage
int *
envsave();
envreset(frame,
int
int
int
hval, lval)
*frame; /* Frame pointer
hval;
/* High-order return
lval;
/* Low-order return
*/
*/
*/
Description
These functions permit a multi-level
return
from
a
C
function to one of its dynamic ancestors in the stack.
Envsave() returns
the
address
of
the
frame
of
its
caller.
Later calls to envreset() with this pointer
as
an argument will
create
the
illusion
that
the
last
function
invoked
by
the
caller of envsave()
returned
directly with a
value
equal
to
the
parameter(s)
to
envreset().
Envreset() simulates a
return
to
the
function
whose
frame
pointer
matches
frame (the result of a
previous
call to envsave()).
as
Envreset() may be made to
look
if
it
is returning a one or two word value.
If only
a
single
integer
value
is
passed
in
addition
to
envreset(),
it looks as if a 1-word value was
returned.
If two integers (or equivalently, a long) are
specified,
it
looks like a long is returned.
Thus any 1 or 2
word
value may be returned because of the lax
type
checking
in C.
It is catastrophic to attempt to return
to
a
function
which has itself already returned!!!
The
following
illustrates
and
envreset():
int
*save_frame;
use
of
envsave()
C Compiler and Library
Page
5-77
envsave Multi-level function return
process() {
...
save_frame = envsave();
if (subroutine()) {
/*
* Success
*/
}
else {
/*
* Failure
*/
}
}
subroutine() {
/*
* Abort on error
*/
if (...)
envreset(save_frame, 0)
/*
* Success
*/
return(1);
}
When subroutine() detects an error, it calls
envreset()
to
return
to
the
caller
of
process(),
passing
a
"failure" flag.
Bugs
If
the
caller
of
envsave()
has
already
returned,
disaster will result.
It
is
highly
recommended
use
setjmp/longjmp instead.
that
programs
C Compiler and Library
Page
5-78
error
5.66
Error exit from C programs
Error exit from C programs
_____ ____ ____
_ ________
*********
* error *
*********
File name:
error.mac
Usage
error(format, arglist); /* Fatal error exit
*/
Description
An error message is written to stderr
and
the
exits.
a subroutine
program
If
profiling
was
enabled,
call
trace will be written to stderr.
The exit status, $$exst, will be set to "error".
Diagnostics
Bugs
C Compiler and Library
Page
5-79
exit
5.67
Exit from C programs
Exit from C programs
____ ____ _ ________
********
* exit *
********
File name:
exit.mac
Usage
exit(status);
/* Exit, no return
*/
exits(status);
/* Exit with status
*/
$$fail();
/* Immediate exit
*/
extern int $$exst;
/* Exit status value
*/
Internal
jmp
$$exit
;Call exit routine
Description
On exit, the following sequence occurs:
1.
The user-supplied wrapup() function is called.
2.
User-supplied finalizers are called.
3.
Profiles (if requested) are printed.
4.
All files are closed.
5.
The program exits to the operating system.
By
calling
exits()
with
an
appropriate
value,
the
program
can
pass
an exit status code to the
operating
system monitor.
The RT11 and RSX11 monitors define
exit
status
codes
differently;
the value passed to
exits()
is not checked for consistancy.
RT11
1.
RSX
1.
Meaning
IO_SUCCESS -- no message is printed
2.
4.
8.
0.
2.
4.
IO_WARNING -- minor error
IO_ERROR
-- serious error
IO_FATAL
-- severe error
Calling exit() with some other value
is
equivalent
to
calling exits(IO_SUCCESS).
This is compatible with
Unix
programs that exit by calling exit() without
parameters.
Note that the program may also set a value
$$exst
and exit via exit():
into
C Compiler and Library
Page
5-80
exit
Exit from C programs
extern int $$exst;
...
$$exst = IO_WARNING;
exit();
If the program calls,
or
jumps
to,
$$fail,
it
will
immediately exit to the operating system without
closing
files, calling wrapup()
a
profile file.
Diagnostics
Bugs
or
finalizers,
or
writing
C Compiler and Library
Page
5-81
fabs
5.68
Floating absolute value
Floating absolute value
________ ________
_____
********
* fabs *
********
File name:
fabs.mac
Usage
double
fabs(val)
double
val;
Description
Return absolute value of a floating argument.
Bugs
C Compiler and Library
Page
5-82
fclear
5.69
Clear file error flags
Clear file error flags
_____ ____ _____
_____
**********
* fclear *
**********
File name:
fclear.mac
Usage
fclear(iop);
FILE
*iop;
Description
Clear the error flags for an open
file.
This
be
needed for interaction with the user's console
terminal.
Bugs
may
C Compiler and Library
Page
5-83
fclose
Close a currently-open file
5.70 Close a currently-open file
______________ ____
_____ _
**********
* fclose *
**********
File name:
fclose.mac
Usage
fclose(iop);
FILE
*iop;
Internal
mov
mov
call
#iov,r4
<signal>,r0
$$clos
;r4 -> i/o vector
;r0 == 0 to free i/o vector
;close file.
mov
mov
call
#iov,r4
<signal>,r0
$$fcls
;r4 -> i/o vector
;r0 == 0 to free i/o vector
;Free buffer space
Description
Close the file.
Returns 0 if ok, -1 if an
error.
The
error code is saved in $$ferr.
Note that stderr is never
closed.
On
RT11-mode,
the
last
block
of a disk file which was open for output
is
filled with nulls.
Internal
$$clos is called internally to close a file.
$$fcls is called internally to free buffer space.
After
the
file
has
been
closed,
record
buffers
(RSX-mode)
and the file-name buffer (RT11-mode) will
be
freed.
If r0 is zero on entry, the iov and any wild-card
buffer
will
also
be
freed.
This
flag
is
set non-zero
by
freopen() or fnext() to close a file without freeing
the
iov.
Bugs
C Compiler and Library
Page
5-84
feof
5.71
Test for end of file
Test for end of file
____ ___ ___ __ ____
********
* feof *
********
File name:
feof.mac
Usage
feof(iop);
FILE
*iop;
Description
Return 1 if end of file on iop, else zero.
Bugs
C Compiler and Library
Page
5-85
ferr
5.72
Test for file error
Test for file error
____ ___ ____ _____
********
* ferr *
********
File name:
ferr.mac
Usage
ferr(iop);
FILE
*iop;
Description
Return 1 if an error has
been
indicated
file.
Bugs
Obsolete, use ferror() instead.
seen
on
the
C Compiler and Library
Page
5-86
ferror
5.73
Test for file error
Test for file error
____ ___ ____ _____
**********
* ferror *
**********
File name:
ferror.mac
Usage
ferror(iop);
FILE
*iop;
Description
Return 1 if an error has
indicated
file.
Bugs
been
seen
on
the
C Compiler and Library
Page
5-87
fflush
5.74
Flush output buffers
Flush output buffers
_____ ______ _______
**********
* fflush *
**********
File name:
fflush.mac
Usage
fflush(iop);
FILE
*iop;
Description
Flush output buffers.
This routine actually
I/O.
$$ferr is set if anything unexpected happens.
Bugs
does
C Compiler and Library
Page
5-88
fget
5.75
Input a binary record
Input a binary record
_____ _ ______
______
********
* fget *
********
File name:
fget.mac
Usage
fget(buffer, maxbytes, iop);
char
*buffer;
int
maxbytes;
FILE
*iop;
Description
Read a record from the indicated file.
Maxbytes is
the
maximum record size.
On RSX, the record is read by a direct call to the
file
service
GET$
routine.
Your program must not mix
calls
to fget() with calls to
other
I/O
routines,
such
as
fgets().
On RT11, the file must have been written by fput().
The actual number of bytes read is returned.
Use
feof()
to test for end of file.
Fget() is not present on Unix standard I/O libraries.
Internal
On RT11, when the record is written
is
by
fput(),
it
preceeded
by
a two-byte byte count.
This value is
one
greater than the number of bytes in the record.
a
zero count is read, it will mean "end of file.")
Bugs
(If
C Compiler and Library
Page
5-89
fgetname
5.76
____ __ _____
Convert file name to Ascii
Convert file name to Ascii
_______ ____
************
* fgetname *
************
File name:
fgetna.mac
Usage
char *
fgetname(iop, buffer);
FILE
*iop;
char
*buffer;
Description
Convert the file name to Ascii and put it in the
buffer.
On native RSX (and RSTS/E emulation)
the
device
name,
file
name,
file
type,
and
version
are converted
to
Ascii.
The UIC is converted if
it
was
specified
and
differs
from
the job's default UIC.
(Note that on
VMS
compatibility mode, the UIC is unavailable.) The
version
is
converted
to
octal on native RSX and to decimal
on
VMS emulation.
The
result
should
be
sufficient
to
delete the file.
On RT11 modes, the file name passed to fopen() is
copied
to
the
buffer without further processing.
If the
file
was opened by an fwild()/fnext() sequence,
correct
the
file
name is returned.
(On RSTS/E, the PPN is
returned
as well.)
Fgetname() returns a pointer to the buffer argument.
Fgetname() is present in the Vax-11 C
support
library,
but is not generally present on Unix implementations.
Note that
fgetname()
returns
a
fully-qualified
file
specification
including,
where
possible,
the
disk,
directory, and version of the file.
If only the
actual
file
name
is needed, the following code segment may
be
executed.
As
shown,
it
writes
the
file
and
filetype (extension) to a global "buffer".
getfilename(fd, buffer)
FILE
*fd;
register char
*buffer;
name
C Compiler and Library
Page
5-90
fgetname
Convert file name to Ascii
{
register char *tp;
register char c;
fgetname(fd, buffer);
/*
* Skip over node and device name
*/
while ((tp = strchr(buffer, ':')) != NULL)
strcpy(buffer, tp + 1);
/*
* Skip over [UIC] or [PPN] if present
*/
c = EOS;
switch (*tp) {
case '[':
c = ']'; break;
case '(':
c = ')'; break;
case '<':
c = '>'; break;
}
if (c != EOS
&& (tp = strchr(buffer, c)) != NULL) {
strcpy(buffer, tp + 1);
/*
* Don't include version
*/
if ((tp = strchr(buffer, ';')) != NULL)
*tp = EOS;
}
Bugs
Various operating systems behave differently.
C Compiler and Library
Page
5-91
fgets
5.77
____ _ ____
Read a string from a file
Read a string from a file
____ _ ______
*********
* fgets *
*********
File name:
fgets.mac
Usage
char *
fgets(buffer, maxbytes, iop);
char
*buffer;
int
maxbytes;
FILE
*iop;
char *
fgetss(buffer, maxbytes, iop);
char
*buffer;
int
maxbytes;
FILE
*iop;
Description
Fgets()
reads
a
string
into
the
buffer
from
the
indicated file.
Maxbytes is the maximum number of
to
string
bytes
read.
The
is
terminated
by
a
newline
character,
which
is
followed
by
a
null.
Fgets()
normally returns buffer.
It returns NULL on end of
file
or
error.
If
the line being read is maxbytes long
or
longer, no newline is appended.
Fgetss()
is
identical
to
fgets()
except
that
the
terminating
is
newline
is
replaced
by a null.
(This
compatible with gets(), but fgetss() is not
present
in
the Unix standard library.)
Note that fgets keeps the newline,
while
fgetss()
and
gets() delete it.
To delete the newline after
executing
fgets(), execute the following:
buffer[strlen(buffer) - 1] = 0;
Bugs
Note that fgets() returns the next
logical
text
line.
Certain
RSX-11
or
RMS
file
formats,
such as
Runoff
output files
or
task-builder
load
maps,
often
have
multiple
record.
text
lines
packed
into
one logical
C Compiler and Library
Page
5-92
fgets
Read a string from a file
Fgets() processes these correctly.
Note, however,
that
the
record
location,
as
returned
by ftell(), is
the
location of the physical
record,
as
returned
by
the
operating system.
The "obvious" ftell/fgets sequence,
rfa = ftell(fd);
fgets(text, sizeof text, fd);
will not work properly if multiple text lines are
packed
into one RSX-11 record.
These routines
do
not
understand
some
of
the
more
baroque
RSX-11
file formats, such as "Fortran
carriage
control" or VMS print-file format.
The typeout
program
in
the tools package, T.C, shows an example of
complete
record deblocking and "seek to byte" procedure.
C Compiler and Library
Page
5-93
fileno
5.78
Get logical unit number
Get logical unit number
___ _______ ____
______
**********
* fileno *
**********
File name:
fileno.mac
Usage
fileno(iop)
FILE
*iop;
Description
Return the logical unit number associated with the
file.
(On RT11, the channel number is returned.)
Bugs
C Compiler and Library
Page
5-94
fill
Fill a Block of Memory With a Character
5.79 Fill a Block of Memory With a Character
____ _ _____ __ ______ ____ _ _________
********
* fill *
********
File name:
fill.mac
Usage
fill(addr, ch, count);
char
*addr;
char
ch;
unsigned int
count;
Description:
Fill the count characters of memory
beginning
addr
with the character ch.
Note:
To fill with zero
zero(),
which is slightly faster.
Bugs
bytes,
you
can
use
at
C Compiler and Library
Page
5-95
flun
5.80
Get logical unit number
Get logical unit number
___ _______ ____
______
********
* flun *
********
File name:
flun.mac
Usage
flun(iop)
FILE
*iop;
Description
Return the logical unit number associated with the
file.
(On RT11, the channel number is returned.)
Bugs
Obsolete -- use fileno() for transportability.
C Compiler and Library
Page
5-96
fmkdl
Mark file for deletion -- obsolete
5.81 Mark file for deletion -- obsolete
____ ___ ________ __ ________
____
*********
* fmkdl *
*********
File name:
fmkdl.mac
Usage
fmkdl(iop);
FILE
*iop;
Description
fmkdl() closes and deletes the specified file.
Returns
0 on success, -1 on error.
This routine is
obsolete.
New
programs
should
call
delete()
instead.
To
delete
an
existing
file,
the
program may execute:
char
buffer[80];
...
fgetname(iop, buffer);
fclose(iop);
delete(buffer);
Bugs
On RT11, the job is aborted with an error message if
the
file
wouldn't parse.
$$ferr is set to "file not
found"
if the program
tries
to
delete
something
(like
the
line-printer)
does
that
it
shouldn't.
Note that RT11
not flush the last buffer before deleting the file.
On VMS compatibility mode,
the
user's default directory.
the
file
must
be
in
C Compiler and Library
Page
5-97
fopen
5.82
C library file opener
C library file opener
_ _______ ____
______
*********
* fopen *
*********
File name:
fopen.mac
Usage
FILE *
fopen(name, mode);
char
*name;
char
*mode;
/* File to open
/* Open modes
*/
*/
FILE *
freopen(name, mode, iop);
char
*name; /* File to open
char
*mode; /* Open modes
FILE
*iop;
/* I/O pointer
*/
*/
*/
Internal
mov
jmp
iov,r4
$$fopn
;r4 -> iov
;Open the file and return to the
;caller via $$fopx or $$fope if error.
;On RSX, fixup append mode if the file
;wasn't found.
mov
call
iov,r4
$$fopo
;r4 -> iov
;Normal open, then exit via $$fopx
;On RSX, $$fopo returns if any error
;occurred. On return, r0 := RSX error
mov
jmp
iov,r4
$$fopx
;r4 -> iov, file is open
;Normal exit from fopen
;On RSX, $$fopx allocates the record
;buffer.
mov
mov
iov,r4 ;r4 -> iov (or r4 == 0)
code,r0 ;r0 := error code (to go to $$ferr)
code.
jmp
$$fope
;Error exit from fopen
;$$fope deallocates buffers
Description
Fopen opens a new or
indicated
mode:
existing
file
in
the
C Compiler and Library
Page
5-98
fopen
C library file opener
r
w
a
n
u
Read the existing file sequentially
Create and write the file sequentially
Append to the file
Not record oriented
RSX-mode "unbuffered i/o"
RT11-mode: use .ttyin and .ttyout
Either "r", "w", or "a" must be given.
"n" and "u"
are
optional.
"n" should be given for "binary" files.
Note
that "n" mode will create
fixed-block
records
on
RSX
systems.
Append mode does not work on native RT11.
Note that "n" and "u" are not compatible with other
Unix
systems.
Implementation Details
On
RSX,
"u"
mode
files
will
be
created
with
the
"variable-length"
attribute.
On
RSTS/RSX
emulation,
text files (neither
"n"
nor
"u"
specified)
will
be
created with "stream" attribute.
On RSX, if the record type bits in the record
attribute
byte
(F.RATT in the FDB) is zero, the file will be
read
as if the "n" was specified.
Note
that,
if
the
file
contains carriage-return line-feed sequences, the
entire
sequence will be
passed
to
the
user's
program.
If
record
attributes
are
understandable,
the
carriage-return will be deleted from <CR><LF>
sequences.
On RSX, if the "file" is being opened for write
the
to
same
device/unit
as
stderr
(the
user's
"command
console), the character stream is
diverted
to
stderr.
This
avoids
synchronization problems by funnelling
all
output through the same buffer.
In addition, output
to
any
terminal
device is done via QIO's to the
terminal,
IO.WLB for normal mode, IO.WAL for "n" mode.
On RT11, when opening a file
for
writing,
a
specific
block
allocation
may
be
included
in
the Ascii
file
specification
following
standard
RT-11
syntax:
"DKn:file.nam[nnn]" where the "nnn" specifies the
number
of blocks to allocate to the file.
After opening a
file
successfully,
the actual file size (or number of
blocks
allocated) will be found in (FILE *)fd->io_size.
If the RT11 library decides that the file is really
the
user's
command
terminal,
single-character I/O will
be
performed (by calling .ttyin and
.ttyout).
Note
that
the
"special-mode"
bits
must be set in the Job
Status
Word by the program if it requires true singlecharacter
or
immediate return input.
Output to the terminal
will
be performed without
for
buffering,
which
is
useful
C Compiler and Library
Page
5-99
fopen
C library file opener
screen updating, but otherwise expensive.
Fopen() returns NULL on errors -- $$ferr gets
an
error
code.
On
RT11,
this will be a RSTS/E compatible
code
(described in iov), while on RSX, this will be
the
FCS
error code.
On RT11, the file name pointed to by the "io_name"
field
of
the
iov is either the file name string as passed
to
fopen() or an ascii string reconstructed from the 4word
Rad50
device
block if the file was opened as part of
a
fwild/fnext
sequence.
By
saving
the
ascii
string,
RSTS/E
is
able
to
re-parse
logical device names
and
PPN's, which are not present on native RT11.
On VMS compatibility mode, the device and
directory
of
the
file
name argument are saved in the iov
"io_dname"
field for use by fgetname().
Note that "no buffer space available" (IE.NBF or
E$$NSP)
and "invalid lun" (IE.ILU or E$$NOC) may be generated
by
fopen.
On RT11, if the file cannot
be
opened
because
the
user's
program
has already opened the channel,
an
E$$ILU error will be returned.
The same file may not
be
used
for
both
reading
and
writing
except
if the program writes a disk file,
then
repositions and reads it using ftell()/fseek().
In
this
case,
to
the
program should call rewind() or freopen()
reinitialize the file before using fseek().
Except in the one specific
case
of
the
RT11
console
terminal open in "u" mode, an open file must not be
used
for reading and writing at the same time.
Freopen() substitutes the named file
in
place
of
the
open
file -- indicated by iop.
The file currently
open
on iop is closed.
Freopen returns
iop.
If
the
open
failed,
iop
will
be
deallocated.
Note that
freopen
loses any pending fwild/fnext status.
Internal
The
following
routines/globals
are
for
use
by
fopen/fwild.
If any of these routines detect an
error,
they return to the fopen() caller
with
an
appropriate
error code in $$ferr.
$$fope
$$fopn
$$fopx
Warning:
unpublished
fopen()
Error exit from fopen
Normal open, hack append
Normal exit from fopen
in
RSX/RSTS
mode
uses
C Compiler and Library
Page
5-100
fopen
C library file opener
information
to
obtain
the
PPN [UIC] of an open
file.
This code (in iocsi.mac) may
require
modification
for
subsequent releases of RSTS/E.
Bugs
Append mode cannot work on native RT11 given the
design
of the RT11 file system.
The RT11 file system does not support files greater
than
65535 blocks long.
RT11 does not
get
the
actual
keyboard
name
of
the
console
terminal, although this isn't too hard to do
on
RT11/RSTS/E.
Freopen() cannot be used to assign a file to
stderr
as
there
is
code
throughout
the i/o package for
special
treatment of stderr.
For example, it cannot
be
closed
by a user-written program.
In RSX modes, the maximum number of files
that
may
be
simultaneously
open
macro (FSRSZ$)
which
is
defined
at assembly time by
a
is
expanded
when
fopen.mac
is
assembled.
The default FSRSZ$ parameter is 4.
This
may
be modified by using the task builder /ACTFIL=n
option.
The
default
FSRSZ$ value may be specified when the
RSX
library is built by editing assembly parameter N$$FIL
in
RSX.MAC.
Internal
This module contains release-specific code for VMS
V3.0
to enable Decus C programs to read "Ascii stream"
files.
C Compiler and Library
Page
5-101
fprintf Formatted Output Conversion
5.83 Formatted Output Conversion
______ __________
_________
***********
* fprintf *
***********
File name:
fprint.mac
Usage
fprintf(iov, format, arg1, ...);
FILE
*iov;
char
*buffer;
char
*format;
Description
fprintf() converts and formats
its
arguments,
writing
the result to the indicated file.
For information
on
formatting,
the
description of printf.
Bugs
please
refer
to
C Compiler and Library
Page
5-102
fps
Set floating point status (FPS)
5.84 Set floating point status (FPS)
________ _____ ______ _____
___
*******
* fps *
*******
File name:
fps.mac
Usage
#include <fps.h>
fps(status)
unsigned int
status;
Description
This routien sets the floating point
status
by
executing
This allows a
simply
the
LDFPS
instruction.
user
program to switch between roundoff and truncation
modes
or
enable/disable
floating
point
interrupts.
Bit
definitions are in the include file, "fps.h".
For example,
to
enable
rounding
and
all
fpu
error
interrupts except underflow, do the following:
#include <fps.h>
fps(FIUV | FIV | FIC);
Bugs
The C library
doesn't
initialize
the
floating
point
status.
This routine -- with appropriate parameters -
should be in all C main programs that
floating
require
point operations.
C Compiler and Library
Page
5-103
fput
5.85
Output a binary record
Output a binary record
______ _ ______
______
********
* fput *
********
File name:
fput.mac
Usage
fput(buffer, nbytes, iop);
char
*buffer;
int
nbytes;
FILE
*iop;
Description
The specified record is written to the file.
The
file
must
have
been
opened
'n' so newlines aren't
stuffed
here and there.
On RT11, the file is only readable by fget.
Nbytes is always returned.
A call to ferr() after calling fput() is advised.
Bugs
On RT11, file close zeros the current output block.
To
prevent
fget() from reading "zero length" records,
fput
writes "record count + 1" on the file.
C Compiler and Library
Page
5-104
fread
5.86
Input a record
Input a record
_____ _ ______
*********
* fread *
*********
File name:
fread.mac
Usage
int
fread(object, sizeof (*object), nitem, iop)
int
nitem;
FILE
*iop;
Description
Object points to a buffer that is to receive a
specified
number of items from the file.
fread() returns the actual number of items
This
will be zero if an end-of-file or error was
encountered.
Bugs
read.
C Compiler and Library
Page
5-105
frec
Return True if record-oriented file
5.87 Return True if record-oriented file
____ __ _______________ ____
______
********
* frec *
********
File name:
frec.mac
Usage
frec(iop);
FILE
*iop;
Description
Return 1 if the file is record-oriented.
Note:
this
context,
record-oriented
files are not file-
structured
disks, nor are they the user's console terminal.
Other
terminals,
along
printers,
qualify, however.
Bugs
with
devices
such as line-
in
C Compiler and Library
Page
5-106
fscanf
5.88
Formatted input conversion
Formatted input conversion
_________ _____
__________
**********
* fscanf *
**********
File name:
fscanf.mac
Usage
fscanf(fd, fmt, pointer(s))
FILE
*fd;
/* Input file pointer
char
*fmt;
/* Format string
*/
*/
Description
Fscanf()
parses
the
input
file
according
to
the
indicated
format descriptor, storing the results in
the
pointer
arguments.
It
returns
the
number
of
successfully assigned input items.
See
the
description
of
scanf()
for
further
documentation.
Diagnostics
Fscanf() returns -1 if an end of file
condition
exists
and
no
data
was
stored.
It returns -2 if a
palpably
incorrect format, such as "%" is encountered.
Bugs
C Compiler and Library
Page
5-107
fseek
Reposition file pointer (seek)
5.89 Reposition file pointer (seek)
____ _______ ______
__________
*********
* fseek *
*********
File name:
fseek.mac
Usage
fseek(iop, offset, param);
FILE
*iop;
/* What device to seek
long
offset; /* New read position
int
param; /* Zero for abs. seek
*/
*/
*/
Description
fseek()
moves
the
file
pointer
to
the
indicated
position.
The
position
must
have
been
returned
by
ftell() or equal zero for rewind.
Param must
be
zero.
The file/device must be seekable.
fseek() returns zero if correct, EOF if an error
occurs.
If no error occurred, error and eof flags are reset.
flseek() is an alternate entry with identical
parameters
and actions.
Note that on RSX, fseek() can be used to open a file
for
update by a sequence such as:
fd = fopen("file.nam", "a");
fseek(fd, 0L, 0);
/* Rewind file
*/
If the file was opened on RSX using the 'n' mode
switch,
it
will be opened using file attributes "fixed 512-
byte
records with no carriage control".
The
offset
pointer
is
thus
a virtual byte number and fseek may be used
to
freely reposition the file pointer.
Bugs
C Compiler and Library
Page
5-108
fspool
Spool file to default print queue
5.90 Spool file to default print queue
____ __ _______ _____ _____
_____
**********
* fspool *
**********
File name:
fspool.mac
Usage
fspool(fp);
FILE
*fp;
/* Open file IOV
*/
Description
This routine is called in lieu of fclose()
when
it
is
desired
to
spool
the file to the system line
printer.
There is no control over
the
disposition
or
printout
parameters.
Fspool() returns
zero
if
the
file
was
spooled,
it
returns
an
error
code
if
spooling
could
not
be
initiated.
If called on native RT11, the file
will
be
closed
and
an "illegal device error" (E$$NOD = 6)
will
be returned.
If the program needs access to the power
of
the
queue
manager
print spooler on native RSX, the RSX
extensions
library spwn() routine should be used to spawn a
command
line to MCR after closing the file as usual.
If the program needs access to the power
of
the
queue
manager
on RSTS/E, it should close the file and use
the
routines in the RSTS/E extensions library to execute
the
UU.SPL system function call.
On RSTS/E V7.0, the file is spooled to any line
printer
(RSX
mode)
or
to
LP0:
in RT11 mode.
The
particular
line printer cannot be selected
without
modifying
the
source of fspool().
If the
file
was
opened
by
calling
fwild()/fnext(),
internal buffers will not be freed, allowing the
program
to call fnext() for subsequent files.
Bugs
On
RSTS/E
RT11
mode,
error
codes
will
follow
the
description of the spooling system function call.
C Compiler and Library
Page
5-109
ftell
Get file position for subsequent seek
5.91 Get file position for subsequent seek
____ ________ ___ __________ ____
___
*********
* ftell *
*********
File name:
ftell.mac
Usage
long
ftell(iop);
FILE
*iop;
/* What device to seek
*/
Description
ftell() returns the position of the
read/write
pointer
of
the
indicated
file.
This value may be fed back
to
the file system by calling fseek().
Note that the
value
is a pointer to the record, not a block or byte
pointer.
On RSX, the program
should
flush
the
current
record
before calling ftell().
(Flush() is a noop on RT11.)
If reading lines of text, the correct sequence is:
position = ftell(fd);
if (fgets(buffer, sizeof buffer, fd) != EOF) {
/*
* 'position' locates the record
* read by the call to fgets()
*/
}
Make sure you declare ftell()
extern long ftell();
If you do not, it will return garbage.
Bugs
On both systems, the value returned is the
position
of
the
file pointer (RFA), as a byte offset from the
start
of the file.
Note, however, that
on
RSX
systems
the
pointer
is
to
the start of the current record.
It
is
not necessarily the case that the start of a
text
line
equates
to
the
start
of a record.
RSX supports
many
file record formats, including Fortran,
print_file
and
"unformatted"
The
(with embedded control information).
C Compiler and Library
Page
5-110
ftell
Get file position for subsequent seek
latter files may have multiple text
lines
embedded
each
internally
in
record.
This
is
handled
by
the
formatted read routines (i.e., fgets() and getc()).
On
RSX, the only way to be certain of the exact
record/line
correspondance
is
to
use
the
fget()
and
fput()
functions.
The T utility program (in the tools
library)
shows another method of handling this problem.
On RSTS/E RT11 mode,
ftell
will
not
process
"large"
files (with more than 65535 blocks) correctly.
C Compiler and Library
Page
5-111
ftime
Compute time of day (augmented)
5.92 Compute time of day (augmented)
____ __ ___ ___________
_______
*********
* ftime *
*********
File name:
ftime.mac
Usage
#ifdef unix
#include <sys/types.h>
#include <sys/timeb.h>
#else
#include <timeb.h>
#endif
long
ftime(buf);
struct timeb
*buf;
Description
ftime returns the time of
day
in
seconds.
The
time
buffer
receives the time of day, milliseconds since
the
current second, and timezone and Daylight
Savings
time
indicators.
The time buffer has the following format:
struct timeb {
long
time;
unsigned millitm;
short
timezone;
short
dstflag;
};
/*
/*
/*
/*
Time of day
Milliseconds
Current timezone
Daylight Savings
*/
*/
*/
*/
The time value is the time since midnite, Jan
1,
1970,
measured
in
seconds.
The timezone value is the
number
of minutes that local time differs from GMT.
Note that, on Unix, the time buffer definition is
stored
in the sys directory, while for Decus-C and Vax-11 C,
it
is
stored
in
the
default
or
sys$library:
Bugs
respectively).
system
library
(C:
C Compiler and Library
Page
5-112
ftime
Compute time of day (augmented)
The Unix time function returns
GMT.
Decus
C
returns
local time.
Timezone and dstflag are set to zero.
C Compiler and Library
Page
5-113
ftty
5.93
Test if terminal file
Test if terminal file
____ __ ________
____
********
* ftty *
********
File name:
ftty.mac
Usage
ftty(iop)
FILE
*iop;
Description
Return 1 if the file
is
a
terminal-type
device.
In
general, this means the user's command terminal.
Bugs
Obsolete
--
use
for
transportability.
isatty(fileno(iop))
instead
C Compiler and Library
Page
5-114
fwild
5.94
Wild-card file open
Wild-card file open
_________ ____ ____
*********
* fwild *
*********
File name:
fwild.mac
Usage
FILE *
fwild(name, mode);
char
*name;
char
*mode;
/* File to open
/* Open modes
*/
*/
FILE *
fnext(iop);
FILE
/* I/O pointer
*/
*iop;
Description
Fwild() opens a new or existing file
(whose
file
name
may
contain "wild-cards").
Open modes are identical
to
those given in fopen().
On return, the
file
name
has
been
parsed,
but
no file has yet been opened.
A
NULL
return means that the file name did not parse
correctly.
Fnext() opens the first or next file which
was
defined
by a previous call to fwild().
If fnext() returns
NULL,
there are no
(more)
files
that
match
the
wild-
card
specification.
fwild/fnext handle RSX file version numbers correctly
on
VMS
compatibility
mode
(which
uses
the
ODS2
disk
structure).
Fwild/fnext do not handle
version
numbers
correctly
on
native RSX systems which use the FILES-
11
(ODS1) disk
structure.
For
example,
a
program
can
request "foo.*;3", "foo.*;*", "foo.*;0", and "foo.*;1".
Omitting a
version
number
"foo.*"
is
equivalent
to
"foo.*;0".
Note
that
version
number
0
means
the
"newest" file, while version number -1 means the
oldest.
(Version numbers are not used on RT11 or RSTS/E.)
For
native
RSX
systems
(using
the
FILES-11
disk
structure),
an explicit version number and the
wildcard
version number work correctly.
Version numbers 0 and -
1
work only if the directory has been reorganized by
using
the SRD utility program.
If the directory has not
reorganized
the
been
appears
(such
that
youngest
version
C Compiler and Library
Page
5-115
fwild
Wild-card file open
first
in
the
directory),
fnext()
will
yield
unpredictable results.
On
RT-11,
the
wildcard
filename
match
is
handled
internally
to
fwild/fnext.
The
parser
will
handle
several forms of wild file specs, including imbedded
'*'
and the single character wildcard '%', and acts the
same
as the DIRECTORY wildcard handler.
For
convenience,
a
'?' acts the same as a '%' in a match string.
Note:
if a program executes
fclose(),
all
file
name
information
will
be
lost.
The
following
sequence
illustrates proper use of fwild()/fnext():
if (gets(name_buff) == NULL)
exit();
if ((fd = fwild(name_buff, "r")) == NULL)
error("Can't open %s\n", name_buff);
for (count = 0; fnext(fd) != NULL; count++) {
/*
* Process each file
*/
while (fgets(buffer, sizeof buffer, fd)
!= NULL) {
/*
* Process each record
*/
}
}
/*
* fnext() fails; the channel is closed.
* count has the number of files processed.
*/
if (count == 0)
error("No matching files found");
The
following
summarizes
the
types
of
wild-
card
processing
of
available
on the various implementations
the C support library:
Environment
Supports
Native RSX
"*"
matches
any filename, filetype,
or
version number.
Version ;0 and ;-1
are
supported on ODS2
systems.
UIC's
may
not contain wildcards.
RSX/VMS
As above, note that
version
;-1
means
the "earliest"
version.
Note
warning
below.
Directory identifiers may not
be
RSX/RSTS
wildcarded.
VMS systems support ODS2.
Uses RSTS/E
wildcard
conventions:
"*"
replaces
"?"
filename
or
filetype.
C Compiler and Library
Page
5-116
fwild
Wild-card file open
matches any character.
PPN's may not
be
wildcarded.
Version
numbers
are
not
supported on RSTS/E.
Native RT11
"*" replaces
any
string,
"%"
or
"?"
match any non-blank character.
RT11/RSTS
Uses RSTS/E wildcard
conventions
noted
above.
Bugs
On
native
RSX
systems
using
ODS1
(FILES-11)
disk
structures,
version
numbers will be processed
properly
only if directories have been sorted (by using
the
SRD
utility
program,
for example).
If directories are
not
sorted, and fwild() is invoked with version number ;0
or
;-1, it will yield unpredictable results.
The command language scan (CSI1$) on
VMS
compatibility
mode
does not parse version number -1 (because it has
a
different
meaning
on
native
VMS)
and
fwild()
will
consequently fail.
If you
want
the
oldest
version,
fwild()
should
be
invoked
with
a
file
name
of
the
type
"foo.*"
or
"foo.*;0" and, before
calling
fnext()
for
the
first
time,
you
should
set the correct bits in the IOV
flag
word as follows:
if ((fd = fwild(file, "r")) == NULL)
error("can't open file %s", file);
if ((fd->io_flag & IO_VER) != 0
&& version_minus_1_wanted)
fd->io_flag |= IO_VM1;
Flag bit IO_VER signals "version 0
or
-1",
while
bit
IO_VM1
signals
version minus 1.
Again, note that
this
must be done before the first call to fnext().
On native RT11 and all RSTS/E
modes,
fwild/fnext
will
fail
if the device is not directory structured (even
if
no wildcard file is specified).
If this is
a
problem,
you should write:
if ((fd = fwild(filename, mode)) != NULL)
iswild = 1;
else if ((fd = fopen(filename, mode) != NULL)
iswild = 0;
else error("cannot open the file");
The program must then test iswild
to
determine
it
must
call
initiated
directly.
fnext() or if processing should be
if
C Compiler and Library
Page
5-117
fwild
Wild-card file open
On all RSTS/E modes, there may be problems with
logical
name
translation
as
file
name strings must be
parsed
more than once.
Thus, if a programer defines a
logical
name which is identical to a valid physical device
name,
a wildcard lookup
may
access
the
wrong
unit.
This
problem is described in the RSTS/E documentation.
Fwild/fnext was designed to work only with disk
devices.
It
will
not
necessarily
work
correctly
with
other
directory-structured devices, such as magtape.
Internal
If you are always running on RSTS/E, or
always
running
on
RSX-11
(native or VMS compatibility mode) or
always
running on native
RT11,
you
should
consider
editing
fwild.mac to remove unnecessary code.
This routine depends on some
internal
knowledge
about
RSTS/E
and
about
the
implementation
of
RSX-11
file
control services on RSTS/E.
It
may
need
modification
for subsequent releases of RSTS/E.
The implementors do not apologize for the size
of
this
module.
The distribution
of
the
C
language
system
includes
source
code
utility
program.
for
the
SRD
(sort
directories)
C Compiler and Library
Page
5-118
fwrite
5.95
Output a record
Output a record
______ _ ______
**********
* fwrite *
**********
File name:
fwrite.mac
Usage
int
fwrite(object, sizeof (*object), nitem, iop)
int
nitem;
FILE
*iop;
Description
Object points to a buffer that is contains
a
specified
number of items to be written to the file.
fwrite() returns the actual
number
of
items
written.
This will be zero if an error was encountered.
Bugs
C Compiler and Library
Page
5-119
getchar Get characters
5.96
Get characters
___ __________
***********
* getchar *
***********
File name:
getcha.mac
Usage
getchar();
getc(iop);
FILE
*iop;
Description
Getchar() reads one character from
the
standard
input
file.
getc()
reads
one
character from the
indicated
input file.
Both return EOF on error or end of file.
To continue reading
from
the
program may execute:
clearerr(iop);
Bugs
a
terminal
after
EOF,
C Compiler and Library
Page
5-120
gets
5.97
Read a string from stdin
Read a string from stdin
____ _ ______
____ _____
********
* gets *
********
File name:
gets.mac
Usage
char *
gets(buffer);
char
*buffer;
Description
gets() reads a string into the buffer from the
standard
input
(stdin).
The
string is terminated by a
newline
character, which is replaced in the buffer
by
a
null.
Gets() returns buffer or NULL on end of file or error.
Bugs
C Compiler and Library
Page
5-121
gettty
5.98
________ ____
Get control terminal name
Get control terminal name
___ _______
**********
* gettty *
**********
File name:
gettty.mac
Usage
gettty(buffer);
char
*buffer;
Description
Store the device name of the
control
terminal
in
the
buffer.
If
this cannot be done, a null string will
be
returned.
Bugs
On
RSX
modes,
gettty()
uses
the
GLUN$
executive
directive
to
obtain the device name and unit number
of
stderr
(which
always
is
assigned
to
the
control
terminal).
On RT11 modes, gettty() calls iovtoa to return the
file
name
on
which
stderr
was
opened.
not
necessarily contain a valid unit number.
This
will
C Compiler and Library
Page
5-122
getw
Input a binary integer from a file
5.99 Input a binary integer from a file
______ _______ ____ _ ____
_____ _
********
* getw *
********
File name:
getw.mac
Usage
getw(iop);
FILE
*iop;
Description
getw() reads one (16-bit) word from the indicated
file.
The
program
must call feof() or ferr() to test for
end
of file or error.
Bugs
C Compiler and Library
Page
5-123
inchr
Find Index of Character in a String
5.100 Find Index of Character in a String
_____ __ _________ __ _ ______
____
*********
* inchr *
*********
File name:
inchr.mac
Usage
char *
inchr(stng, chr)
char
*stng;
char
chr;
/* String to search in
/* Byte to search for
*/
*/
Description
If chr is in stng, return its index, i.e.
the offset
in
bytes
from
the
beginning
of
the
string
inchr("abc",'b') == 1.
return
-1.
See also strchr().
Bugs
If chr is not
in
stng,
C Compiler and Library
Page
5-124
index
Find First Instance of a Character in a String
5.101 Find First Instance of a Character in a String
____ _____ ________ __ _ _________ __ _ ______
*********
* index *
*********
File name:
index.mac
Usage
char *
index(stng, chr)
char
*stng;
char
chr;
/* String to search in
/* Byte to search for
*/
*/
Description
If chr is in stng, return a
pointer
not,
return NULL.
Bugs
Obsolete;
use strchr() instead.
to
it.
If
C Compiler and Library
Page
5-125
iov
I/O vector definition
5.102
I/O vector definition
___ ______
__________
*******
* iov *
*******
File name:
iov.mac
Usage
#include <stdio.h>
... to be supplied ...
Bits in iov.io_flag:
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
_IOREAD 0000001
_IOWRT 0000002
_IONBF 0000004
_IOMYBUF 000010
_IOEOF 0000020
_IOERR 0000040
_IOSTRG 0000100
_IORW
0000200
IO_CMD 0000400
IO_APN 0001000
IO_NOS 0002000
IO_NEWL 0004000
IO_FIL 0010000
IO_TTY 0020000
IO_REC 0040000
IO_OPN 0100000
IO_EOR (IO_ERR
Bits in iov.io_wflag:
#define IO_WLD 0000001
#define IO_VM1 0000002
#define IO_VER 0000004
#define IO_WF1 0000010
#define IO_NLH 0000020
/* read
/* write
/* Unbuffered, "u" mode
/* I/O lib. owns buffer
/* End of file seen
/* Error seen
/* For sprintf
/* Open for read/write
/* User's command tty
/* Append mode open
/* No newlines needed
/* RSX TTY newline hack
/* Disk file
/* Terminal device
/* Record device
/* Open file
| IO_EOF)
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
/*
/*
/*
/*
/*
*/
*/
*/
*/
*/
fwild: wildcard file
fwild: version ;-1
fwild: ;0 or ;-1
fwild first flag
Newlines hack bit
Bits in iov.io_rsflag (RSTS native only)
#define IO_ODT2 0100000 /* ODT mode (RSTS only) */
extern
extern
extern
extern
extern
int
FILE
FILE
FILE
int
$$ferr;
*stdin;
*stdout;
*stderr;
$$exst;
/*
/*
/*
/*
/*
Error word
Standard input file
Standard output file
User's command tty
Exit status
*/
*/
*/
*/
*/
C Compiler and Library
Page
5-126
iov
I/O vector definition
Internal
extern
extern
extern
extern
extern
extern
FILE
extern
FILE *$$luns[]; /* IOV pointer table
FILE *$$lune;
/* IOV table end
(int)(char *$$lmax); /* RSX $$luns dim.
char **$$ifil; /* -> stdin file name
char **$$ofil; /* -> stdout file name
int
$$nlun;
/* RSX: Number of luns
*$$eiov;
/* RSX: Stderr iov
int
$$iosb[2]; /* RSX: I/O status
*/
*/
*/
*/
*/
*/
*/
*/
Description
Define the I/O vector structure used
for
communication
by
all
I/O routines in the C library.
Note that it
is
different for
RSX
certain
in
and
RT11
modes.
Note
also
that
bits
IO_FLAG
are
only meaningful for
one
flavor of I/O.
The RSX-mode IOV contains
an
entire
file
data
block
(FDB).
Also,
'io_uic'
contains the binary UIC of
the
directory via which the file is being accessed, not
the
'owner'
UIC.
It
is
this
UIC
which
is
given
when
fgetname() is called.
The RT11-mode IOV contains only
enough
information
to
read
and
write files plus a pointer to an Ascii
string
with the file name argument to fopen().
The
file
name
is
needed
for
fgetname()
and to allow deleting
files
given the IOV pointer.
The following files are defined here:
stdin
The standard input file.
stdout
The standard output file.
stderr
The error
output
file.
Note:
on
RSX
systems, stderr is opened on LUN 1.
$$ferr (error word) is also defined here.
This
is
set
non-zero
if
an error occurred when performing I/O.
On
RSX, the standard I/O error code is returned.
On
RT11,
an error code compatible with RSTS/E usage is returned:
Global
E$$ILF
E$$NOR
E$$FNF
E$$NOD
E$$ILU
E$$NOO
E$$EOF
E$$FAT
Value
02. 002
04. 004
05. 005
06. 006
07. 007
09. 011
11. 013
12. 014
Meaning
Illegal file name
No room for user on device
Can't find file or account
Not a valid device
I/O channel in use
I/O channel not open
End of file on device
Fatal system I/O failure
C Compiler and Library
Page
5-127
iov
I/O vector definition
E$$ERR
E$$FND
E$$NOC
E$$NSP
13.
16.
17.
32.
015
020
021
040
User data error on device
File already found (protected)
Too many open files on unit.
No memory space for buffer
E$$FAT (12) is set only if an "impossible" error
occurs.
While this may indicate a bug in the RT11 library, it
is
more likely to be a user programming error (like
passing
garbage to an I/O routine).
E$$ILU (7) is set if fopen tries to open a channel
that
is already in use.
The perror() library routine may be
used
to
print
an
error message defined for the error code.
$$exst (exit status) is used to transmit
a
termination
code
to
the
operating
system.
The
value is set
by
calling exit() or exits().
The
following
exit
status
values are defined in stdio.h:
Global
E$$XOK
E$$XWA
E$$XER
E$$XFA
#define
IO_SUCCESS
IO_WARNING
IO_ERROR
IO_FATAL
RSX RT11 Meaning
1
1 Normal
0
2 Warning
2
4 Error
4
8 Severe Error
Internal
In RSX, buffering is done
by
the
RSX
file-
management
services (FCS).
The block buffer pointer is unused
(but
reserved for anybody who cares to add random access).
Bugs
C Compiler and Library
Page
5-128
irand
Random number modulus argument
5.103 Random number modulus argument
______ _______ ________
______
*********
* irand *
*********
File name:
irand.mac
Usage
int
irand(arg)
int
arg;
Description
Generate
a
pseudorandom
number
in
the
range
(arg-1).
If arg is zero, generate a number in the
..
range
0 ..
32767.
Note that the algorithm is prone to nonrandom
sequences
when considering the next pseudorandom number.
irand is equivalent to the following sequence:
extern long
rand;
if (arg == 0) arg = 32767;
return(((rand() >> 8) & 32767) % arg);
Bugs
0
C Compiler and Library
Page
5-129
isalloc Check If a Pointer Points to Allocated Memory
5.104 Check If a Pointer Points to Allocated Memory
_____ __ _ _______ ______ __ _________ ______
***********
* isalloc *
***********
File name:
isallo.mac
Usage
int
isalloc(buff)
char *buff;
Description
isalloc() returns 1 if buff is a pointer to a
block
of
memory
allocated
by
calloc(),
malloc(), or
realloc()
that has not been freed (by free());
-1
if
it
is
a
(recently) freed allocated block;
and 0 otherwise.
isalloc(NULL) == 0.
isalloc(p) will remain -1 after a
call
of
free(p)
at
least
until
the
next call to calloc(), malloc(),
etc.
Beyond that, its value is not predictable.
Pointers
for
which
isalloc()
is non-zero are exactly those that
may
safely be passed to realloc().
The test done by isalloc()
is
definitive,
unlike
the
tests
done
by,
for example, free() and msize(),
which
will yield false positives at least
time.
25%
of
the
However, isalloc() is slower.
Bugs
Not portable.
C Compiler and Library
Page
5-130
isalnum Return TRUE if alphanumeric argument
5.105 Return TRUE if alphanumeric argument
______ ____ __ ____________ ________
***********
* isalnum *
***********
File name:
isalnu.mac
Usage
isalnum(c);
int
c;
Description
Return non-zero if c is
0
otherwise.
Bugs
an
alphanumeric
character,
C Compiler and Library
Page
5-131
isalpha Test for alphabetic argument
5.106 Test for alphabetic argument
__________ ________
____ ___
***********
* isalpha *
***********
File name:
isalph.mac
Usage
isalpha(c);
int
c;
Description
Return non-zero if
0
otherwise.
Bugs
c
is
an
alphabetic
character,
C Compiler and Library
Page
5-132
isascii Test for 7-bit Ascii character
5.107 Test for 7-bit Ascii character
_____ _____ _________
____ ___
***********
* isascii *
***********
File name:
isasci.mac
Usage
isascii(c);
int
c;
Description
Return non-zero if c
0
otherwise.
Bugs
is
a
7-bit
Ascii
character,
C Compiler and Library
Page
5-133
isatty
5.108
Test if terminal file
Test if terminal file
____ __ ________
____
**********
* isatty *
**********
File name:
isatty.mac
Usage
isatty(channel_number)
int
channel_number;
Description
Return
1
if
the
file
open
on
this
channel
is
a
terminal-type device.
In general, this means the
user's
command terminal.
Note that the argument is a file descriptor, not a
FILE
*
pointer.
File
descriptors
are
used
on
Unix
to
identify the channel on which
the
file
is
open.
As
Decus C does not support file descriptor I/O
processing,
the logical unit number assigned to a file by fopen()
is
used instead.
Use isatty() as follows:
if (isatty(fileno(fd))) ...
Bugs
Note that Decus C channel numbers
are
to
Unix file descriptors.
isatty(0)
Specifically,
not
related
does not necessarily check stdin.
isatty(fileno(stdin))
instead.
Use
C Compiler and Library
Page
5-134
iscntrl Test for control character argument
;02
5.109 Test for control character argument
____ ___ _______ _________ ________
02
***********
* iscntrl *
***********
File name:
isctrl.mac
Usage
iscntrl(c);
int
c;
Description
Return non-zero if C is a control character.
Bugs
C Compiler and Library
Page
5-135
isdigit Return TRUE if digit argument
5.110 Return TRUE if digit argument
____ __ _____ ________
***********
* isdigit *
***********
File name:
isdigi.mac
Usage
isdigit(c);
int
c;
Description
Return 1 if c is an Ascii digit, 0 otherwise.
Bugs
______
C Compiler and Library
Page
5-136
isgraph Test for graphic alphabetic argument
5.111 Test for graphic alphabetic argument
____ ___ _______ __________ ________
***********
* isgraph *
***********
File name:
isgrap.mac
Usage
isgraph(c);
int
c;
Description
Return
non-zero
if
c
is
a
graphic
character,
0
otherwise.
Graphics
characters
include
letters,
digits,
and
punctuation.
Bugs
Space, tab, etc.
are not graphics.
C Compiler and Library
Page
5-137
islower Test for lower-case alphabetic argument
5.112 Test for lower-case alphabetic argument
____ ___ __________ __________ ________
***********
* islower *
***********
File name:
islowe.mac
Usage
islower(c);
int
c;
Description
Return
non-zero
if
C
alphabetic
character, 0 otherwise.
Bugs
is
a
lower-case
C Compiler and Library
Page
5-138
isprint Return non-zero if printable argument
5.113 Return non-zero if printable argument
______ ________ __ _________ ________
***********
* isprint *
***********
File name:
isprin.mac
Usage
isprint(c);
int
c;
Description
Return
non-zero
if
c
is
a
printable
character,
0
otherwise.
Printable
characters
include
letters,
digits,
punctuation,
and
the
newline,
etc.
Bugs
are not included.
space
character.
Tab,
C Compiler and Library
Page
5-139
ispunct Return TRUE if punctuation argument
5.114 Return TRUE if punctuation argument
______ ____ __ ___________ ________
***********
* ispunct *
***********
File name:
ispunc.mac
Usage
ispunct(c);
int
c;
Description
Return
non-zero
0
otherwise.
Bugs
if
c
is
an
Ascii
punctuation,
C Compiler and Library
Page
5-140
isspace Return non-zero if the character is "whitespace"
5.115 Return non-zero if the character is "whitespace"
______ ________ __ ___ _________ __ ____________
***********
* isspace *
***********
File name:
isspac.mac
Usage
isspace(c);
int
c;
Description
Return non-zero if c is a whitespace
character.
These
consist
of
space,
backspace,
newline,
and
form-feed.
included.
Bugs
The carriage return ('\r') is also
tab,
C Compiler and Library
Page
5-141
isupper Return TRUE if Upper-case alphabetic argument
5.116 Return TRUE if Upper-case alphabetic argument
______ ____ __ __________ __________ ________
***********
* isupper *
***********
File name:
isuppe.mac
Usage
isupper(c);
int
c;
Description
Return 1 if c is an Upper-case alphabetic
0
otherwise.
Bugs
character,
C Compiler and Library
Page
5-142
isxdigit
Return non-zero if hexadecimal digit
5.117 Return non-zero if hexadecimal digit
______ ________ __ ___________ _____
************
* isxdigit *
************
File name:
isxdig.mac
Usage
isxdigit(c);
int
c;
Description
Return non-zero if C is a valid hexadecimal digit
9,
A-F, a-f).
Bugs
This routine is not present in other C libraries.
(0-
C Compiler and Library
Page
5-143
itoa
5.118
Integer to Ascii
Integer to Ascii
_______ __ _____
********
* itoa *
********
File name:
itoa.mac
Usage
char *
itoa(value, string)
int
value;
char
*string;
Description
itoa converts the value to a
(signed)
decimal
string.
The
string
is null-trailed.
itoa returns a pointer
to
the trailing null.
Note that the result can be computed (more flexibly)
by
executing sprintf(buffer, "%d", value);
Bugs
C Compiler and Library
Page
5-144
itoa8
Convert integer to octal Ascii
5.119 Convert integer to octal Ascii
_______ __ _____ _____
_______
*********
* itoa8 *
*********
File name:
itoa8.mac
Usage
char *
itoa8(value, buffer);
int
value;
char
*buffer;
Description:
The value is
converted
to
octal
and
stored
in
the
buffer.
A pointer to the trailing null is returned.
Note that the result can be computed (more flexibly)
by
executing sprintf(buffer, "%o", value);
Bugs:
This routine does not generate leading zeros.
they
are needed, use:
sprintf(buffer, "%06o", value);
If
C Compiler and Library
Page
5-145
itoax
Convert an integer to hexidecimal Ascii
5.120 Convert an integer to hexidecimal Ascii
_______ __ _______ __ ___________ _____
*********
* itoax *
*********
File name:
itoax.mac
Usage
char *
itoax(value, buffer);
int
value;
char
*buffer;
Description:
Convert the integer to hexidecimal ascii.
The string
is
null-trailed.
Values
from
10
to
15
(decimal)
are
represented by "A" to "F".
Itoax() returns a pointer
to
the trailing null.
Note that the result can be computed (more flexibly)
by
executing sprintf(buffer, "%x", value);
Bugs:
C Compiler and Library
Page
5-146
kbin
Single Character Terminal Input
5.121 Single Character Terminal Input
_________ ________ _____
______
********
* kbin *
********
File name:
kbin.mac
Usage
int
kbin();
Description
Read one character from the console terminal.
The
input
character is not echoed nor does the program delay
until
an entire line has been entered.
Note the following:
This
routine
is
very
inefficient,
as
it
requests
operating-system service for every character entered.
Typing Control/C (or Control/Y on VMS)
will
cause
the
program
to
exit
immediately (as if the main()
routine
exited), closing all files.
On RT-11 (native and
emulated),
the
operating
system
expands
<return>
to
a
carriage
return
line
feed
sequence.
This will
be
stripped
by
kbin()
to
just
<return>
reads
('\r'
in C).
Thus, if the user program
'\n', a <line-feed> was typed.
Note that this is
unlike
the general C library.
Bugs
On RSX,
this
routine
requires
the
command
terminal
having been assigned as logical unit number 1.
In general, the
input
character
will
not
have
been
echoed.
On RSTS/E and native RT11, the operating
system
may already have echoed the character if
you
type
the
character before the read request has been made.
C Compiler and Library
Page
5-147
kbinr
Terminal Input Without Wait
5.122 Terminal Input Without Wait
_____ _______ ____
________
*********
* kbinr *
*********
File name:
kbinr.mac
Usage
int
kbinr();
Description
If a character has been typed on the
console
terminal,
return it (without echoing or waiting).
If no
character
is available, kbin() returns -1 (EOF).
Note the following:
This
routine
is
very
inefficient,
as
it
requests
operating-system service for every character entered.
Typing Control/C (or Control/Y on VMS)
will
cause
the
program to exit immediately.
On RT-11, the operating system
expands
<return>
to
a
carriage
return
line
feed
sequence.
This
will
be
stripped by kbin() to just <return> ('\r' in C).
Thus,
if the user program reads '\n', a <line-feed> was
typed.
Note that this is unlike the general C library.
Bugs
On RSX-11M, this routine depends on the
fact
that
the
console terminal was assigned to LUN 1.
On RSX-11M and VMS emulation mode, the
typed
character
will
not
be
echoed.
On RSTS/E and RT11 modes, it
may
have already been echoed by the operating system if
the
terminal user typed before the program requests input.
C Compiler and Library
Page
5-148
localtime
5.123
Build time of day buffer
Build time of day buffer
_____ ____ __
___ ______
*************
* localtime *
*************
File name:
localt.mac
Usage
#include <time.h>
/* Define tm structure
*/
struct tm *
localtime(tvec);
long
*tvec;
/* Time value pointer
*/
struct tm {
int
tm_sec;
int
tm_min;
int
tm_hour;
int
tm_mday;
int
tm_mon;
int
tm_year;
int
tm_wday;
int
tm_yday;
int
tm_isdst;
};
/*
/*
/*
/*
/*
/*
/*
/*
/*
Seconds
*/
Minutes
*/
Hours
*/
Day of month
*/
Month 0 .. 11
*/
Year - 1970
*/
Weekday, Sunday == 0 */
Days since Jan 1
*/
Daylight Saving if 1 */
Description
localtime() converts a Unix time value to
a
vector
of
values.
Bugs
Decus C
doesn't
correct
for
time
zone
or
daylight
savings time.
Leap year isn't done correctly.
fail
The routine
will
after Feb 28, 2100.
Following Unix precedent, localt returns a pointer to
a
static buffer.
C Compiler and Library
Page
5-149
malloc
5.124
____ ______
Allocate and free memory
Allocate and free memory
________ ___
**********
* malloc *
**********
File name:
malloc.mac
Usage
char *
malloc(size);
unsigned
size;
/* NULL if no space
/* Number of bytes
*/
*/
mfree(p);
free(p);
char
*p;
/* Was allocated
*/
Internal
extern char *$$alhd;
/* Allocated block list */
mov
call
; Internal call
; to malloc()
size,r0
$$aloc
Return: r0 -> space (or 0), other registers preserved
mov
call
pointer,r0
$$free
; Internal call
; to free()
Return: r0 random, other registers preserved
Description
malloc()
allocates
the
indicated
number
of
bytes,
returning
a
pointer
to
the first.
If the
allocation
request cannot be satisfied, malloc returns
The
program image is expanded as needed.
NULL.
free() and
mfree()
return
a
buffer
to
free
space.
Nothing is returned.
See also the description of realloc() and sbrk().
Internal
All free memory is allocated in linked lists
which
are
stored
in
monotonically
linked,
noncontiguous
areas.
Each block has is preceeded by a one word header:
C Compiler and Library
Page
5-150
malloc
Allocate and free memory
pointer to next block + "busy bit"
The pointer is to the next following
block.
The
last
block
points
to the first.
The "busy bit" will be
set
if the data in the block is in use.
$$alhd
points
to
the first such block.
Note that a block need not contain any data.
Free
space
is coalesced during the allocation search.
Diagnostics
The program may abort
if
free()
is
passed
a
random
pointer
or
if
the
program
writes outside of an
area
reserved by malloc().
Note that only certain cases
are
trapped
by
this test and that free will accept
invalid
addresses, which will cause
mysterious
failures.
The
isalloc()
function
may be used to test whether a
block
of memory has been allocated by malloc().
Bugs
C Compiler and Library
Page
5-151
maxmin
Maximum and Minimum Routines
5.125 Maximum and Minimum Routines
_______ ________
_______ ___
**********
* maxmin *
**********
File name:
maxmin.mac
Usage
max(a,b)
int
int
a;
b;
min(a,b)
int
int
a;
b;
unsigned
maxu(a,b)
unsigned
unsigned
a;
b;
unsigned
minu(a,b)
unsigned
unsigned
a;
b;
Description
max() and min() return, respectively,
the
maximum
and
minimum
of
their
two
arguments, considered as
signed
integers.
maxu() and minu() are the same
but
consider
their arguments to be unsigned.
Note:
If you are interested in getting the fastest
code
possible
sizes
and
have some knowledge of the relative
of a and b, arrange for
a
to
be
chosen
most
often.
(It's
unlikely
the
in
virtually all cases.)
Bugs
difference
will
be
noticable
C Compiler and Library
Page
5-152
memdmp
5.126
Dump memory or registers
Dump memory or registers
____ ______ __
_________
**********
* memdmp *
**********
File name:
memdmp.mac
Usage
memdmp(start, end);
/* Memory dump routine
char
*start; /* First to dump
char
*end;
/* Last to dump
*/
*/
*/
regdmp();
*/
/* Register dump
Internal
call
regdmp
;Register dump
mov
mov
call
#end,-(sp)
#start,-(sp)
memdmp
;Last address
;First address
;Dump memory
(or first)
(or last)
mov
mov
call
#start,r0
#end,r1
$$dump
;First address
;Last address
;Dump memory
(or first)
(or last)
mov
mov
call
value,r0
#buffer,r1
$$toct
;What to convert
;Where it goes
;Convert it
Return:
r0
r1
r2-r5
unchanged
-> first free byte in buffer
unchanged
Description
Dump
registers
are
preserved.
and/or
memory.
All
registers
If memdmp is called with a zero argument, the stack
will
be dumped.
Memdmp and regdmp are independent of the C I/O
library.
However,
on
RSX, they assume that the console
terminal
has been assigned as LUN 1.
C Compiler and Library
5-153
memdmp
Dump memory or registers
Bugs
Condition codes are not preserved.
Page
C Compiler and Library
Page
5-154
msg
Print a message on the command terminal
5.127 Print a message on the command terminal
_____ _ _______ __ ___ _______ ________
*******
* msg *
*******
File name:
msg.mac
Usage
msg(text)
char
*text;
Internal
mov
call
#text,r0
$$msg
Description
Print a message on the console terminal.
This
does
Return:
routine
not
use
the
standard
library.
all
registers are preserved.
Bugs
On RSX,
this
routine
requires
the
command
terminal
having been assigned as logical unit number 1.
C Compiler and Library
Page
5-155
msize
5.128
______ _____
Get Size of a Memory Block
Get Size of a Memory Block
___ ____ __ _
*********
* msize *
*********
File name:
msize.mac
Usage
unsigned int
msize(buff)
char *buff;
Description
msize() returns the size of a block of memory
allocated
by
calloc(),
malloc(), or realloc().
If buff did
not,
in fact, come from one of these
routines,
the
program
will
crash
about
75%
of
the
time;
the other 25%
,
nonsense will be returned.
(This behavior is due
to
a
simple-minded
validation
algorithm.)
However, buff
==
NULL is valid and will return 0.
Note that the value returned is
the
amount
of
memory
that malloc() (or whoever) actually allocated, which
may
not be exactly
the
same
as
the
program
asked
for.
(Currently,
all
even
number of bytes.)
Bugs
allocations
are rounded up to an
Not portable.
C Compiler and Library
Page
5-156
mul$l
5.129
Multiply long * long
Multiply long * long
________ ____ _
____
*********
* mul$l *
*********
File name:
mull.mac
Usage
long
mul$l(a, b);
long
long
a;
b;
long
mul$li(a, b);
long
int
a;
b;
/* long = long * long
*/
/* Long = long * int
*/
Description
Multiply the long arguments.
This routine is called
by
the C compiler to compile long multiplies.
For EIS, given two longs, A and B, in
the
word
format
Ah,As,Al
and Bh,Bs,Bl where Ah is the high word, As
the
sign bit of the low word, and Al the remaining
15
bits
of the low order word.
A * B = Al * Bl
Then
+
As * Bl * 2**15
+
Bs * Al *
+
Al * Bh * 2**16
+
Bl * Ah *
2**15
2**16
This derivation was provided by Cliff Geschke.
Bugs
C Compiler and Library
Page
5-157
peek
Peek at a location in RSTS/E
5.130 Peek at a location in RSTS/E
________ __ ______
____ __ _
********
* peek *
********
File name:
peek.mac
Usage
peek(location)
int
*location;
Description
Peek to a location in the RSTS/E monitor.
The job will be aborted with a BPT if not running
under
RSTS/E.
Bugs
C Compiler and Library
Page
5-158
perror
Print Library Error Message
5.131 Print Library Error Message
_______ _____ _______
_____
**********
* perror *
**********
File name:
perror.mac
Usage
perror(text)
char
*text;
Description
An error message is written to stderr, using the
current
i/o library error (stored in $$ferr).
prepended
to the message.
Diagnostics
Bugs
Text is
C Compiler and Library
Page
5-159
printf
5.132
Formatted print routine
Formatted print routine
_________ _____
_______
**********
* printf *
**********
File name:
printf.mac
Usage
printf(format, arg1, ...)
char
*format;
fprintf(iov, format, arg1, ...)
FILE
*iov;
char
*format;
char *
sprintf(buffer, format, arg1, ...);
char
*buffer;
char
*format;
$$prnt(format, argvec, iov)
char
*format;
int
*argvec[];
FILE
*iov;
Description
printf() converts, formats, and
prints
its
arguments,
under
control of the first argument, writing output
via
putchar().
fprintf() writes its output to the
indicated
file.
sprintf()
writes
its
output
to the
indicated
string buffer.
$$prnt() is the internal print
formatter
which is called by printf, etc.
sprintf() returns a pointer to the EOS at the end of
the
output buffer.
This is not necessarily transportable.
The format argument is a character string which
contains
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 argument to printf.
Each
conversion
specification
is
introduced
by
the
character %.
- an
left
Following the %, there may be
optional
minus
sign
"-"
which
specifies
C Compiler and Library
Page
5-160
printf
Formatted print routine
adjustment of the converted argument in the
indicated
field.
- an optional digit string specifying field
width;
if
the
converted argument has fewer characters than
the
field width, it will be blank-padded on the left
(or
right, if
the
left-adjustment
indicator
has
been
given) to make up the
field
width.
If
the
field
width
is
specified as '*' or '?', the next
argument
is used.
(Note: '?' is
obsolete.)
If the
width
is
specified
with a leading
zero,
zeros are
used
for
padding instead of blanks.
This zero
does NOT
imply
an octal field width.
For example, assume the
value
123 is to be printed:
%d
"123"
%5d
" 123"
%-5d
"123 "
%05d
"00123"
- an
optional
period "." which serves to separate
the
field width from the next digit string;
- an optional digit string (precision) which
specifies
the number of digits
to
appear
after
the
decimal
point for e- and f-conversion, or the maximum
number
of
characters
to be printed from a string.
If
the
precision is
specified
as
'*'
or
'?',
type
of
next
argument is used.
- a character which indicates the
conversion
the
to be applied.
The conversion characters and their meanings are
d
u
o
X
x
Signed-decimal
Unsigned-decimal
Octal
Hexadecimal, 10-15 are represented by A-F
Hexadecimal, 10-15 are represented by a-f
The
integer
argument
is converted to
decimal,
octal, or hexadecimal
notation
respectively.
Any
of
the
conversion
characters
may
be
preceeded
by
'l'
to
signal
"long"
integer
argument.
Note
that the Unix usage of
capital
letters
to
represent
long
arguments
is
not
supported.
Note
In order to eliminate the very large
floating point conversion routines from
most programs, a program which requires
floating point conversion must request
C Compiler and Library
Page
5-161
printf
Formatted print routine
the double to ascii conversion routine
explicitly.
The following sequences
show how this is done:
RSX: TKB task=source,LB:DTOA,LB:C/LB
RT11: LINK
source,C:DTOA,C:SUPORT,C:CLIB/BOT:2000
If this is not done, any use of the %f
%e, or %g conversions will result in an
error message.
On RSTS/E, the library
build procedure creates RTDTOA.OBJ and
RXDTOA.OBJ in the library account.
**
**
**
**
**
**
f
The
Floating point support has not yet
been fully implemented. The float
or double value must be the last
or only argument to printf.
Only
single-precision
conversion
is
presently available.
argument
is
**
**
**
**
**
**
converted to decimal
notation
in the style "[-]ddd.dd" where the number of
d's
after
the
decimal
point
equals the
precision
specification for the argument.
If precision
is
missing, 6 digits are given; if explicitly 0,
no
digits and no decimal point
are
printed.
The
argument
should
be
float or double.
"%lf"
or
"%F" must be used to signal "long (i.e.
double)
argument."
e
This is a restriction of Decus C.
The float or double argument is converted in
the
style "[-]d.ddde+-dd" where there is
one
digit
before the decimal point and the number after
is
equal
the
to
the
precision
specified
for
argument;
if the precision is missing, 6
digits
are produced.
"%le" or "%E"
must
be
used
to
signal "long (i.e. double) argument."
This is
a
restriction of Decus C.
g
Floating point:
"%f" format if
suitable,
else
"%e"
format.
"%lg"
or
"%G"
must be used
to
signal "long (i.e. double) argument."
This is
a
restriction of Decus C.
c
The argument character is printed.
(Note
that
'lc' takes a long integer argument.)
r
Remote format.
The next
printf()
argument
is
the format.
Note that this is not a
subroutine.
The current format is not processed further.
For
example:
bug(args)
{
C Compiler and Library
Page
5-162
printf
Formatted print routine
error("Error at %r", &args);
}
This routine might be called as follows:
bug("Error %d at %s\n", val, name);
%r is not transportable to
all
implementations
of
the
standard
library.
It does not word
on
Vax-11 C, for example. $$prnt may be used
as shown below for similar functionality.
s
The
argument is taken to be a string
(character
pointer) and
characters
from
the
string
are
printed
until
a
null
character
or until
the
number of characters indicated by the
precision
specification
is
reached;
however
if
the
precision
specification
is
0
or missing
all
characters up to null are printed.
If no recognizable character appears after the
%,
that
character
is printed;
thus % may be printed by the
use
of the string %%.
In no case
does
a
non-existant
or
small
field width cause truncation of a field;
padding
takes place only if the specified
field
width
exceeds
the
actual width.
Characters generated by printf()
are
printed by calling putchar().
$$prnt() is the internal print formatter called
all
"top-level"
print
functions.
It
is
functionally
identical to the Unix and
library
Vax-11
C
_doprnt()
by
routine.
Unfortunately, the leading '_' conflicts
with
RSX-11M
file
services
library
routine
conventions,
requiring the use of the Decus C unique "$$" prefix.
If
your
programs
wish
to
call
$$prnt,
a
potentially
transportable procedure would be:
#ifdef decus
$$prnt(format, args, iov);
#else
_doprnt(format, args, iov);
#endif
You
should
assume,
however,
that
_doprnt()
is
implementations
of
not
necessarily
present
on
all
the
"standard library."
Bugs
e, f, and g conversion only
work
for
single-
precision
floating point.
Use of "%lf" etc.
is not
and may change.
It may also cause
problems
transportable
in
the
C
compiler
(as
the
standard
says that subroutine
calls
take double (not short floating) arguments.
C Compiler and Library
Page
5-163
profile Print profile data
5.133
Print profile data
_____ _______ ____
***********
* profile *
***********
File name:
profil.mac
Usage
$$prof();
extern
int
$$prnl;
extern
char
*$$pfil;
Description
$$prof is
called
by
the
run-time
library
when
the
program
exits
if any functions have been executed
that
were compiled with the profile option.
A profile file is written to file "profil.out".
This
is
defined by a global symbol $$pfil.
By setting $$prnl
to
NULL, the profile file is supressed.
By changing the value of $$prnl, the program can
control
the number of profile entries written on each line.
The
default value
writes
4
entries
per
line.
$$prnl
writes N entries on each line,
Changing
to
N
simplifing
post-processing (sorting) of the data.
$$prnl = 0;
For example:
writes each entry on a separate line.
The following example shows how to
control
the
output
file name:
extern char *$$pfil;
...
$$pfil = "ti:"; /* Output to ti:
$$pfil = NULL; /* No profile output
Data is written using the format string "%8s
If
more
than
one
entry
is written to a line,
succeeding
entries will be preceeded by one space.
*/
*/
%6u".
C Compiler and Library
Page
5-164
profile Print profile data
Note that, by writing the data one entry per
line,
the
profile
output
may easily be sorted either by
function
name or by frequency count.
Bugs
C Compiler and Library
Page
5-165
putc
Output one character to a file
5.134 Output one character to a file
___ _________ __ _ ____
______
********
* putc *
********
File name:
putcha.mac
Usage
putchar(c);
char
c;
putc(c, iop);
char
FILE
c;
*iop;
Description
Putchar() writes one character to
the
standard
output
file.
Putc()
writes one character to the named
output
file.
Normally, the character is returned.
on
errors.
Bugs
EOF is returned
C Compiler and Library
Page
5-166
puts
Output a string to a file
5.135 Output a string to a file
______ __ _ ____
______ _
********
* puts *
********
File name:
puts.mac
Usage
puts(s);
char
*s;
fputs(s, iop);
char
FILE
*s;
*iop;
fputss(s, iop);
char
*s;
FILE
*iop;
Description
puts() writes a
string
to
the
standard
output.
It
appends a newline after the string.
fputs() writes a
string
to
the
indicated
file.
No
newline is appended.
fputss() writes a
string
A
newline is appended.
Bugs
to
the
indicated
file.
C Compiler and Library
Page
5-167
putw
Output a binary integer to a file
5.136 Output a binary integer to a file
_ ______ _______ __ _ ____
______
********
* putw *
********
File name:
putw.mac
Usage
putw(word, iop);
int
word;
FILE
*iop;
Description
putw() writes
one
word
to
the
It
returns EOF on error, 0 on success
Bugs
indicated
file.
C Compiler and Library
Page
5-168
qset
Add memory to the RT11 queue area
5.137 Add memory to the RT11 queue area
______ __ ___ ____ _____ ____
___
********
* qset *
********
File name:
qset.mac
Usage
qset(number)
int
number; /* How many elements
*/
Description
Allocate sufficient memory for the requested
number
queue
cannot
of
elements.
If
sufficient
be
allocated, do nothing.
Bugs
This routine is ignored on RSX.
memory
C Compiler and Library
Page
5-169
r50toa
Convert Radix-50 to Ascii
5.138 Convert Radix-50 to Ascii
________ __ _____
_______
**********
* r50toa *
**********
File name:
r50toa.mac
Usage
r50toa(buff, r5vec, r5cnt);
char
*buff; /* Output text buffer
*/
int
*r5vec; /* Input rad50 buffer
*/
int
r5cnt; /* How many rad50 words */
Description:
Convert r5cnt words of radix
50
data
to
Ascii.
All
letters
will
be in upper-case.
The output buffer
will
not be null-trailed, nor will blank fields be
supressed.
Bugs
C Compiler and Library
Page
5-170
rand
5.139
Random number generator
Random number generator
______ ______
_________
********
* rand *
********
File name:
rand.mac
Usage
long
rand()
extern long
seed;
/* Random number seed
*/
Description
Generate a pseudorandom number.
The algorithm is:
seed = (69069 * seed + 1);
return (rand & 0X8FFFFFFF);
The algorithm is based on the mth$random function in
the
VMS common run-time library.
Note that the algorithm is prone to nonrandom
sequences
when considering the next pseudorandom number.
Bugs
C Compiler and Library
Page
5-171
realloc Reallocate memory
5.140
Reallocate memory
__________ ______
***********
* realloc *
***********
File name:
reallo.mac
Usage
char *
realloc(buff, size);
char
*buff;
unsigned
size;
/* Buffer from malloc() */
/* New size for buff
*/
Description
Realloc() changes the size of the block
pointed
to
by
buff, returning 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 buff points
to
a
block
freed
since the last call of malloc(), realloc(), or
calloc();
thus sequences of free(), malloc(),
and
realloc()
can
exploit
the
search
strategy of malloc() to do
storage
compaction.
See also
the
description
of
malloc(),
calloc()
and
sbreak().
The
following
program
segment
illustrates
of
realloc() to expand and compact storage.
use
#ifndef vms
static char *compact_work;
#endif
main() {
/*
* Initialize work element
* for compact()
*/
#ifndef vms
compact_work = malloc(1);
#endif
...
}
C Compiler and Library
Page
5-172
realloc Reallocate memory
char *
compact(old_ptr, new_size)
char
*old_ptr;
int
new_size;
/*
* Reallocate the area allocated to old_ptr,
* originally allocated by a call to malloc(),
* so that it will contain new_size bytes
(which
* may be greater or less than the current
size).
* Return a pointer to the new area.
* Note: error handling is not shown.
*/
{
extern char *realloc();
free(old_ptr);
#ifndef vms
free(compact_work);
compact_work = malloc(1);
#endif
return(realloc(old_ptr, new_size));
}
compact_work must not be used on the native vax
compiler
(Vax-11
C)
as
the
internal
free
memory buffers
are
organized in a different and incompatible manner.
Diagnostics
The program will abort if buff is not the address
a
buffer allocated by malloc() or calloc().
Bugs
of
C Compiler and Library
Page
5-173
rewind
Rewind a file for re-reading
5.141 Rewind a file for re-reading
____ ___ __________
______ _
**********
* rewind *
**********
File name:
rewind.mac
Usage
rewind(iop);
FILE
*iop;
Description
Rewind the indicated file.
Return -1 if failure,
0
if
ok.
On RT11, if the file was opened for output, it is
closed
and reopened for input.
Diagnostics
RT11 exits fatally if the file name won't parse.
As
the
filename was stored by fopen(), this probably means
that
the user program has stored randomly in memory.
Bugs
C Compiler and Library
Page
5-174
rindex
Find Last Instance of a Character in a String
5.142 Find Last Instance of a Character in a String
____ ____ ________ __ _ _________ __ _ ______
**********
* rindex *
**********
File name:
rindex.mac
Usage
char *
rindex(stng, chr)
char
*stng;
char
chr;
/* String to search in
/* Byte to search for
Description
If chr is in stng, return a pointer to the last
instance
it.
If not, return NULL.
Bugs
Obsolete, use strrchr() instead.
*/
*/
C Compiler and Library
Page
5-175
rstsys
5.143
Execute a RSTS EMT
Execute a RSTS EMT
_______ _ ____ ___
**********
* rstsys *
**********
File name:
rstsys.mac
Usage
int
rstsys(emt)
Description
Execute a rsts emt, returning the error code.
Bugs
C Compiler and Library
Page
5-176
rtemt
5.144
Execute a RT11 EMT
Execute a RT11 EMT
_______ _ ____ ___
*********
* rtemt *
*********
File name:
rtemt.mac
Usage
int
rtemt(emt, r0value)
Description
Execute a rt11 emt after loading r0.
Bugs
C Compiler and Library
Page
5-177
salloc
5.145
Allocate local memory
Allocate local memory
________ _____
______
**********
* salloc *
**********
File name:
salloc.mac
Usage
char *
salloc(n);
/*
NULL if no space
*/
Description
Allocate the requested number of bytes on
the
run-
time
stack,
returning a pointer to the first byte
allocated.
The storage will be
reclaimed
automatically
when
the
function that called salloc() exits.
Note that storage
so
allocated
cannot
be
explicitly
freed.
salloc() returns NULL if allocating the requested
space
would cause the run-time stack to go below 1000 octal.
Note:
it is essential that salloc() be
called
with
a
"clean stack".
I.e, the program must not execute
subr(salloc(10), 20);
Instead, it should execute
temp = salloc(10);
subr(temp, 20);
Diagnostics
Bugs
C Compiler and Library
Page
5-178
sbrk
Allocate memory from operating system
5.146 Allocate memory from operating system
________ ______ ____ _________ ______
********
* sbrk *
********
File name:
sbrk.mac
Usage
char *
sbrk(amount)
int
amount;
Description
sbrk() allocates the indicated amount of memory from
the
operating system.
The allocation is permanent.
Diagnostics
NULL
is
returned
if
the
memory
requested
not
available.
There is no "shortened" return.
Bugs
Internal
Sbrk() does not modify its argument.
is
C Compiler and Library
Page
5-179
scanf
Formatted input conversion
5.147 Formatted input conversion
_____ __________
_________
*********
* scanf *
*********
File name:
scanf.mac
Usage
scanf(fmt, pointer(s))
char
*fmt;
/* Format string
*/
fscanf(fd, fmt, pointer(s))
FILE
*fd;
/* Input file pointer
char
*fmt;
/* Format string
*/
*/
sscanf(buf, fmt, pointer(s))
char
*buf;
/* Input text buffer
char
*fmt;
/* Format string
*/
*/
$$scan(fmt, argp, iov)
char
*fmt;
/* Format string
int
*ptr[]; /* Pointer vector
FILE
*iov;
/* Input file des.
*/
*/
*/
Description
Using the format string, these functions parse the
input
file
(or
given
text file), storing the results in
the
pointer arguments.
The
three
user-callable
routines
differ as follows:
scanf
Reads from the standard input file.
fscanf
Reads from the indicated file.
sscanf
Reads from the text buffer.
$$scan() is an internal routine called by the
above
to
actually
parse
the
input
text.
It
is
functionally
identical to the Unix and Vax-11
C
_doscan()
routine.
Unfortunately,
the
leading '_' conflicts with RSX
file
control service routine naming conventions.
The format string
may
contain
control
characters
to
direct the conversion of the input textual data:
' '
format
Blanks, tabs, or newlines are ignored in
C Compiler and Library
Page
5-180
scanf
Formatted input conversion
strings.
x
An
To match whitespace, use "%[ \t\n]".
ordinary
character
(not
%) must match
the
next input character.
%
Conversion specifications consist of a
'%',
an
optional
'*'
(to
supress
assignment),
an
optional
maximum
numeric
field
width,
and
a
conversion specifier.
Unless value assignment was supressed by the '*'
format
modifier,
the next field is converted and stored in
the
variable pointed to by the corresponding
argument.
An
input
field
is
defined
as
a
string
of
non-
space
characters,
extending
to
the
first
inappropriate
character
or
until
the
field
width
(if
given)
is
exhausted.
The following conversion characters are specified:
%
A single
'%'
is
expected
in
the
input,
no
assignment is done.
d
An integer
of
the
specified
o
octal,
hexadecimal)
x
corresponding
class
(decimal,
or
is
expected.
The
argument
should
be
an
integer
pointer.
If
the
format specifer is given
in
upper-case, or preceeded by 'l', a long
integer
will be stored.
For example, "%ld" is
identical
to "%D".
ignored.
Leading
whitespace
will be
A null field is not converted.
Scanf()
returns
a
count
of the number of fields converted,
but
does not indicate which fields were ignored.
s
A character string is expected.
The input
field
will be terminated by a space, tab, or
newline.
The corresponding argument
should
point
to
a
buffer large enough to contain the
text
and
a
terminating
NULL.
Leading
whitespace will
be
ignored.
c
A single character is read. Leading white
space
is not supressed
--
to read the next non-
blank
character, use "%1s".
If a field width is
given
the
corresponding
argument
is
a pointer to
a
vector of characters and the indicated number
of
characters are read.
e
A floating-point number is converted and
f
appropriately.
g
capitalized, or
stored
If
the
format
indicator
is
preceeded
by
'l',
a
doubleprecision
floating-point number will be
stored.
The floating-point format is the same as in
the
C language:
of
an
optionally
signed
string
C Compiler and Library
Page
5-181
scanf
Formatted input conversion
digits
possibly
containing
a
decimal
point,
followed by an
optional
exponent
field
which
consists
of
an
'E'
or
'e'
followed
by
an
optionally signed integer.
[ ]
A string not
to
be
delimited
by
white-
space
characters.
Unless the first character is
'^',
the format constitutes an acceptance
list:
input field is all characters
until
the
character
which
the
brackets.
Note
the
first
is
not
in
set
within
that leading whitespace is
not
ignored.
If the first character after the left bracket
is
'^', the format defines a stop list:
the
field
the
input
is
all
characters
until
first
character specified within the bracketed
string.
The corresponding argument points to a
character
vector.
The result will be null-terminated.
Scanf() returns the number of successfully
matched
and
assigned
input items.
If the end of input was
reached,
EOF (-1) is returned.
For example:
main()
{
register int
int
char
c;
i;
text[10];
c = scanf("%d%9s", &i, &text);
printf("i = %d, text = %s\n",
i, text);
}
If the input line is
"150
foobar",
the
program
will
print:
i = 150, text = foobar
Diagnostics
Scanf() returns -1 if an end of
file
(end
of
string)
condition
exists and no data was stored.
It returns -
2
if
a
palpably
is
encountered.
Bugs
incorrect
format,
such
as
"%"
C Compiler and Library
Page
5-182
screen
5.148
Screen I/O Primitives
Screen I/O Primitives
______ ___
__________
**********
* screen *
**********
File name:
screen.mac
Usage
scdown()
/* Roll screen down
*/
scerln(line, column)
/* Erase to end of line */
int
line;
/* Line number
*/
int
column; /* Column number
*/
scerpg(line, column)
/* Erase to end of page */
int
line;
/* Line number
*/
int
column; /* Column number
*/
char *
scget(buff, size, text)
char
int
char
*buff;
size;
*text;
int
sclmargin(lmarg)
int
lmarg;
/*
/*
/*
/*
Prompt and read
Returned text
Buffer size
Optional prompt
*/
*/
*/
*/
/* Set left margin
/* New left margin
*/
*/
scout(line, column, text)
/*
int
line;
/*
int
column; /*
char
*text; /*
scput(oldbf)
Write text to screen */
Line number
*/
Column number
*/
Text to write
*/
/* Reset buffer mode
*/
char
*oldbf; /* Previous buffer
*/
int
scset(newbf, size, old)
char
/* Set buffer mode
*newbf; /* New buffer
*/
*/
C Compiler and Library
Page
5-183
screen
Screen I/O Primitives
char
char
size;
**old;
/* Size of new buffer
*/
/* Previous buffer save */
int
scsettype(type)
int
type;
/* Force terminal type
/* Terminal type
int
sctype()
/* Return terminal type */
*/
*/
Description
Based on the "terminal independent screen procedures"
in
the
VAX/VMS
runtime library, these routines provide
an
efficient, operating-system
independent,
interface
to
(DIGITAL)
video
terminals.
VT52
VT100
(ANSI)
They
work correctly
with
and
terminals
and
do
nothing
disasterous if the terminal is not a video terminal.
Note
that
they
only
work
with
the
user's
console
(stderr) terminal.
The following definitions should be noted:
line
The line on
the
screen
to
which
the
cursor
is
to be moved.
The top of
the
screen is line one.
If
line
is
less
than
or
equal to zero, the cursor
does
not move.
column
The column to which the cursor is to
be
moved.
the
This value will be offset by
left-margin value (if one is set).
The
default
left-hand margin is column
one.
If column
(after
offsetting)
is
less
than
or
equal to zero, the cursor
does
not move.
text
A null-terminated string to
be
output.
If
text
equals NULL, nothing is
output
and internal buffers are flushed.
The routines are designed to operate in a buffered
mode,
allowing
the
program
to
format
an
entire screen
of
information and present this data with one call
to
the
monitor-level
I/O
service.
This
is
particularily
efficient
on
multi-user
or
networked
systems.
The
routines
scput()
and
scset()
establish
and
release
buffer mode.
Buffers can be chained together,
allowing
a
subroutine to establish a buffer independently of
its
callers.
long.
Each buffer must be at least
12
bytes
C Compiler and Library
Page
5-184
screen
Screen I/O Primitives
Longer buffers are more efficient.
Although multiple buffers can be established,
only
one
is
active at any particular time.
If a call to
scset()
establishes a new buffer, the contents of
the
previous
buffer
are
copied
to
the new buffer and the
previous
buffer is set empty.
If scput() releases a buffer,
its
contents are copied to any higher-level buffer.
The first call to any routine
determines
the
terminal
type.
Note
that on native RT11, if the screen
handler
decides that the terminal may be a scope, it
will
send
an
"identify" request "<ESC>/Z" to determine whether
it
is a VT52 or VT100.
If the screen routine decides
that
the
terminal is not a scope, cursor move operations
are
ignored and text is output to "stderr".
If
the
screen
handler decides that the terminal is a VT100, the
"Enter
ANSI mode" escape sequence will be sent to the
terminal.
Similarily, if the terminal is thought to be a VT52,
the
"Enter VT52 emulation mode" sequence will be sent.
The
screen
handler
will
not
record
the current mode
for
subsequent resetting.
Screen output will be to the "stderr" device
(explicitly
the
console
terminal).
Input will be from the
"stdin"
device.
If a local buffer
has
been
established,
the
screen
directly,
handler calls operating system service
bypassing the "standard" I/O library.
This
means
that
output
formatting should use sprintf() to format a
buffer
which
user
is
subsequently
output
using
scout().
Furthermore,
the
newline
'\n'
character
will not
be
expanded to a "carriage return/line feed" sequence.
It
is thus highly recommended that the user program
perform
all formatting by passing
appropriate
row
and
column
values to scout().
The following routines are defined:
scdown()
The cursor is moved up one line on the screen.
If
the
cursor
was
already
at the top line on the screen,
all
lines are moved down one line, the top line is
replaced
with
a
blank, and the data that was on the bottom
line
is lost.
(VMS Lib$Down_Scroll)
scerln(line, column)
Erase the screen from the indicated (or current)
cursor
position
to
(VMS
Lib$Erase_Line)
the
end
of
the
current
line.
C Compiler and Library
Page
5-185
screen
Screen I/O Primitives
scerpg(line, column)
Erase the screen from the indicated (or current)
cursor
position to the end of the screen.
(VMS
Lib$Erase_Page)
scget(buff, size, text)
Output
the
prompt
text,
if
given,
then
flush
any
buffered
text.
Read
text
input by the terminal
user
(from stdin) to the buffer.
Scget() returns NULL on
end
of
file or error.
(Scget calls fgetss() to perform
the
read.) (VMS Lib$Get_Screen) Programs
using
scget()
to
read
from
the
keyboard
should
not
use
the
input
redirection capabilities of the C library.
sclmargin(lmarg)
Define a new left
margin
(if
lmarg
is
greater
than
zero).
Sclmargin() returns the old lmarg value.
After
calling sclmargin(), an output
request
to
column
and
column
one
will be written to column lmarg.
scout(line, column, text)
Move the cursor to the indicated
line
and
output
the
text.
If
line or column are less than
or
equal to zero, the cursor is
not
moved.
If
buffers
are
text
is
equal
to
NULL,
the
internal
flushed
(possibly after cursor movement).
(VMS Lib$Put_Screen)
scput(oldbf)
Scput()
terminates
reverts
to
the
current
buffering
mode
and
the
previous
mode
as
specified
in
the
parameter.
If oldbuf is NULL, buffering
is
terminated
and
the
current
buffer
is flushed to the screen.
If
oldbuf is not zero, it is taken as
the
location
of
a
previous buffer (established by calling scset()) and
the
current buffer is copied into the previous buffer.
The
previous
buffer
is
then
made
current.
(VMS
Lib$Put_Buffer)
scset(newbf, size, old)
Scset()
establishes
a
new
buffer
for
the
screen
routines.
Newbf
is
a
character
array whose size
is
given in parameter
size
(Size
must
be
at
least
12
bytes.)
Old
is the address of a word which will be
set
to the previous buffer (if any).
a
This
is
used
for
C Compiler and Library
Page
5-186
screen
Screen I/O Primitives
subsequent
call
to
scput().
Scset
returns
zero
if
correct, returning -1 if size was less
than
12
bytes.
(VMS Lib$Set_Buffer).
A larger buffer will generally yield
a
more
efficient
program
as the number of operating system requests
will
be minimized.
For example, for
a
typeout
program,
a
buffer size of 800 bytes might well be used.
scsettype(type)
This routine sets
the
terminal
type,
overriding
the
definition
supplied
by
the
operating
system.
scsettype() returns what it thought the type was (as
if
sctype
were
called).
The
type
must
be
one of
the
following values:
0
65
97
If type has
Not a video terminal
VT52 or VT100 in VT52 mode
VT100 in ANSI mode
some
other
value,
scsettype()
not
change the type.
sctype()
This routine returns the terminal type.
following
types are defined:
0
1
1+64
1+96
Not a video terminal
Unknown video terminal
VT52
VT100 type
The
does
Note:
On intitialization, a VT100 will be
forced
into
VT52
or
VT100
mode
depending on the determined
type.
VT100-type terminals include newer terminals such as
the
VT125.
It
is
not clear whether the algorithm used
is
correct for terminals
developed
since
these
routines
were written.
Note the following normal use of scset() and scput()
char
char
**oldbuf;
mybuf[100];
main()
{
/*
* Setup
*/
scset(mybuf, sizeof mybuf, &oldbuf);
C Compiler and Library
Page
5-187
screen
Screen I/O Primitives
/*
* Usage
*/
scout(1, 1, "Stuff");
/*
* Termination (force out last buffer)
*/
scout(0, 0, NULL);
scput(oldbuf);
}
Bugs
These routines are fairly inefficient if
no
buffer
is
supplied.
Determining the terminal type turns out to be a
somewhat
painful
process
which
is
different
for
the
various
operating systems:
On native RSX-11M and VMS compatibility
mode,
the
QIO
"get multiple characteristics function" is executed.
If
the
terminal
is
a
scope
and
can
generate
escape
sequences, it is assumed to be a VT100, otherwise, if
it
is a scope, it is assumed to be a VT52.
On all
RSTS/E
systems,
the
executive
"get
terminal
characteristics"
request is executed, the
determination
proceeding as above.
On native RT11 systems, a peek sequence described in
the
RT11
Software
Support
manual
is
used
to
determine
whether the terminal is a scope.
(This may not work
on
the
request
XM monitor.) If so, an "<ESC>/Z" is sent to
identification
and
various
tests
are
made
on
the
returned
text.
Note
that,
if
the terminal does
not
reply to the inquiry,
the
program
will
hang.
These
tests
are valid for VT52 and VT100 terminals only.
You
will have to modify this routine if
you
have
anything
else (including a VT125).
On RSX-11M systems (even emulated), if a local buffer
is
established
by
calling
scset(),
output
will be
done
using the IO.WAL QIO function.
While based on
the
VMS
Run-time
library
screen
I/O
primitives,
there
are a few differences that may be
of
interest:
The
VMS
library
standard
assumes
that
subroutines
generally
return
a
status
code,
permit
missing
parameters, and return error codes
presented
on
being
C Compiler and Library
Page
5-188
screen
Screen I/O Primitives
with
invalid arguments.
The routines described here
do
nothing when arguments are out of
range.
Also,
there
are
no
optional arguments (optionality is provided
for
by specifing
zero
or
NULL
argument
values).
Where
appropriate,
arguments
have
been
ordered
"line_no,
col_no, other".
A more significant difference is that
the
VMS
library
writes
to
the
standard output device (SYS$OUTPUT:
or
TT:) while these routines write to the
user's
terminal
(SYS$ERROR
standard
input.
or
CO:).
scget()
reads from the
C Compiler and Library
Page
5-189
setcc
Trap Control/C (RSTS/E RT11 mode only)
5.149 Trap Control/C (RSTS/E RT11 mode only)
____ _________ _______ ____ ____ _____
*********
* setcc *
*********
File name:
setcc.mac
Usage
setcc(function);
extern int function();
Description
The function
is
defined
as
a
CTRL/C
trap
routine.
Executing setcc(0) disables CTRL/C trapping.
Note:
If the routine is reentered (because
typed
during
CTRL/C
was
the execution of function()), the
program
aborts.
Bugs
Runs on RSTS/E RT11 mode only.
C Compiler and Library
Page
5-190
setjmp
5.150
Execute non-local goto
Execute non-local goto
_______ _________
____
**********
* setjmp *
**********
File name:
setjmp.mac
Usage
#include <setjmp.h>
setjmp(env);
jmp_buf
env;
longjmp(env, val)
jmp_buf
env;
int
val;
/* Static save buffer
*/
/* Was set by setjmp
/* Value to return
*/
*/
Description:
These routines are useful for dealing
with
errors
and
interrupts
encountered
in
a low-level subroutine of
a
program.
Setjmp() saves its stack environment in
env
for
later
use by unwind().
It returns 0.
Longjmp(env) restores the environment saved by the
last
call of setjmp(env).
It then returns in such a way
that
execution continues as if the call of setjmp() had
just
returned.
All
accessible
data
have values as of
the
time setjmp() was called.
The
return
from
setexit()
will have the specified value.
For example:
#include <setjmp.h>
jmp_buf
env;
...
main() {
...
if (setjmp(&env) != 0) {
err_exit(); /* Longjmp called
}
else {
process(); /* Setjmp called
}
...
process() {
...
*/
*/
C Compiler and Library
Page
5-191
setjmp
Execute non-local goto
longjmp(&env);
The routine that called setjmp() must
active
when longjmp() is called.
Bugs
still
be
C Compiler and Library
Page
5-192
sleep
Delay job a given number of seconds
5.151 Delay job a given number of seconds
_____ ___ _ _____ ______ __ _______
*********
* sleep *
*********
File name:
sleep.mac
Usage
sleep(delay);
int
delay;
Description
Sleep a specified number of seconds.
Bugs
On RSTS/E, the reader should refer to the description
of
SLEEP() in the operating system documentation.
On native
RSX-11M
or
RSX
emulated
by
VMS,
sleep()
executes
a
mark-time
(MRKT$) and wait sequence,
using
event flag 1.
On native RT11,
sleep()
executes
executive
request.
Sleep flushes stdout and stderr.
a
.TWAIT
C Compiler and Library
Page
5-193
sprintf Formatted Numeric Conversion
5.152 Formatted Numeric Conversion
_______ __________
_________
***********
* sprintf *
***********
File name:
sprint.mac
Usage
char *
sprintf(buffer, format, arg1, ...);
char
*buffer;
char
*format;
Description
sprintf() converts and formats
its
arguments,
writing
the result to the indicated string buffer.
For information
on
formatting,
please
refer
to
the
description of printf.
sprintf() returns a pointer to the EOS byte at
the
end
of
the output buffer.
Note, however, that this
feature
is not transportable to other C implementations.
Bugs
C Compiler and Library
Page
5-194
sscanf
Formatted input conversion
5.153 Formatted input conversion
_____ __________
_________
**********
* sscanf *
**********
File name:
sscanf.mac
Usage
sscanf(buf, fmt, pointer(s))
char
*buf;
/* Output buffer
char
*fmt;
/* Format string
*/
*/
Description
sscanf() parses the input string, in buf,
according
to
the
indicated format descriptor, storing the results
the
pointer
in
arguments.
It
returns
the
number
of
successfully assigned input items.
See
the
description
of
scanf()
for
further
documentation.
Diagnostics
Sscanf() returns -1 if the end of the input
string
was
detected
and
no
data
was stored.
It returns -2 if
a
palpably incorrect format, such as "%" is encountered.
Bugs
C Compiler and Library
Page
5-195
strcat
5.154
String Concatenate
String Concatenate
______ ___________
**********
* strcat *
**********
File name:
strcat.mac
Usage
char *
strcat(out, in);
char
*out;
char
*in;
Description
Append "in" to "out".
Bugs
Return out.
C Compiler and Library
Page
5-196
strchr
Find First Instance of a Character in a String
5.155 Find First Instance of a Character in a String
____ _____ ________ __ _ _________ __ _ ______
**********
* strchr *
**********
File name:
strchr.mac
Usage
char *
strchr(stng, chr)
char
*stng;
char
chr;
/* String to search in
/* Byte to search for
*/
*/
Description
If chr is in stng, return a
pointer
to
it.
If
not,
return NULL.
strchr(NULL, anything) returns NULL.
See also index().
Bugs
C Compiler and Library
Page
5-197
strcmp
5.156
String Compare
String Compare
______ _______
**********
* strcmp *
**********
File name:
strcmp.mac
Usage
int
strcmp(s1, s2);
char
*s1;
char
*s2;
Description
Compare two strings, returning
-1 if s1 < s2
0 if s1 == s2
+1 if s1 > s2
Bugs
C Compiler and Library
Page
5-198
strcpy
5.157
String copy
String copy
______ ____
**********
* strcpy *
**********
File name:
strcpy.mac
Usage
char *
strcpy(out, in);
char
*out;
char
*in;
Description
Copy "in" to "out".
Return out.
Bugs
It might be more useful if it returned out +
strlen(in).
(See cpystr()).
C Compiler and Library
Page
5-199
streq
5.158
String Equality Test
String Equality Test
______ ________
____
*********
* streq *
*********
File name:
streq.mac
Usage
streq(a, b);
char
char
*a;
*b;
Description
Return TRUE if the strings are equal.
Bugs
C Compiler and Library
Page
5-200
strlen
5.159
String length
String length
______ ______
**********
* strlen *
**********
File name:
strlen.mac
Usage
int
strlen(s);
char
*s;
Description
Return the length of the argument string.
Bugs
C Compiler and Library
Page
5-201
strncat String Concatenate
5.160
String Concatenate
______ ___________
***********
* strncat *
***********
File name:
strnca.mac
Usage
char *
strncat(out, in, count);
char
*out;
char
*in;
unsigned int
count;
Description
Append "in" to "out".
Return
out.
At
most,
"count"
bytes
are
moved
from
in.
not
include the trailing null.
Bugs
Note that "count" does
C Compiler and Library
Page
5-202
strncmp String Compare With Count
5.161
String Compare With Count
______ _______
____ _____
***********
* strncmp *
***********
File name:
strncm.mac
Usage
int
strncmp(s1, s2,
char
char
unsigned int
count);
*s1;
*s2;
count;
Description
Compare
at
most
count
strings,
returning:
-1 if s1 < s2
0 if s1 == s2
+1 if s1 > s2
Bugs
bytes
between
two
C Compiler and Library
Page
5-203
strncpy String Copy With Count
5.162
String Copy With Count
______ ____ ____
_____
***********
* strncpy *
***********
File name:
strncp.mac
Usage
char *
strncpy(out, in, count);
char
*out;
char
*in;
unsigned int
count;
Description
Copy "in" to "out".
Return out.
At most, "count"
bytes
are
moved
from
in.
Note
that
"count" includes
the
trailing null.
If strlen(in) is less than count, "out" is null-filled.
If strlen(in) is greater than count, the
buffer
will not be null-trailed.
Bugs
output
C Compiler and Library
Page
5-204
strneq
String Equality Test With Count
5.163 String Equality Test With Count
________ ____ ____ _____
______
**********
* strneq *
**********
File name:
strneq.mac
Usage
int
strneq(s1, s2, count);
char
*s1;
char
*s2;
unsigned int
count;
Description
Compare
at
most
count
bytes
between
two
strings,
returning TRUE if the the strings are equal.
Bugs
C Compiler and Library
Page
5-205
strrchr Find Last Instance of a Character in a String
5.164 Find Last Instance of a Character in a String
____ ____ ________ __ _ _________ __ _ ______
***********
* strrchr *
***********
File name:
strrch.mac
Usage
char *
strrchr(stng, chr)
char
*stng;
char
chr;
/* String to search in
/* Byte to search for
*/
*/
Description
If chr
is
in
stng,
return
a
pointer
to
the
last
(rightmost) occurrance of it.
If not, return NULL.
strchr(NULL, chr) returns NULL.
Bugs
C Compiler and Library
Page
5-206
swabb
Byte swap (argument is a buffer pointer)
5.165 Byte swap (argument is a buffer pointer)
____ ____ _________ __ _ ______ ________
*********
* swabb *
*********
File name:
swabb.mac
Usage
swabb(buffer);
char
*buffer;
Description:
Return
buffer[0]
and
buffer[1]
as
a
byte-
swapped
integer.
Buffer
or
word boundary.
Bugs
need not be on any particular byte
C Compiler and Library
Page
5-207
swabi
Byte swap, (argument is an integer)
5.166 Byte swap, (argument is an integer)
_____ _________ __ __ ________
*********
* swabi *
*********
File name:
swabi.mac
Usage
swabi(value);
int
value;
Description
Return value byte-swab'ed.
Bugs
____
C Compiler and Library
Page
5-208
time
5.167
Compute time of day
Compute time of day
_______ ____ __ ___
********
* time *
********
File name:
time.mac
Usage
long
time(0);
long
time(tloc);
long
*tloc;
Internal
call
$$time
Description
time returns the time of day in
seconds.
If
tloc
is
non-null,
the
return value is also stored in the
place
to which tloc points.
The value is
the
time
since
midnite,
Jan
1,
1970,
measured in seconds.
Internal
$$time is called by time and ftime.
It returns the
time
value in registers r0 and r1, and the number of ticks
in
the current second in r2.
R3 and r4 are modified.
On RSX, $$time refreshes $$tick.
Bugs
The Unix
time
function
returns
GMT.
This
function
returns local time.
The leap year algorithm is only accurate in the range
1970 <= year < 2100
C Compiler and Library
Page
5-209
toascii Convert to 7-bit Ascii
5.168
Convert to 7-bit Ascii
_____
***********
* toascii *
***********
File name:
toasci.mac
Usage
toascii(c);
int
c;
Description
Remove the parity bit from c.
Bugs
_______ __ _____
C Compiler and Library
Page
5-210
tod
5.169
Compute time of day
Compute time of day
_______ ____ __ ___
*******
* tod *
*******
File name:
tod.mac
Usage
long
tod(0);
long
tod(tloc);
long
*tloc;
Description
tod() returns the time of day in seconds.
If
tloc
is
non-null,
the
return value is also stored in the
place
to which tloc points.
tod() is fairly fast.
time() computes the
time"
but is much slower and larger.
Bugs
"Unix
C Compiler and Library
Page
5-211
tolower Convert upper-case to lower-case
5.170 Convert upper-case to lower-case
__________ __ __________
_______
***********
* tolower *
***********
File name:
tolowe.mac
Usage
tolower(c);
int
c;
Description
If c is a upper-case alphabetic, return it's
case
equivalent.
Bugs
Otherwise, return c.
lower-
C Compiler and Library
Page
5-212
toupper Convert lower-case alphabetic to upper-case
5.171 Convert lower-case alphabetic to upper-case
_______ __________ __________ __ __________
***********
* toupper *
***********
File name:
touppe.mac
Usage
toupper(c);
int
c;
Description
If c is a lower-case alphabetic, return it's
case
equivalent.
Bugs
Otherwise, return c.
upper-
C Compiler and Library
Page
5-213
trace
Profile support entry module (with trace)
5.172 Profile support entry module (with trace)
_______ _______ _____ ______ _____ ______
*********
* trace *
*********
File name:
pcsv.mac
Usage
#include <stdio.h>
extern FILE
*$$flow;
$$flow = fopen("trace.out", "w");
/* or $$flow = stderr; to trace to the console
...
$$flow = NULL;
/* Turn off flow trace
*/
*/
Internal
jsr
.word
r5,pcsv$
name
; Pointer to name
Where name has the structure:
name:
.word
.asciz
0
/name/
; Counter
; function name
This module is
called
whenever
Description
a
function
that
was
compiled with the profile option is executed.
It
that the stack will remain
when
checks
above
600
octal
the
function executes and optionally prints a flow-trace.
If $$flow is set to
function
a
file
descriptor,
the
name,
location
the
function
is
called from, and
the
calling environment, are
printed
on
each
call
to
a
function compiled with the profile option.
The output format is:
function_name<TAB>caller<TAB>environment
Where function_name is the name of
the
function
being
called,
caller
is
the
address of the calling
program
(actually, the return address), and environment
is
the
R5
the
argument
pointer
(for
local addressing within
C Compiler and Library
Page
5-214
trace
Profile support entry module (with trace)
routine being called).
The information will be
written
to $$flow with a newline before and after.
If profiling has been enabled and the program exits
via
error()
or
via
illegal
memory
an
operating-system
trap (such as
an
reference),
a
register
dump
and
subroutine trace will be written to stderr.
See the description of calltrace() for details.
Internal
See csv$ for details of the calling environment.
When this routine is entered for the first time, it
sets
up
to intercept synchronous system traps, and loads
the
error
exit
address
and
profile
pointer.
The
trap
service
routines
are
in
the "traps" module.
the
description there for more information.
Bugs
See
C Compiler and Library
Page
5-215
traps
Operating system trap handlers
5.173 Operating system trap handlers
______ ____ ________
_________
*********
* traps *
*********
File name:
traps.mac
Usage
Internal
$$sstt::
; RSX synchronous trap
; vector
$$t410::
; RT11 Entry after traps
; to vectors 4 and 10
Description
This module contains code
which
is
executed
after
a
synchronous
trap
is
detected by the operating
system.
All such traps are regarded
as
fatal
errors
and
the
program will be terminated.
This code is enabled by executing any function, such
as
main(),
for
which
profiling
was
enabled
when
the
function was compiled.
The following traps are processed:
Illegal memory reference (trap through vector
4)
Illegal instruction (trap through vector 10)
BPT (assuming a debugging aid is not present)
IOT
Illegal TRAP (this may be a Fortran error)
Illegal EMT (RSX only)
Floating point exception (RSX only)
Memory management violation
Before exiting to the operating system, the registers
at
the time the trap occurred will be written, in octal,
to
stdout.
Note also that
a
calling
sequence
traceback
will be written to stdout by error().
If a
trap
occurred,
the
program
will
exit
the
operating system with a "severe error" status.
Note that some errors, such as stack overflow or
random
to
C Compiler and Library
Page
5-216
traps
Operating system trap handlers
jumps into the operating system, may cause the C
program
to
be
terminated
without
the
C
library
regaining
control.
Internal
The first call to pcsv$
will
initialze
trapping.
On
RSX11-M, the SVTK$ executive service will be called.
On
RT11, the .tprset monitor request will be executed.
As
.trpset
only traps illegal memory reference (trap to
4)
and
illegal
instruction
(trap
to
10),
the
other
interesting
vectors
are
initialized
by
absolute
references (.ASECT).
Diagnostics
Bugs
Internal
Don't
forget
it's
implemented.
to
handle
floating-point
when
C Compiler and Library
Page
5-217
ungetc
Push back a character onto an input file
5.174 Push back a character onto an input file
____ ____ _ _________ ____ __ _____ ____
**********
* ungetc *
**********
File name:
ungetc.mac
Usage
ungetc(c, iop);
char
c;
FILE
*iop;
Description
Push one character back on the indicated stream.
Bugs
C Compiler and Library
Page
5-218
unwind
5.175
Execute non-local goto
Execute non-local goto
_______ _________
____
**********
* unwind *
**********
File name:
unwind.mac
Usage
setexit();
unwind();
Description:
These routines are useful for dealing
with
errors
and
interrupts
encountered
in
a low-level subroutine of
a
program.
setexit() saves its stack environment in a static
place
for later use by unwind().
It returns 0.
Unwind() restores the environment saved by the last
call
of
setexit().
It
then
returns
in
such
a way
that
execution continues as if the call of setexit() had
just
returned.
All
accessible
data
have values as of
the
time unwind() was called.
The
return
from
setexit()
will have the value 1.
For example:
if (setexit()) {
/* Unwind called
}
else {
*/
/* Setexit setup called */
}
The routine that called setexit() must still
active
when unwind() is called.
Bugs
Obsolete -- use setjmp/longjmp instead.
be
C Compiler and Library
Page
5-219
wdleng
Expensive way to say sizeof(int)
5.176 Expensive way to say sizeof(int)
_________ ___ __ ___ ___________
**********
* wdleng *
**********
File name:
wdleng.mac
Usage
wdleng()
Description
Return word length in bits.
Bugs
Assuming 8-bit bytes, this may be replaced by:
#define wdleng() (sizeof (int) * 8)
C Compiler and Library
Page
5-220
wrapup
Dummy routine called on exit
5.177 Dummy routine called on exit
_______ ______ __ ____
_____
**********
* wrapup *
**********
File name:
wrapup.mac
Usage
wrapup()
Description
This routine (which does nothing) is called on
exit
if
the user's program does not provide a wrapup() routine.
Wrapup will be called only once.
Bugs
C Compiler and Library
Page
5-221
zero
5.178
Clear a block of memory
Clear a block of memory
_____ _ _____ __
______
********
* zero *
********
File name:
zero.mac
Usage
zero(addr, nbytes);
char
*addr;
unsigned int
nbytes;
Description:
Clear the block of core.
Bugs
No value is returned.
CHAPTER 6
LIBRARY HEADER FILES
This chapter contains descriptions of the standard header
files
that
are
used
by
C
programs
and
libraries.
In
addition,
descriptions of internal routines are provided.
These
files
are
included
in
your
a
pre-processor command of the form:
#include <filename.h>
program
source
by
C Compiler and Library
Page
6-2
ctype
Character test macros and global definitions
6.1 Character test macros and global definitions
_________ ____ ______ ___ ______ ___________
*********
* ctype *
*********
File name:
NAME:
ctype.h
ctype -- Character test macros and global definitions
SYNOPSIS:
#include <ctype.h>
DESCRIPTION:
This
module
defines
a
set
of
character
test
and
manipulation
macros
(or,
on
Decus C, functions)
that
allow
classification
and
modification
of
Ascii
characters.
If
the
C
compiler
supports macros
with
arguments, the following are defined:
isupper(c)
islower(c)
isalpha(c)
isdigit(c)
isalnum(c)
isxdigit(c)
isspace(c)
ispunct(c)
isgraph(c)
isprint(c)
iscntrl(c)
isascii(c)
_toupper(c)
_tolower(c)
toascii(c)
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
Upper case alphabetic
Lower case alphabetic
Alphabetic in any case
Decimal digit
Alphabetic or digit
Hexadecimal digit
Space or tab
Punctuation
Visible character
Printable character
Control character
7-bit Ascii character
Lower case convert to Upper
Upper case convert to Lower
Remove eighth (parity) bit
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
Note that _toupper() and _tolower()
must
not
be
used
with arguments that have side effects, such as
_toupper(*ptr++);
Use the functions toupper() and tolower() instead.
BUGS:
C Compiler and Library
Page
6-3
fps
Bit definitions for the floating point status word
6.2 Bit definitions for the floating point status word
___ ___________ ___ ___ ________ _____ ______ ____
*******
* fps *
*******
File name:
NAME:
fps.h
fps -- Bit definitions for
the
floating
point
status
word
SYNOPSIS:
#include <fps.h>
DESCRIPTION:
This module defines common
definitions
for
the
FP-
11
floating point status word.
FER
FID
FIUV
FIU
FIV
FIC
FD
FL
FT
FN
FZ
FV
FC
0100000
0040000
0004000
0002000
0001000
0000400
0000200
0000100
0000040
0000010
0000004
0000002
0000001
The following are defined:
Floating error (sense/reset)
Disable all interrupts
Interrupt on undefined variable
Interrupt on underflow
Interrupt on overflow
Interrupt on int. conv. error
Double precision mode
Long integer mode
Chop mode
Floating negative (sense)
Floating zero
(sense)
Floating overflow (sense)
Floating carry
(sense)
C Compiler and Library
Page
6-4
initial Specify Initializers and Finalizers
6.3 Specify Initializers and Finalizers
____________ ___ __________
_______
***********
* initial *
***********
File name:
NAME:
initia.h
initial -- Specify Initializers and Finalizers
SYNOPSIS:
#include <initia.h>
INITIAL
{ initial-code-block };
FINAL
{ final-code-block };
DESCRIPTION:
The macros defined in this module provide a facility
for
module-specific
initialization
and
finalization
code.
The code in the initial-code-block is called as a
normal
C
function
before
main()
is
called;
the
final-code-block is called on exit, just after
wrapup().
Neither call passes any arguments.
Any number of modules
in
an
image
may
independently
declare initializers or finalizers;
all of them will
be
called at startup or exit.
to
However, it is impossible
predict
what
order
the
calls
will
be
made in,
and
programs should not rely on any particular ordering.
A typical use of
initializers
and
finalizers
is
the
following:
Suppose
you
have
a package that
supports
access to some on-disk data base;
a user of the
package
will
call
a
lookup
and an update function.
The
file
containing the data
base
must
be
opened
before
any
operations on it can take place, and it should be
closed
when the program is finished.
(Assume that the
package
maintains
some
sort
of
resident buffer which it
must
flush.) There are two conventional approaches to
solving
this
problem:
Have
the
lookup
and update
functions
check the file on each call, and open it if necessary
which
small
could
be
quite expensive if they are very
C Compiler and Library
Page
6-5
initial Specify Initializers and Finalizers
functions, and in any case does not solve the problem
of
properly
closing
the
file
- or have the main
program
call an initialization and finalization function at
the
proper
time.
The problem with this latter approach
is
lack of modularity - the main program ought not to
have
to
know
that
the
module
needs
initialization
or
finalization.
The solution using these macros is straightforward.
The
defining module includes the calls:
INITIAL
{ open-the-data-base };
FINAL
{ flush-buffers-and-close-the-data-base };
The
wrapup()
function
is
treated
like
a
built-
in
finalizer;
however, it is guaranteed to execute
before
any other finalizers.
(The module defining wrapup()
may
declare
an
initializer
or finalizer if it wishes;
it
will be treated just like
all
other
initializers
and
finalizers.)
If any finalizer (or wrapup()) calls exit(), the
program
exits immediately.
Notes:
Using INITIAL will
declare
a
static
function
named $init$(), and a (char *) named $init_;
similarly,
FINAL will declare
$finl$()
and
$finl_.
Also,
both
INITIAL
C
and
FINAL
generate
dsect
commands.
Since
provides no way to "remember" the
current
dsect,
both
macros
issue
a
dsect
""
command when they are
done,
restoring the C default dsect.
While it is a poor idea to write code
that
depends
on
the
order
in
which
initializers
and
finalizers
are
executed, this can be useful
information
to
have
for
debugging.
Execution
is
always in the order that
the
modules involved were examined by the
task
builder
or
linker.
When
the
modules
are named explicitly,
this
will just be the order in which they were
named.
When
the
modules
come
from a library, it will be
extremely
difficult to predict the order in
which
they
will
be
extracted and linked in.
Warning:
While initializers and finalizers provide
some
modularity
to
package initialization and
finalization,
they are not a panacea.
For example, if package A
calls
routines
in package B from within its initializers,
and
package
B
also
declares
initializers,
the
correct
functioning
of a program that includes both - hence,
of
any program using package A - will be problematical.
C Compiler and Library
Page
6-6
initial Specify Initializers and Finalizers
INTERNAL:
The macros operate by leaving a list
of
(pointers
to)
functions
to be called in psects $INIT$ and $FINL$.
In
order to be able to determine the beginning and
end
of
these
psects,
the
psects
$INIT,
$FINL,
$INIT.,
and
$FINL.,
are
also
reserved.
These
psects
must
not
actually contain any data;
they exist solely to
provide
well-defined
endpoints
to
the
The
names
initialization
and
finalization
list.
are
consecutive
in
alphabetical sequence, so the Task
Builder
will
place
them
in order.
The RT11 Linker, however - and the
Task
Builder with the /SQ switch - place psects in the
order
they
are
encountered.
Since it impossible to
predict
what order the various
modules
will
be
seen
by
the
linking
program, it is essential that EVERY module
that
refers to any of these psects refer to the
two
related
ones as well, and in the correct order.
BUGS:
Requires
the
DECUS
C
dsect
commands;
hence,
very
non-portable.
It
may
functionality
using
be possible to provide the
same
different
techniques;
not,
what's wrong with your implementation?
AUTHOR:
Jerry Leichter
if
C Compiler and Library
Page
6-7
rtime
Define time buffer structure for $$rtime()
6.4 Define time buffer structure for $$rtime()
______ ____ ______ _________ ___ _________
*********
* rtime *
*********
File name:
NAME:
rtime.h
rtime -- Define time buffer structure for $$rtime()
SYNOPSIS:
#include <rtime.h>
...
struct TIME buffer;
DESCRIPTION:
This header file
defines
the
structure
of
the
time
buffer
used
by the standard library $$rtime()
function
(which is unique to Decus C).
It is defined as
follows:
struct TIME {
int
int
int
int
int
int
int
int
};
year;
month;
day;
hour;
minute;
second;
tick;
tsec;
G.TIYR
G.TIMO
G.TIDA
G.TIHR
G.TIMI
G.TISC
G.TICT
G.TICP
year - 1900
Jan. = 1
00 .. 23
00 .. 59
00 .. 59
00 .. tsec-1
tick/second
BUGS:
Oboslete, use time() and localtime() instead.
C Compiler and Library
Page
6-8
setjmp
Define buffer for setjump() and longjump()
6.5 Define buffer for setjump() and longjump()
______ ______ ___ _________ ___ __________
**********
* setjmp *
**********
File name:
NAME:
setjmp.h
setjmp -- Define buffer for setjump() and longjump()
SYNOPSIS:
#include <setjmp.h>
DESCRIPTION:
This defines the jmp_buf array
that
the
setjmp() and longjmp() functions.
BUGS:
is
used
for
C Compiler and Library
Page
6-9
stdio
Definitions for standard i/o library
6.6 Definitions for standard i/o library
___________ ___ ________ ___ _______
*********
* stdio *
*********
File name:
NAME:
stdio.h
stdio -- Definitions for standard i/o library
SYNOPSIS:
#include <stdio.h>
DESCRIPTION:
<stdio.h> should be included in the assembly
of
all
C
programs
that
use
the
standard i/o library
(fopen(),
getc(), printf(), etc.)
It defines the following:
FILE
The
i/o
routines
use
and
return pointers
to
objects of this type.
NULL
I/O routines signal "rejection" by
returning
a
null pointer.
EOF
The get character routine returns this value
to
signal end of file.
TRUE
The value 1.
FALSE The value 0.
EOS
The "end of string" marker: '\0'.
IO_SUCCESS Normal exit to operating system.
IO_WARNING "Warning error" exit to operating system.
IO_ERROR
"Error" exit to operating system.
IO_FATAL
"Severe error" exit to operating system.
stdin
The "standard" input file. Normally the user's
terminal; it may be redirected.
C Compiler and Library
Page
6-10
stdio
Definitions for standard i/o library
stdout
The "standard" output file.
Normally the
user's
terminal; it may be redirected.
stderr
The "error" output file.
to the user's terminal.
It will always write
DIFFERENCES FROM UNIX:
FILE is defined as a
"typedef
struc",
rather
than
a
#define.
The
i/o
structure is considerably
different
from Unix.
It is, however, arranged so that
reasonable
compatibility
may
be
attained.
Specifically,
things
which have the same name are used for the same
purpose,
and located in the same place within the I/O structure.
ACCESSING THE FDB ON RSX MODES:
The FDB (file
data
block)
is
the
primary
means
of
communication between the C I/O library and the RSX
file
control services modules.
It contains file
and
record
format
information as well as pointers and counters
for
accessing data in the file.
It
is
highly
recommended
that
you
do
not
access
this
information
directly.
Should you need to do so, the following may be done:
extern char *F_RTYP; /* F.RTYP (char) in fdb */
extern char *F_SEQN; /* F.SEQN (int) in fdb */
...
fd = fopen("file.nam", "r");
/*
* Set rtyp to the record type, stored as a
* byte at offset F.RTYP
*/
rtyp = fd->io_fdb[(int) &F_RTYP] & 0377;
/*
* set seqn to the sequence number (printfile
* fixed header), stored as an integer at
* offset F.SEQN.
*/
seqn = *((int *) &fd->io_fdb[(int) &F_SEQN]);
The somewhat messy use of casts
and
addressing
allows
the
program to use the value of F.xxx stored in the
RSX
system library.
BUGS:
TRUE, FALSE, and EOS are not
present
in
<stdio.h>
on
some other C systems.
If you compile with the /r switch (-r on RSX
modes)
or
#define
rsts before #include <stdio.h>, a native
RSTS/E
I/O vector
will
be
defined
which
fully
supported nor fully implemented.
is
neither
C Compiler and Library
Page
6-11
time
Define time buffer structure for localtime()
6.7 Define time buffer structure for localtime()
______ ____ ______ _________ ___ ___________
********
* time *
********
File name:
NAME:
time.h
time -- Define time buffer structure for localtime()
SYNOPSIS:
#include <time.h>
...
extern struct tm *localtime();
DESCRIPTION:
This header file
defines
the
structure
of
the
time
buffer
used
by
the
standard
library
localtime()
function.
It is defined as follows:
struct tm {
int
tm_sec;
int
tm_min;
int
tm_hour;
int
tm_mday;
int
tm_mon;
int
tm_year;
int
tm_wday;
int
tm_yday;
int
tm_isdst;
};
/*
/*
/*
/*
/*
/*
/*
/*
/*
Seconds
Minutes
Hours
Day in month
Month
Year
Weekday
Days since Jan 1
Daylight Savings = 1
*/
*/
*/
*/
*/
*/
*/
*/
*/
extern struct tm *localtime();
BUGS:
Unix V7 changed the tm_isday to tm_isdst.
Thanks guys.
C Compiler and Library
Page
6-12
timeb
Define timeb buffer structure for ftime()
6.8 Define timeb buffer structure for ftime()
______ _____ ______ _________ ___ _______
*********
* timeb *
*********
File name:
NAME:
timeb.h
timeb -- Define timeb buffer structure for ftime()
SYNOPSIS:
#include <timeb.h>
...
extern long ftime();
DESCRIPTION:
This header file defines
the
structure
of
the
timeb
buffer
used
by
the standard library ftime()
function.
It is defined as follows:
struct timeb {
long
unsigned
short
short
};
time;
milltim;
timezone;
dstflag;
The time value is identical to the value returned by
the
time()
function.
Milltim is the number of
milliseconds
in the current second.
Timezone indicates the number
minutes
the
of
past
GMT
in
current time zone (zero
for
Decus C) and dstflag is set if Daylight Savings Time
is
in effect.
APPENDIX A
IMPLEMENTATION
A.1
Overview
________
This document describes the Decus C distribution
and
discusses
its implementation on RSTS/E, RSX-11M, RT-11, and VAX/VMS.
A.2
Distribution
____________
NOTE
The following is in a state of change.
strategy is to have several kits:
The most
likely
1.
VMS backup format at 1600 bpi built on a VMS V3.2
system.
This will contain both source and compiled
images.
2.
DOS (FLX) format (source only) on two 1200 foot
magtapes at 800 or 1600 bpi. This will contain
source files only.
3.
RT11 RL02 disk containing a built system and sources
stored in "archive" format.
4.
RT11 RX01 disk containing built images
sources.
Suggestions for improvements are welcome.
only
--
no
The master source tape (DOS FLX)
was
generated
on
a
VAX/VMS
system.
All files contain readable Ascii text.
All
executable
images were generated by supplied command files.
The compiler and run-time library, accounts [5,1] through
[5,7],
comprise a compiler and run-time system for the C language.
The
compiler was written by David G.
Martin
Conroy, and modified by
C Compiler and Library
Page
A-2
Getting on the Air with Decus C
Minow,
Robert
B.
Denny, Clifford Geshke, and several
others.
The run-time libraries for RSX-11M and
RT-11
were
written
by
Martin
Minow
with
help from many friends.
In addition,
there
are several executive interface libraries:
one for
RSX-11M
by
Robert
B.
Denny,
one
for RSTS/E by Jim Burrows, and one
for
Vax/VMS (for interface with Vax-11 C) by Martin Minow.
There is also a portable math library by Fred Fish.
The program library, accounts
[6,1]
through
[6,7],
offers
a
collection
of
tools, games, and other programs, mostly
written
in C.
They are not needed
for
installation
of
the
compiler
(although
several
programs in the tools account, such as
KWIK,
are used to build the documentation.) In general, you should
be
aware that only the tools in [6,1] are tested.
The distribution account numbers were originally chosen so as
to
be identical under RSX-11M (octal) and RSTS/E (decimal).
If
the
C language system is not
stored
in
the
above
accounts,
the
implementor
on RSTS/E will have to edit command files to
define
the proper accounts.
The
GETCMD
and
BUILD
programs
be
useful in this regard.
[5,1]
[5,2]
[5,3]
[5,4]
[5,5]
[5,6]
[5,7]
Command procedures, documentation source, etc.
Documentation.
Compiler and assembler source.
Common (non-I/O) library source.
I/O library source and command files.
Native RSTS/E interface library.
Native RSX-11M interface library.
[6,1] "Software tools."
[6,2] Miscellaneous programs -- games and stuff.
may
[6,3]
[6,4]
[6,5]
[6,6]
[6,7]
Cross-assemblers for several micro-computers.
Lexical analyser generator.
Pieces of a standard library in C
Useful subroutines in C.
Vax/VMS interface library.
The two-tape distribution contains accounts [5,*] on one
(full)
tape and accounts [6,*] on the second (2/3 full) tape.
Each account contains a file
named
contents
For
README.nnn
describing
the
of
the
account.
in
account [5,1] is named README.501.
example,
the
README file
C Compiler and Library
Page
A-3
Getting on the Air with Decus C
A.3
___________
Command File Conventions
_______ ____
Command files used to build the C compiler and run-time
library
follow the following standard:
V?????
VAX/VMS indirect command file
X?????
RSX-11M file for the RSTS/E RSX emulator
R?????
RT-11
M?????
RSX-11M indirect command file
T?????
RT-11
indirect command file
.CMD
RSTS/E
indirect
file for the RSTS/E RT-11 emulator
command
files,
RSX-11M
indirect
command
files,
and
indirect
command
files
for
MAC.TSK and MACRO.SAV.
.COM
RT-11 or VMS indirect command files
.TKB
Task-builder indirect command files
.ODL
Task-builder overlay descriptor commands
.EIS
[RT11.EIS only] hardware EIS configuration
Command files used
to
build
tools
and
C-language
libraries
follow the following convention:
VN????
Use the native Vax-11C compiler only.
VX????
Use Decus-C (RSX compatibilitye) on Vax/VMS.
VB????
Use
either,
selecting
the
command
invocation.
RX????
RSTS/E RSX-11M emulation mode.
RT????
RSTS/E RT-11 emulation mode.
M????
RSX-11M native.
compiler
at
T????
RT-11 native.
C Compiler and Library
Page
A-4
Getting on the Air with Decus C
A.4 Distribution Contents in Detail
________ __ ______
____________
[5,1] [.command] Command Files and Documentation
This account contains documentation source files
(.rno),
kit building command files, and a few things that
didn't
fit
anywhere
else.
This
includes
a
number
of
special-purpose
command
files
used
to
develop the
C
language
system
(such
as
FORK.COM,
BATCH.COM,
and
TOOL.COM)
which may serve as models for your own
needs.
It also contains the source for CRUN.BAS, used on
RSTS/E
systems
to
pass arguments to C programs and source
for
CCN, used to compile and assembler C programs on
native
RSX-11M.
A full build of the Decus C system may
be
effected
by
executing
RBUILD.CMD on RSTS/E (requires privileges)
or
VBUILD.COM on VAX/VMS.
Either
command
requires
about
two
hours
to
complete.
At least 2000 free blocks
of
disk space is necessary on the
default
(public)
disk.
Note
that
the
build
will abort if the RSX LBR or
TKB
programs cannot obtain sufficient contiguous disk
space.
The RGTDOC.CMD or VGTDOC.COM command files build
new
documentation
kit.
To build the documentation,
proceed
as follows:
1.
Build the compiler and libraries.
a
2.
Build the tools.
4.
Use GETRNO to create library
runoff
files
--
see
VGTDOC.COM or RGTDOC.CMD.
5.
Use RNO.TSK to build
documentation
on
RSX-11M
or
RSTS/E,
or
use
RUNOFF to built the library on
VMS
V2.0.
6.
If on RSTS/E or VMS, execute FIXDOC to
repair
.DOC
files
after
RNO.TSK
or
RUNOFF.EXE
has
finished
messing
them
up.
(See
the
gory
details
in
RGTDOC.CMD and VGTDOC.CMD.)
The GETCMD.C and BUILD.C programs were used to
build
command
files
for
compilation
and
network
file
transfer.
See the
tool
documentation
or
examine
some
command
files for more information.
Run-
time
library
command
files
were
built
using
the
RLBCMD.CMD
(RSTS/E)
or
VLBCMD.COM
(VMS)
command
files.
Tool command
files
were
built
the
BTOOLS.COM or RTOOLS.CMD command files.
[5,2]
RSTS/E only
using
C Compiler and Library
Page
A-5
Getting on the Air with Decus C
On some distributions (but not
the
Decus
submission),
this
account contains the running system for RSTS/E
and
save images for RT-11.
It is never needed on VMS.
Any
file
residing
in
this account has been generated
from
source stored in other accounts.
The VMS
kit
read/write
account
[5,2]
command
procedures
reference
only
to
copy documentation to and
from
magtape.
Note that CC.DOC, AS.DOC, CBUGS.DOC,
CLIB.DOC,
and
WIZARD.DOC
are in this account on all
distribution
kits.
This account is the only one
that
may
contain
binary
files.
Consequently,
the
RSX-11M
interface
library,
CX.OLB, is stored here.
It is
needed
only
on
native
RSX-11M
systems.
RSX-11M
users should be warned
that
CX.OLB was generated on a
VAX/VMS
system.
CX.OLB
is
built from a command file in [5,7].
Note that some subroutines will not assemble
on
RSTS/E
or
early
versions
of RSX-11M as the associated
macros
are not present in the system macro library.
[5,3] [.comp]
Compiler source
This account contains the source and build files for
the
compiler
(CC????.MAC),
assembler (AS????.MAC), and
the
compiler support library (L?????.MAC).
The support library is a stripped-down variant of a
very
early
version
of
the
standard
library,
which
is
conditionally compiled
for
RSX
or
RT-11
flavor
I/O
support.
It is not particularily efficient.
To build the compiler, edit RSX.MAC and RT11.MAC to
suit
your
particular hardware needs and execute the CC
build
command file:
@
ATPK
ATPK
@
@
VMAKCC.COM
XMAKCC.CMD
RMAKCC.CMD
MMAKCC.CMD
TMAKCC.COM
On
On
On
On
On
VMS
RSTS/E RSX mode
RSTS/E RT-11 mode
RSX native mode
RT-11 native mode
Then, build the assembler:
@
ATPK
ATPK
@
@
[5,4] [.otscom]
VMAKAS.COM
XMAKAS.CMD
RMAKAS.CMD
MMAKAS.CMD
TMAKAS.COM
Common Library
On
On
On
On
On
VMS
RSTS/E RSX mode
RSTS/E RT-11 mode
RSX native mode
RT-11 native mode
C Compiler and Library
Page
A-6
Getting on the Air with Decus C
This account
contains
the
"common"
run-time
library
source.
These
files
have
no I/O or operating-
system
dependencies.
(Note
that
a
few
reference
library
routines
to
print error messages.) Several modules
are
called by direct code generation
sequences
(e.g.,
the
EIS
support
routines).
Command
files
are stored
in
[-.OTSIO] ([5,5]).
[5,5] [.otsio]
I/O library
This account contains
I/O
dependent
run-time
library
source
files.
These
files
conditionally
compile
to
generate code for
either
system
You
RSX-11M
or
RT-11
operating
support.
should
be
warned
that
several
modules
contain
essentially
two
totally
distinct
subroutines.
Internally-called
routines
are
in
IO????.MAC.
INIT.MAC
contains
the
run-time
startup
program,
which
is
very
system
dependent.
also
contains some
code
which
is
specific
to
particular
operating system releases.
To build
a
library,
invoke
the
appropriate
command
procedure, using the format described above:
@
ATPK
ATPK
@
@
[5,6] [.rstslb]
VMAKLB.COM
XMAKLB.CMD
RMAKLB.CMD
MMAKLB.CMD
TMAKLB.COM
On
On
On
On
On
VMS
RSTS/E RSX mode
RSTS/E RT-11 mode
RSX native mode
RT-11 native mode
RSTS/E Interface Library
It
RSTS/E operating-system dependent
subroutines
allowing
access to RSTS/E executive services by C programs.
Many
are written in C.
They are not as well
documented
(or
written) as they might be.
[5,7] [.rsxlib]
RSX-11/M Interface Library
An interface library to the RSX-11M
executive.
It
is
not
known
what
parts
of
this library work on VMS
or
RSTS/E emulation modes.
This library will not
assemble
on
RSTS/E
V7.0 as the distributed system macro
library
lacks certain executive service macros.
[6,1] [.tools]
C
Software Tools
tools.
See
[.tools]readme.601
for
details.
The
following command files are provided:
V?TOOL.COM
Vax/VMS:
VNTOOL
uses
the
native
compiler
VAX-11C;
VXTOOL uses Decus
C;
and VBTOOL allows selection of either.
C Compiler and Library
Page
A-7
Getting on the Air with Decus C
R?TOOL.CMD
RSTS/E:
RXTOOL uses
RSX
emulation
mode,
while
RTTOOL uses RT11
emulation
mode.
TTOOL.COM
Native RT11.
MTOOL.CMD
Native RSX-11M.
The command files were built by
executing
BUILD.C
for
all tools.
It is highly recommended that, when you
need
to recompile a tool, you build the
command
file
using
BUILD.
For example, to build a command file for GREP
on
your current operating system, you need only execute:
build grep.c >grep.cmd
On VMS, the TOOL.COM command file may be used to build
a
tool
by running BUILD to create a command file which
is
then executed.
Note that the RSTS and VMS
commands
refer
to
logical
devices
(BIN:)
that, on VMS, are defined externally
to
the build process.
[6,2] [.misc]
Toys,
Toys and Other Stuff
half
baked
ideas,
and
other
stuff.
See
[.misc]readme.602
for
details.
Command
files
are
provided to build COOKIE on RSTS/E
and
VMS.
of
these files haven't been touched in years.
[6,3] [.cross]
Cross Assemblers
A variety of cross assemblers.
[.cross]readme.603
See
Some
for
details.
This account also contains a copy of
the
8080 C compiler printed in
Dr.
Dobbs
Journal,
March
1980.
Again, little recent debugging.
Files in this account are stored in archives.
To
build
a cross assembler, you should first extract the
relevant
files.
These have not been extensively tested.
[6,4] [.lex]
Lexical Analyser
A lexical-analyser generator written by Charles
Forsyth.
The
standard
build
command files will create
compiler
command files.
[6,5] [.libc]
Library in C
The first pieces of a "standard" library, implemented
in
C.
Currently,
the
str???
and is???
routines, a
few
floating-point routines, and some pieces of
are
present.
eventually
It is hoped that this account will
printf
C Compiler and Library
Page
A-8
Getting on the Air with Decus C
replace [.OTSCOM] and most of [.OTSIO] in the future.
Note that, in
the
first
Decus
C
distribution,
this
account
contained
a
machine-independent
microcomputer
cross assembler.
Those routines are now stored
in
the
"cross assembler" directory in an archive).
[6,6] [.useful]
Useful subroutines
A library of useful subroutines written in C.
[6,7] [.vaxlib]
VAX/VMS Interface Routines
Interface routines for use with Decus C
programs
which
are
being
transported
to
the
native
VMS
C
program
product.
This library predated the released version
of
Vax-11
C
and
may
contain
modules
that
have
been
superseded by the distributed Vax-11 C run-time
library.
Decus C tools must be linked together with this
library
in
order
to access routines, such as fwild(), that
are
not present in the Vax-11 C
library.
Note
especially
that
the fact that a routine exists in this library
(or
that a tool compiles under Vax-11 C) does not imply
that
the
tool
or
routine
has been tested.
If you
blindly
install this library, you are asking for trouble.
A.5
Installation Overview
____________ ________
NOTE
WARNING If you already have Decus C, please backup all
files
and
zero all accounts before copying this
distribution to disk. Several files that were on the
previous Decus distribution are not on this tape.
If you are installing C for the first time, you should print
all
"README.???"
files,
the
compiler
and
library/support
documentation files, NEWS.DOC, CC.DOC and WIZARD.DOC (in
[5,2]),
RSX.MAC, RT11.MAC, RT11.EIS, and the command files for
your
operating system.
NOTE
WARNING The RT11.MAC and RSX.MAC command files, as
distributed,
assume
the
existance
of
the
SXT
instruction. This instruction is not present on some
early models of the PDP-11. If C programs or libraries
C Compiler and Library
Page
A-9
Getting on the Air with Decus C
are to run on a PDP-11/20, PDP-11/04, PDP-11/05, or on a
PDP-11/40 without EIS, the macro header files must be
edited to define C$$SXT = 0 before building the compiler
or library.
Beware, non-SXT compilation hasn't been
tested for quite a while.
If your system does not have EIS, you can make "no EIS"
standard by editing RSX.MAC and RT11.MAC to set symbol
C$$EIS to zero.
The native RSX build command file inquires
and EIS defaults must be set.
A.5.1
Installation on RSTS/E
whether
SXT
____________ __
______
This installation procedure presupposes RSTS/E
V7.1
or
later.
If
you
are
running on a V6 release, you will have to edit
the
command files, converting them to batch control files.
You
may
also
need
to
edit
SUPORT.MAC,
INIT.MAC,
FWILD.MAC,
and
SBREAK.MAC in the run-time library as these routines
presuppose
executive services that were added with the V7.0 release.
Decus
C does not
require
"large
files"
or
other
optional
RSTS/E
features.
While the C compiler and run-time
libraries
generally
do
not
require
privileges,
you
will need privileges to perform a
few
installation-support functions:
Creating accounts.
Copying files to a specific account.
Installing CCL's and system-wide logicals.
Create the various
accounts,
[5,1]
through
[5,8]
and
[6,1]
through
[6,7].
The accounts may be created on a private
disk.
Then, copy the distribution tape to these accounts:
PIP disk:[*,*]<40>=tape:[*,*]
File CX.OLB may be in some distributions.
It is not needed
for
RSTS/E systems and should be deleted.
The system manager should add the
following
commands
to
your
system startup command file (before executing RBUILD):
RUN
ADD
CCL
CCL
$UTILTY
LOGICAL disk:[account] C
XCC-=C:CC.TSK;0
XAS-=C:AS.TSK;0
! define C logical
! RSX
CC compiler
! RSX
AS assembler
C Compiler and Library
Page
A-10
Getting on the Air with Decus C
CCL CC-=C:CC.SAV;8220
CCL AS-=C:CC.SAV;8220
CCL CRUN-=C:CRUN.*;30000
! RT-11 CC compiler
! RT-11 AS assembler
! Turn CCL to chain
call
EXIT
where "disk:[account]" is specified to suit your
installation's
needs. It need not be [1,2].
NOTE
C programs will not compile if you haven't added C: as a
logical device as they use this logical to locate
system-wide header files.
The CCL's install CC.SAV and
AS.SAV
to
run
in
a
28
K-
word
partition.
The parameter value is constructed as "8192+K"
where
K is the number of K-words the software is to run in.
Note
that
these programs do not dynamically expand memory on RSTS/E.
The
"tools"
build
command
files
also
make
reference
to
system-wide logical PUB:.
This may be assigned to [1,2] or
some
other "public library" account.
If you
do
not
wish
to
edit
these files, you should add PUB:
as a "system-wide logical."
Make sure protection codes are set properly in the files in
C:.
You
may also want to add CC.HLP and [6,1]CTOOLS.HLP to the
help
facility.
Their format is compatible with the VMS help
facility
and must be edited for use on RSTS/E.
Installing the entire system using the
[5,1]RBUILD.CMD
control
file requires about two hours on a lightly-loaded 11/70 system.
Note that RSTS/E system
installation
requires
system
manager
privileges
in
order
to
install
CCL
commands,
system
wide
logicals, and to create files in other accounts.
No
C
program
requires <232> privileges for its operation.
If your system manager installs
the
RSTS/E
feature
patch
to
permit
cross-account
file
creates within the same project
and
gives you a [5,0] and [6,0] account, it
is
possible
to
build
Decus
C
without privileges.
be
run directly, however.
The RBUILD command file cannot
C Compiler and Library
Page
A-11
Getting on the Air with Decus C
A.5.2
Installation on VMS
____________ __ ___
This installation procedure presupposes VMS V2.0 or
later.
If
you are running on an earlier release, you will have to edit
the
command files, replacing account assignments as needed.
If you are running on VMS V3.0 or later,
you
can
restore
the
system from magtape (VAX BACKUP format).
If your Decus C distribution
was
in
various
account
FLX
format,
create
the
accounts
and
copy
[5,1] from the magtape
to
account [.command]:
$ create/dir disk:[decusc]
$
set
default
disk:[decusc]
The VMS V2.0 file system supports relative directory
access
as
follows:
[-.subdirectory]
means "move to the parent of the current directory and then
down
to
the
indicated
subdirectory." This is analogous to the
Unix
syntax
../subdirectory
This is not supported
in
earlier
releases
of
VMS.
If
not
running
under
VMS
V2.0
or
later, you will have to edit
.COM
files
accordingly.
In
any
case,
create
the
following
sub-directories
([P,Pn]
shows
the
correspondance between
the
tape directory and disk subdirectory):
[5,1]
[5,2]
[.command] Command files and documentation
[]
.DOC files
[5,3]
[5,4]
[5,5]
[5,6]
[5,7]
[.comp]
[.otscom]
[.otsio]
[.rstslb]
[.rsxlib]
[6,1]
[6,2]
[6,3]
[6,4]
[6,5]
[6,6]
[6,7]
[.tools]
[.misc]
[.cross]
[.lex]
[.cfloat]
[.useful]
[.vaxlib]
Compiler source
Common (no i/o) run-time library
I/O run-time library
RSTS/E library
RSX-11/M library
C source for useful programs
Various junk
Cross-assemblers
Lexical analyser
Floating point library
Useful subroutines
Vax native library
Set [.command] as your current default and
[5,1]VRKIT.COM
from the magtape to this account:
$ set default [.command]
$ mount/foreign mta0:
copy
C Compiler and Library
Page
A-12
Getting on the Air with Decus C
$ mcr flx sy:=mt0:[5,1]vrkit.com/do
Now, edit file VRKIT.COM to suit your needs and execute it.
(If
your
distribution
is
on
1200
foot magtapes, you should
copy
VRKIT1.COM, execute it, then mount the second magtape
on
and
The
MTA0:
execute
(after
eventual
editing)
VRKIT2.COM.
VRKIT
command procedure copies all other files to the
disk.
Because
of
the
many
rewinds,
this
command requires several hours
to
complete.
An alternate distribution for VMS
systems
only
uses
the
MCR
RMSBCK utility to write each subdirectory in a "container"
file.
The distribution tape is labelled "C" and contains the
following
files:
README.NOW
KIT.DOC
BCK.COM
RST.COM
FILEnn.BCK
A short file explaining the process
This document
The backup command file used
A model restore command file
Container files
To generate a C system from the backup tape, you must first
copy
RST.COM
to
disk,
edit
it
to
set correct disk and
directory
designations, then execute it as an indirect command file.
After reading the kit, install the system using
the
VBUILD.COM
command
procedure.
One simple way to do this is by typing
the
following sequence:
$ set default [.command]
$ @batch vbuild
! or submit vbuild
This builds
login
a
temporary
batch
control
file
in
your
account,
submits
it
to
batch,
and
sends
you mail when
the
process completes.
Batch.com
requires
some
cooperation
from
your login.com file.
The compiler, assembler, and run-time library are written to
the
parent
of
[.command]
(generally
[decusc]).
The
tools
are
written to logical BIN:
which should be defined before
starting
the
build process.
(Edit vbuild.com if BIN:
is not defined
in
your login.com file.)
[.command]CCHLP.COM is a command file that
adds
DECUSC.HLP
to
the system (VMS V2.0) help library.
It requires write-access
to
the help library.
It may not be compatible with later help
file
conventions, nor has it been tested on later releases of VMS.
Installation of VBUILD on an
VMS
V3.0 takes about 90 minutes.
unloaded
Vax-11/782
running
C Compiler and Library
Page
A-13
Getting on the Air with Decus C
A.5.3
Installation on RSX-11M
____________ __
_______
There are command files of the format M?????.CMD.
They
should
require no editing for RSX-11M V3.2.
Execute them using the
"@"
system command, answering
the
questions
as
needed.
Several
routines
in
the RSX interface library are specific to the
V3.2
release and will
not
assemble
on
previous
releases
(or
on
RSX-11M emulated on RSTS/E).
A.5.4
Installation on RT-11
____________ __
_____
An easy way to build an RT-11 system is to first built a
RSTS/E
system.
Then, use ATPK to execute RTKIT.CMD (after editing)
to
copy files to an RT-11 format disk.
To run the compiler,
define
logical
device
C:
to
refer
to
the
disk
containing
the
"#include <>" files and libraries and off you go.
Command procedures of the
format
T?????.COM
are
present
for
"native" RT-11.
They are not optimized to minimize disk
storage
usage.
Decus C has been built on 2 RK05 RT11 systems, using
one
RK05 for system and one for source files.
Except for "RT11.MAC",
"RT11.EIS",
and
"RSX.MAC"
(which
are
everywhere
identical),
there
are
no
known
conflicts
among
compiler and library file names.
However, given the size of
the
C
distribution,
it
would be prudent to use separate disks
for
the various components of the distribution.
The C
system
runs
on
diskette-based
systems,
such
as
the
PDT-150.
(and
even
on
a
VT103 with two TU58's!) No
command
files are present to
build
the
system
on
diskette
copy
the
necessary files to diskette
systems.
Instead,
you
should
as
follows:
o
Build
an
RT-11
system
containing
file
transfer
utilities, editors, LINK.SAV, and LIBR.SAV.
o
Copy CC.SAV, AS.SAV, and STDIO.H
to
this
disk
(there
will
be
only
a
few free blocks left).
This
diskette
will be defined as the C:
o
Initialize a
second
logical device.
diskette
and
copy
CLIB.OBJ
and
SUPORT.OBJ to it.
Your C programs should be created on
the
second
disk.
There
will
be
slightly
more
than
300
blocks
free after
creating
CLIB.OBJ and SUPORT.OBJ.
Note that, if you
omit
some
of
the
file
transfer
utilities, CLIB.OBJ and SUPORT.OBJ may be
stored
on the system disk, freeing
the
second
diskette
for
your
C
programs.
You should attempt to keep C program files
using
quite
short,
C Compiler and Library
Page
A-14
Getting on the Air with Decus C
the linker/librarian to build larger entities.
For example,
the
MAZE.C program (in [6,2]) needs over
200
blocks
of
temporary
disk
storage
for
compilation.
This is unsatisfactory in
many
situations.
The C language system has not been tested on HT-11.
Several
of
the
library routines use RT-11 Version 3 monitor calls that
are
not supported on HT-11.
However, it should not be too
difficult
to "fix" the library as needed.
While all tools have been compiled using Vax-11 C,
only
a
few
have been tested in "native C."
Note also that there are a few incompatiblities between Decus
C
and
"standard"
C,
and
several
incompatibilities between
the
Decus run-time library and Unix-style standard libraries.
A.5.5
Supporting Decus C
Decus C is distributed in source format.
__________ _____ _
All files are
in
the
public-domain.
WIZARD.DOC contains information on compiler
data
formats and library internal information.
This software is made available without any support
whatsoever.
To support the Decus C language, run-time library, or
C
programs, you will need to understand and modify Macro and
C
source code.
The authors would appreciate your
communicating
bug reports (with fixes!)
and
suggestions.
The
Decus
"Structured Languages Special Interest Group" is the
primary
focus for communication among users of Decus C.
APPENDIX B
LIBRARY INDEX
The following is a keyword in
context
index
to
the
standard
library.
The entry in the left-hand column is the title of
the
routine in the main library documentation.
toascii
isascii
abort
abs
fabs
qset
$$fadd
profile
rtemt
$$cl16
$$flun
malloc
calloc
alloc
$$abuf
$$falo
sbrk
isalloc
Convert to 7-bit Ascii
Test for 7-bit Ascii
trap
Abort program with a BPT
Absolute value
Floating absolute value
queue
Add entries to the RT11
Floating-point add and subtract
Print profile data after exit
Execute a RT11 EMT after loading r0
Close all I/O channels
Allocate a logical unit
Allocate and free memory
memory
Allocate and initialize
Allocate memory
buffers
Allocate memory for i/o
subroutines
Allocate memory for i/o
operating system
Allocate memory from
a pointer points to allocated memory Check
if
$$mchk
isalpha
islower
isupper
isalnum
strcat
Concatenate
strncat
Concatenate
Verify memory
Test for
Test for lower-case
Test for upper-case
Test for
a string onto
allocation pointers
alphabetic argument
alphabetic argument
alphabetic argument
alphanumeric argument
another
a string onto another, with
strncpy
$$ltoa
Copy one string to another, with count
long to Ascii (any radix)
Convert
$$fopt
fopen/fwild options argument
Scan
isalpha
isalnum
iscntrl
Test for alphabetic argument
Test for alphanumeric argument
for control character argument
isdigit
isgraph
islower
Test for digit argument
Test for graphic argument
lower-case alphabetic argument
isprint
Test for printable argument
Test
for
Test
C Compiler and Library
Page B-2
Library Index
ispunct
isupper
Test for punctuation argument
upper-case alphabetic argument
Test
for
isspace
$$fcsi
$$dtoa
Test for whitespace argument
Parse file name argument for fopen/fwild
floating point to ASCII
Convert
ddtoa
floating point to ASCII -- dummy
Convert
atofd
$$ctim
-- dummy
Convert ASCII to floating point
$$rtim buffer to Ascii
Convert
$$c5ta
r50toa
fgetname
itoa
itoax
Convert Radix-50 to
Convert Radix-50 to
Convert file name to
Convert integer to
to hexadecimal
Ascii
Ascii
Ascii
Ascii
Ascii
Convert
integer
itoa8
integer to octal Ascii
Convert
toascii
isascii
$$ltoa
ascr50
atod
atof
ctime
ctime
Convert to 7-bit
Test for 7-bit
Convert long to
Convert
Convert
Convert
Convert time value to
time buffer to
Ascii
Ascii
Ascii
Ascii
Ascii
Ascii
ascii
ascii
(any radix)
to Radix-50
to floating point
to floating point
asctime
Convert
ctime
peek
ftime
ungetc
$$clfu
getw
putw
fget
fput
msize
zero
fill
abort
localtime
swabb
$$ctim
$$utim
ctime
buffer to ascii
asctime Convert time
Peek at a location in RSTS/E
Compute time of day (augmented)
Push back onto an input file
Flush last record before closing file
file
Input a binary integer from a
Output a binary integer to a file
Input a binary record
Output a binary record
Get size of a memory block
Clear a block of memory
character
Fill a block of memory with a
Abort program with a BPT trap
Build time of day buffer
Swap bytes in a buffer
Convert $$rtim buffer to Ascii
Convert $$rtim buffer to Unix time
asctime Convert time buffer to ascii
$$abuf
memory for i/o buffers
Allocate
$$flsh
fflush
localtime
swabi
copy
Flush output buffers
Flush output buffers
Build time of day buffer
Byte swap an integer
a given number of bytes
Copy
swabb
call
Swap bytes in a buffer
subroutine from C
Call
callc
subroutine from C
(Fortran)
Call
(Fortran)
$$main
$$main
csv$
$$init
error
variables
C
C
environment
C
C
Error exit from C
library global
main program
program execution
program initialization
programs
C Compiler and Library
Page B-3
Library Index
exit
csv$
call
callc
$$qiow
wrapup
caller
Normal exit from
restore
subroutine from C
subroutine from C
service
Dummy routine
name of profiled
C programs
C register save and
Call (Fortran)
Call (Fortran)
Call RSX executive
called on exit
caller
calltr
brk
$$cl16
ctype
fill
Trace path to the
pointer
Close all I/O
type table
of memory with a
caller
Change top of memory
channels
Character classification
character
Fill a
Return
block
iscntrl
getchar
index
Test for control character argument
Get one character from a file
first instance of a character in a stFind
strchr
first instance of a character in a stFind
inchr
rindex
Find the index of a character in a string
last instance of a character in a stFind
the
the
the
strrchr
last instance of a character in a stFind
the
putc
$$putc
$$getc
isalloc
ctype
zero
clearerr
fclear
$$main
$$cl16
fclose
$$clfu
Output one character to a file
Output one character to a file
Get characters (internal)
points to allocated memoryck if a pointer
table
Character classification type
Clear a block of memory
flags
Clear open file's error
flags
Clear open file's error
$$tick -- Clock interrupt rate
Close all I/O channels
Close an open file
last record before closing file
(internal)
Flush
exit
exit
iov
$$gcmd
msg
$$exst -- Exit status
Exit with status
I/O error
Parse
a message on the
code
code
codes
command line
command terminal
Print
strcmp
strncmp
$$ctim
strlen
count
string
Compare
Compare
Compute
Compute
strings
strings, with
day of week
length of a
time
tod
ftime
strcat
strncat
concat
envsave
Compute time of day
Compute time of day
(augmented)
Compute time of day
onto another
Concatenate a string
onto another, with countoncatenate a string
Concatenate strings
and restore function context
iscntrl
gettty
setcc
fprintf
sprintf
$$tens
$$rtim
argument
Save
Test for
Get
mode only)
Trap
Formatted
Formatted
floating point
Date and time
control character
control terminal name
Control/C (RSTS/E RT11
Conversion
Conversion
Conversion table for
conversion
C Compiler and Library
Page B-4
Library Index
$$scan
fscanf
scanf
sscanf
$$ctim
$$utim
atofd
ascr50
atod
atof
$$c5ta
r50toa
fgetname
$$dtoa
ddtoa
itoa
itoax
itoa8
$$ltoa
toupper
atoi
atol
ctime
ctime
toascii
tolower
copy
strcpy
strncpy
cpystr
strncmp
strncat
Formatted
Formatted
Formatted
Formatted
input
input
input
input
conversion
conversion
conversion
conversion
Ascii
Convert $$rtim buffer to
Unix time
Convert $$rtim buffer to
floating point -- dummyConvert ASCII to
Radix-50
Convert Ascii to
floating point
Convert Ascii to
floating point
Convert Ascii to
Ascii
Convert Radix-50 to
Ascii
Convert Radix-50 to
Ascii
Convert file name to
to ASCII
Convert floating point
to ASCII -- dummy
Convert floating point
Convert integer to Ascii
hexadecimal Ascii
Convert integer to
Ascii
Convert integer to octal
(any radix)
Convert long to Ascii
upper-case
Convert lower-case to
integer
Convert string to
Convert string to long
ascii
asctime Convert time buffer to
ascii
Convert time value to
Convert to 7-bit Ascii
lower-case
Convert upper-case to
bytes
Copy a given number of
Copy a string
another, with count
Copy one string to
String copy
Compare strings, with count
onto another, with countConcatenate a
string
strncpy
to another, with count
Copy one
string
strneq
string equality, with count
Test
$$main
profile
$$rtim
time
tod
ftime
localtime
$$ctim
$$main
$$narg
fspool
$$scca -- RT-11 Ctrl/C flag
Print profile data after exit
Date and time conversion
Compute time of day
Compute time of day
Compute time of day (augmented)
Build time of day buffer
Compute day of week
$$uic -- RSX-11M default UIC
Define $$narg default for RT11 startup
Spool file to default print queue
$$narg
iov
sleep
delete
fmkdl
kbinr
kbin
for RT11 startup
Define $$narg default
I/O vector definition
of seconds
Delay job a given number
Delete a named file
Mark file for deletion
read without waiting
Delimiter-free terminal
the terminal without delimiters
Read
from
isxdigit
isdigit
Test for hexadecimal digit
Test for digit argument
C Compiler and Library
Page B-5
Library Index
div$li
$$div2
wrapup
atofd
Long division and modulus
Unsigned division and modulus
exit
Dummy routine called on
to floating point -- dummy
Convert
ASCII
ddtoa
point to ASCII -- dummy
Convert
floating
memdmp
eis$i
rstsys
rtemt
$$main
eis$i
feof
$$main
qset
profile
csv$
streq
strneq
error
ferr
ferror
iov
clearerr
fclear
perror
iov
rstsys
rtemt
unwind
setjmp
csv$
$$qiow
exit
exit
wrapup
Execute a RSTS
Execute a RT11
$$vms -- Test if VMS
EIS
Test for
$$stnd -- Stack
queue
Add
$$prnl -- Profile
C program execution
Test strings for
Test string
programs
Test for file
Test for file
I/O
Clear open file's
Clear open file's
Print library
$$ferr -- File
loading r0
longjmp -C program
Call RSX
$$exst -routine called on
Dump memory or registers
EIS emulator
EMT
EMT after loading r0
emulation
emulator
end of file
end point
entries to the RT11
entry per line
environment
equality
equality, with count
Error exit from C
error
error
error codes
error flags
error flags
error message
error value
Execute a RSTS EMT
Execute a RT11 EMT after
Execute non-local goto
execute non-local goto
execution environment
executive service
Exit status code
Exit with status code
exit
Dummy
profile
profile data after exit
error
exit
exit
iov
iov
profile
Error exit
Normal exit
$$exst
$$ferr
$$ferr -- File
-- Profile output file
Print
$$pfil
fclose
Close an open file
from C programs
from C programs
-- Exit status code
-- File error value
error value
delete
$$clfu
Delete a named file
record before closing file
Flush
last
getchar
one character from a file
Get
getw
binary integer from a file
fopen
putw
Open or reopen a file
a binary integer to a file
a
Output
puts
putc
Output a string to a file
one character to a file
Output
ungetc
back onto an input file
Push
fgets
feof
Read a string from a file
Test for end of file
Input
C Compiler and Library
Page B-6
Library Index
frec
if record-oriented file
$$putc
one character to a file (internal)
Test
Output
ferr
ferror
fmkdl
rewind
ftty
isatty
$$fcsi
fgetname
$$fopa
fwild
fseek
ftell
fspool
clearerr
fclear
fill
maxmin
maxmin
maxmin
maxmin
index
strchr
inchr
rindex
strrchr
index
strchr
$$main
Test for file error
Test for file error
Mark file for deletion
Rewind a file for re-reading
Test if a file is a terminal
Test if a file is a terminal
fopen/fwild
Parse file name argument for
Convert file name to Ascii
Open or reopen a file on RT11
Wild-card file open
Reposition file pointer (seek)
subsequent seek
Get file position for
queue
Spool file to default print
Clear open file's error flags
Clear open file's error flags
with a character
Fill a block of memory
numbers
Find maximum of two
unsigned numbers
Find maximum of two
numbers
Find minimum of two
unsigned numbers
Find minimum of two
of a character in a stringd the first instance
of a character in a stringd the first instance
character in a string Find the index of a
of a character in a stringd the last instance
of a character in a stringd the last instance
character in aFind the first instance of a
character in aFind the first instance of a
-- RT-11 Ctrl/C flag
$$scca
clearerr
open file's error flags
fclear
open file's error flags
Clear
Clear
iov
fabs
$$tens
atod
atof
atofd
fps
$$dtoa
ddtoa
$$fadd
$$fmul
I/O system internal flags and vectors
Floating absolute value
Conversion table for floating point
Convert Ascii to floating point
Convert Ascii to floating point
Convert ASCII to floating point -- dummy
(FPS)
Set floating point status
Convert floating point to ASCII
-- dummy
Convert floating point to ASCII
subtract
Floating-point add and
multiply/divide
Floating-point
$$fsav
$$clfu
$$flsh
fflush
$$fcsi
routines
closing file
Floating-point support
Flush last record before
Flush output buffers
Flush output buffers
name argument for fopen/fwild
Parse
$$fopt
fprintf
sprintf
$$scan
fscanf
scanf
argument
file
conversion
conversion
conversion
Scan fopen/fwild options
Formatted Conversion
Formatted Conversion
Formatted input
Formatted input
Formatted input
C Compiler and Library
Page B-7
Library Index
sscanf
$$prnt
printf
call
callc
fps
conversion
Formatted input
Formatted output
Formatted output
Call (Fortran) subroutine from
Call (Fortran) subroutine from
point status (FPS)
Set
C
C
floating
malloc
envsave
envsave
irand
rand
$$get
$$getc
gettty
ftell
fileno
flun
getchar
msize
copy
sleep
$$main
unwind
setjmp
Allocate and
Save and restore
Multi-level
Random number
Random number
(internal)
name
subsequent seek
file
block
Copy a
Delay job a
C library
Execute non-local
-- execute non-local
free memory
function context
function return
generator
generator
Get a record (internal)
Get characters
Get control terminal
Get file position for
Get logical unit number
Get logical unit number
Get one character from a
Get size of a memory
given number of bytes
given number of seconds
global variables
goto
goto
longjmp
isgraph
traps
itoax
isxdigit
$$cl16
iov
screen
iov
iov
$$abuf
$$falo
$$main
Test for
Operating system trap
Convert integer to
Test for
Close all
Screen
flags and vectors
Allocate memory for
Allocate memory for
-- Operating system
graphic argument
handlers
hexadecimal Ascii
hexadecimal digit
I/O channels
I/O error codes
I/O primitives
I/O system internal
I/O vector definition
i/o buffers
i/o subroutines
id.
$$opsy
$$main
$$main
$$main
ftty
isatty
isalloc
frec
wdleng
inchr
$$pos -- Test if P/OS (Professional)
$$rsts -- Test if RSTS/E
$$vms -- Test if VMS emulation
Test if a file is a terminal
Test if a file is a terminal
allocated memory Check if a pointer points to
Test if record-oriented file
Machine independent sizeof(int)
a string
Find the index of a character in
$$init
calloc
getw
fget
fread
$$scan
fscanf
scanf
sscanf
C program initialization
Allocate and initialize memory
from a file
Input a binary integer
Input a binary record
Input a record
Formatted input conversion
Formatted input conversion
Formatted input conversion
Formatted input conversion
C Compiler and Library
Page B-8
Library Index
ungetc
index
strchr
rindex
strrchr
swabi
atoi
asl$li
asr$u
in
in
in
in
a
a
a
a
Push back onto an
strFind the first
strFind the first
striFind the last
striFind the last
Byte swap an
Convert string to
Shift long by
shift unsigned by
input file
instance of
instance of
instance of
instance of
integer
integer
integer
integer
a
a
a
a
character
character
character
character
right
getw
itoa
putw
itoax
itoa8
iov
$$get
$$getc
$$putc
Input a binary integer from a file
Convert integer to Ascii
Output a binary integer to a file
Ascii
Convert integer to hexadecimal
Convert integer to octal Ascii
vectors
I/O system internal flags and
Get a record (internal)
Get characters (internal)
character to a file (internal)
Output
$$main
ftty
isatty
sleep
rindex
strrchr
$$clfu
strlen
perror
$$main
profile
$$tick -- Clock
Test if a file
Test if a file
seconds
Delay
character in aFind the
character in aFind the
closing file
Flush
Compute
Print
C
-- Profile entry per
one
interrupt rate
is a terminal
is a terminal
job a given number of
last instance of a
last instance of a
last record before
length of a string
library error message
library global variables
line
$$prnl
$$gcmd
gets
$$link
rtemt
Parse command
Read a
Print memory
a RT11 EMT after
peek
$$put
$$flun
fileno
flun
div$li
atol
mul$l
asl$l
asl$li
mul$l
Peek at a
Write a
Allocate a
Get
Get
line
line from stdin
list
loading r0
Execute
modulus
Convert string to
Multiply long by
shift long by
Shift
Multiply
location in RSTS/E
logical record
logical unit
logical unit number
logical unit number
Long division and
long
long
long
long by integer
long by long
asl$l
$$ltoa
setjmp
shift long by long
radix)
Convert long to Ascii (any
-- save state for longjmp
setjmp
tolower
islower
toupper
wdleng
$$main
fmkdl
non-local goto
Convert upper-case to
argument
Test for
Convert
sizeof(int)
C
setjmp
longjmp -- execute
lower-case
lower-case alphabetic
lower-case to upper-case
Machine independent
main program
Mark file for deletion
C Compiler and Library
Page B-9
Library Index
maxmin
maxmin
alloc
malloc
calloc
Find
Find
Allocate
Allocate and free
and initialize
numbers
maximum of two numbers
maximum of two unsigned
memory
memory
memory
Allocate
isalloc
points to allocated memory Check if a
pointer
zero
realloc
$$mchk
msize
$$abuf
$$falo
sbrk
$$link
memdmp
brk
fill
perror
msg
maxmin
maxmin
setcc
Clear a block of
Reallocate
pointers
Verify
Get size of a
Allocate
subroutines
Allocate
system
Allocate
Print
Dump
Change top of
Fill a block of
Print library error
terminal
Print a
Find
numbers
Find
(RSTS/E RT11
memory
memory
memory allocation
memory block
memory for i/o buffers
memory for i/o
memory from operating
memory list
memory or registers
memory pointer
memory with a character
message
message on the command
minimum of two numbers
minimum of two unsigned
mode only) Trap
trace
div$li
$$div2
envsave
mul$l
$$fmul
$$main
Profile support
Long division and
Unsigned division and
return
gettty
$$fcsi
caller
fgetname
delete
$$narg
unwind
setjmp
exit
$$prmt
fileno
flun
irand
rand
copy
Get control terminal name
fopen/fwild Parse file name argument for
Return name of profiled caller
Convert file name to Ascii
Delete a named file
startup
Define $$narg default for RT11
Execute non-local goto
longjmp -- execute non-local goto
programs
Normal exit from C
Null prompt pointer
Get logical unit number
Get logical unit number
Random number generator
Random number generator
Copy a given number of bytes
Control/C
module (with trace)
modulus
modulus
Multi-level function
Multiply long by long
Floating-point multiply/divide
-- RSX-11M task name
$$task
sleep
maxmin
maxmin
Delay job a given number of seconds
Find maximum of two numbers
of two unsigned numbers
Find
maxmin
maxmin
Find minimum of two numbers
of two unsigned numbers
maximum
Find
minimum
itoa8
getchar
putc
$$putc
strncpy
Convert integer to
file
Get
Output
(internal)
Output
with count
Copy
octal Ascii
one character
one character
one character
one string to
from a
to a file
to a file
another,
C Compiler and Library
Page B-10
Library Index
setcc
(RSTS/E RT11 mode only)
Trap
Control/C
ungetc
strcat
strncat
fopen
$$fopa
fwild
fclose
clearerr
fclear
$$main
traps
sbrk
$$main
$$main
$$fopt
memdmp
fopen
$$fopa
putw
fput
fwrite
puts
putc
$$putc
$$prnt
printf
$$flsh
fflush
profile
$$main
$$gcmd
$$fcsi
calltr
peek
profile
Push back onto an input file
Concatenate a string onto another
Concatenate a string onto another, with count
Open or reopen a file
RT11
Open or reopen a file on
Wild-card file open
Close an open file
Clear open file's error flags
Clear open file's error flags
$$opsy -- Operating system id.
handlers
Operating system trap
Allocate memory from operating system
variables
Operating-system unique
id.
$$opsy -- Operating system
Scan fopen/fwild options argument
Dump memory or registers
Open or reopen a file
Open or reopen a file on RT11
to a file
Output a binary integer
Output a binary record
Output a record
file
Output a string to a
a file
Output one character to
a file (internal)
Output one character to
Formatted output
Formatted output
Flush output buffers
Flush output buffers
$$pfil -- Profile output file
$$pos -- Test if P/OS (Professional)
Parse command line
for fopen/fwild
Parse file name argument
Trace path to the caller
RSTS/E
Peek at a location in
-- Profile entry per line
profile
$$main
$$tens
file
$$pfil -- Profile output
$$stnd -- Stack end point
table for floating point
$$prnl
Conversion
atod
Ascii to floating point
atof
Ascii to floating point
atofd
ASCII to floating point -- dummy
Convert
Convert
Convert
fps
$$dtoa
ddtoa
brk
$$prmt
fseek
isalloc
$$mchk
Set floating
Convert floating
Convert floating
Change top of memory
Null prompt
Reposition file
allocated meCheck if a
memory allocation
point status (FPS)
point to ASCII
point to ASCII -- dummy
pointer
pointer
pointer (seek)
pointer points to
pointers
isalloc
$$main
ftell
screen
memoCheck if a pointer points to allocated
(Professional)
$$pos -- Test if P/OS
seek
Get file position for subsequent
Screen I/O primitives
Verify
C Compiler and Library
Page B-11
Library Index
msg
perror
$$link
profile
fspool
isprint
profile
$$main
command terminal
message
Print a message on the
Print library error
Print memory list
exit
Print profile data after
Spool file to default print queue
Test for printable argument
per line
$$prnl -- Profile entry
-- Test if P/OS (Professional)
profile
profile
trace
profile
caller
$$main
csv$
$$init
abort
error
exit
$$prmt
ispunct
ungetc
qset
$$prnl -- Profile entry per line
$$pfil -- Profile output file
(with trace)
Profile support module
Print profile data after exit
Return name of profiled caller
C main program
environment
C program execution
C program initialization
Abort program with a BPT trap
Error exit from C programs
Normal exit from C programs
Null prompt pointer
Test for punctuation argument
file
Push back onto an input
entries to the RT11 queue
$$pos
Add
fspool
file to default print queue
rtemt
EMT after loading r0
Spool
Execute a
RT11
$$svr1
$$ltoa
Save registers r1-r5 on the stack
long to Ascii (any radix)
ascr50
$$c5ta
r50toa
irand
rand
$$main
Convert Ascii to Radix-50
Convert Radix-50 to Ascii
Convert Radix-50 to Ascii
Random number generator
Random number generator
-- Clock interrupt rate
Convert
$$tick
rewind
gets
fgets
kbin
kbinr
Rewind a file for re-reading
Read a line from stdin
file
Read a string from a
without delimiters
Read from the terminal
terminal read withouDelimiter-
free
realloc
fread
fget
Reallocate memory
Input a record
Input a binary record
fwrite
fput
$$put
$$get
$$clfu
frec
csv$
memdmp
$$svr1
fopen
$$fopa
fseek
csv$
Output a
Output a binary
Write a logical
Get a
file
Flush last
Test if
restore
C
Dump memory or
stack
Save
Open or
Open or
(seek)
C register save and
record
record
record
record (internal)
record before closing
record-oriented file
register save and
registers
registers r1-r5 on the
reopen a file
reopen a file on RT11
Reposition file pointer
restore
C Compiler and Library
Page B-12
Library Index
envsave
caller
envsave
rewind
asr$u
wrapup
$$fsav
Save and restore function context
caller
Return name of profiled
Multi-level function return
re-reading
Rewind a file for
integer
right shift unsigned by
Dummy routine called on exit
support routines
Floating-
rstsys
$$main
$$main
peek
setcc
$$qiow
$$main
$$main
$$main
$$fopa
Execute a RSTS EMT
$$rsts -- Test if RSTS/E
$$rsts -- Test if RSTS/E
Peek at a location in RSTS/E
Trap Control/C (RSTS/E RT11 mode only)
Call RSX executive service
$$uic -- RSX-11M default UIC
$$task -- RSX-11M task name
$$scca -- RT-11 Ctrl/C flag
or reopen a file on RT11
point
Open
rtemt
setcc
r0
Execute a RT11 EMT after loading
Control/C (RSTS/E RT11 mode only)
Trap
qset
$$narg
Add entries to the RT11 queue
$$narg default for RT11 startup
Define
$$ctim
$$utim
envsave
$$svr1
csv$
setjmp
$$fopt
$$main
screen
sleep
Convert $$rtim buffer to Ascii
Convert $$rtim buffer to Unix time
function context
Save and restore
the stack
Save registers r1-r5 on
C register save and restore
setjmp -- save state for longjmp
argument
Scan fopen/fwild options
flag
$$scca -- RT-11 Ctrl/C
Screen I/O primitives
job a given number of seconds
Delay
ftell
for subsequent seek
Get file
position
fseek
file pointer (seek)
Reposition
$$qiow
fps
setjmp
asl$li
asl$l
asr$u
msize
wdleng
Call RSX executive service
status (FPS)
Set floating point
longjmp
setjmp -- save state for
Shift long by integer
shift long by long
integer
right shift unsigned by
Get size of a memory block
Machine independent sizeof(int)
fspool
$$main
$$svr1
print queue
Spool file to default
$$stnd -- Stack end point
r1-r5 on the stack
Save
registers
$$narg
default for RT11 startup
Define
$$narg
setjmp
fps
exit
exit
gets
$$main
cpystr
strlen
strcpy
setjmp -- save state for longjmp
Set floating point status (FPS)
$$exst -- Exit status code
Exit with status code
Read a line from stdin
$$stnd -- Stack end point
String copy
Compute length of a string
Copy a string
C Compiler and Library
Page B-13
Library Index
index
of a character in a stFind the first
strchr
of a character in a stFind the first
inchr
of a character in a string
rindex
of a character in a strFind the last
strrchr
of a character in a strFind the last
instance
instance
Find the
index
instance
instance
strneq
fgets
strcat
strncat
puts
strncpy
atoi
atol
strcmp
concat
streq
strncmp
call
callc
$$falo
count
Test
Read a
Concatenate a
with counConcatenate a
Output a
count
Copy one
Convert
Convert
Compare
Concatenate
Test
Compare
Call (Fortran)
Call (Fortran)
memory for i/o
string equality, with
string from a file
string onto another
string onto another,
string to a file
string to another, with
string to integer
string to long
strings
strings
strings for equality
strings, with count
subroutine from C
subroutine from C
subroutines
Allocate
ftell
$$fadd
Get file position for subsequent seek
add and subtract
Floating-
point
trace
$$fsav
swabb
swabi
sbrk
trace)
Profile support module (with
Floating-point support routines
Swap bytes in a buffer
Byte swap an integer
memory from operating system
$$main
iov
traps
ctype
$$opsy -- Operating system id.
and vectors
I/O system internal flags
Operating system trap handlers
classification type table
Allocate
Character
$$tens
$$main
$$main
msg
name
Conversion table for floating point
$$task -- RSX-11M task
$$task -- RSX-11M task name
on the command terminal Print a
message
ftty
isatty
gettty
Test if a file is a terminal
Test if a file is a terminal
Get control terminal name
kbinr
kbin
isascii
isalpha
isalnum
iscntrl
isdigit
feof
ferr
ferror
isgraph
isxdigit
islower
isprint
ispunct
isupper
waiting Delimiter-free terminal read without
delimiterRead from the terminal without
Test for 7-bit Ascii
argument
Test for alphabetic
argument
Test for alphanumeric
character argument
Test for control
Test for digit argument
Test for end of file
Test for file error
Test for file error
argument
Test for graphic
digit
Test for hexadecimal
alphabetic argument
Test for lower-case
argument
Test for printable
argument
Test for punctuation
alphabetic argument
Test for upper-case
C Compiler and Library
Page B-14
Library Index
isspace
$$main
$$main
$$main
ftty
isatty
frec
strneq
streq
$$main
$$utim
argument
Test
(Professional)$$pos -- Test
$$rsts -- Test
$$vms -- Test
terminal
Test
terminal
Test
file
Test
with count
Test
equality
Test
rate
$$tick
$$rtim buffer to Unix time
for whitespace
if P/OS
if RSTS/E
if VMS emulation
if a file is a
if a file is a
if record-oriented
string equality,
strings for
-- Clock interrupt
Convert
ctime
$$rtim
time
tod
ftime
localtime
ctime
brk
calltr
trace
asctime Convert
Date and
Compute
Compute
Compute
Build
Convert
Change
time buffer to ascii
time conversion
time of day
time of day
time of day (augmented)
time of day buffer
time value to ascii
top of memory pointer
Trace path to the caller
support module (with trace)
Profile
setcc
abort
RT11 mode only)
Trap Control/C (RSTS/E
program with a BPT trap
Abort
traps
maxmin
maxmin
maxmin
maxmin
ctype
Operating system
Find maximum of
Find minimum of
Find maximum of
Find minimum of
classification
trap handlers
two numbers
two numbers
two unsigned numbers
two unsigned numbers
type table
Character
$$main
-- RSX-11M default UIC
$$uic
$$main
$$main
$$flun
fileno
flun
$$utim
UIC
$$uic -- RSX-11M default
Operating-system unique variables
Allocate a logical unit
Get logical unit number
Get logical unit number
$$rtim buffer to Unix time
$$div2
asr$u
maxmin
maxmin
toupper
isupper
modulus
Convert
right shift
Find maximum of two
Find minimum of two
Convert lower-case to
argument
Test for
Unsigned division and
unsigned by integer
unsigned numbers
unsigned numbers
upper-case
upper-case alphabetic
tolower
iov
abs
fabs
ctime
$$main
$$main
Convert
$$ferr -- File error
Absolute
Floating absolute
Convert time
C library global
unique
upper-case to lower-case
value
value
value
value to ascii
variables
variablesOperating-
system
iov
iov
I/O vector definition
internal flags and vectors
I/O
system
$$mchk
$$main
$$main
pointers
Verify memory allocation
$$vms -- Test if VMS emulation
emulation
$$vms -- Test if VMS
C Compiler and Library
Page B-15
Library Index
kbinr
terminal read without waiting
Delimiter-
free
$$ctim
isspace
kbin
Compute day of week
Test for whitespace argument
from the terminal without delimiters
Read
kbinr
terminal read without waiDelimiter-
free
$$put
Write a logical record
* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project
advertisement
© 2021