DECUS C LANGUAGE SYSTEM Compiler & Library Software Support Manual

DECUS C LANGUAGE SYSTEM Compiler & Library Software Support Manual
DECUS C LANGUAGE SYSTEM
Compiler & Library
Software Support Manual
by
Martin Minow
Edited by
Robert B.
Denny
This document describes the RSX/POS/VMS/RSTS/RT11 DECUS C language system runtime support library. It also contains all internal functions and such compiler internal information as is
available.
DECUS Structured Languages SIG
Version of 28-July-1984
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 of Bell Telephone Laboratories. RSX,
RSTS/E, RT11 and VMS are trademarks of Digital Equipment
Corporation.
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 perform
operations, such as copying a string, that are more
efficiently performed by optimized assembly language
subroutines.
o
An implementation
library.
of
(most
of) the Unix Standard I/O
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. This is
the Software Support Manual.
This release is the first to support the RMS-11(V2) file system.
The runtime library may optionally be built to use RMS. If this
is done, the advantages are compatibility across DECnet between
RSX, POS and VMS systems, and transparent remote DECnet file
access.
RMS is the preferred system for use on MICRO-RSX and
P/OS.
CHAPTER 2
THE STANDARD LIBRARY
This manual describes the DECUS C "standard I/O" package. It
was developed with the idea of maintaining maximum compatibility
with the UNIX Version 7 environment and maximum portability
between Digital operating systems.
This release (28-July-1984) of the library can be built for use
on RSX-11 (and friends) and P/OS to use either FCS-11 or
RMS-11(V2) record I/O systems. FCS-11 is the traditional record
I/O package used on RSX and the RSTS/RSX emulator. In the last
several years, however, the RMS-11 system has undergone a major
overhaul, the result of which is a very complete, reasonably
fast record I/O package.
P/OS
(the
Professional 300 series operating system) and
MICRO-RSX are oriented toward RMS-11. Both systems are shipped
with the RMS resident shared library (called RMSRES) genned into
the system. You might as well use it if you can afford the loss
of 8K words (2 APR's) of virtual address space. It is possible
to use RMS without RMSRES but your task image will be larger
than it would if you used FCS.
NOTE
The RMSRES shared library is "vectored". What this
means is that the entry points are kept in a fixed
table at the base of the region, and their locations
are guaranteed not to change with successive releases
of RMS. So you can build tasks against RMSRES without
the worry that the task will fail if the library is
revised. One other bit of trivia ... RMSRES on P/OS,
MICRO-RSX, RSX-11M and M-PLUS and, yes, even RSTS/E
(V8 & later) have IDENTICAL vectoring.
The native RSX library build command file MMAKLB.COM gives you
the choice of building the FCS or RMS flavors of the library.
All C programs should be linked together with the run-time
support library.
On systems that support logical
device
[[
Page 2-2
C Compiler and Library]]
Software Support Manual
descriptors, this will generally be stored in the C: logical
device/account. On RSX-11M, the library will be found in
LB:[1,1].
On PRO/Toolkit (native P/OS) the library will be
found in LB:[1,5]. To link a C program, proceed as follows:
RSX (FCS flavor):
LINK/CHECK/OPT/EXE:task objects+LB:[1,x]C/LIB
RSX/POS (RMSRES flavor):
LINK/CHECK/OPT/EXE:task objects+LB:[1,x]C/LIB
Option? STACK=1024
Option? LIBR=RMSRES:RO
Option?
RT11 & TSX+
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 /CHECKPOINT as the
default. If the /CHECKPOINT option is not given, the task may
abort (no memory) when started. Stack extension is needed if
subroutines locally allocate large amounts of data or if RMSRES
is in use. The easiest way to handle this is to make a command
file for linking.
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. If the stack size
is not increased, the program may abort without any error
message.
The standard I/O interface header file is in C:STDIO.H, or
LB:[1,1]STDIO.H on native RSX-11 or LB:[ZZDECUSC] on
POS
PRO/Toolkit, and should be included in all C programs as
follows:
#include <stdio.h>
WARNING
If you are using the RMS flavor of the standard I/O
package, there is an alternate header file that
describes the modified "iov" for RMS. It is called
RMSTDIO.H. Programs which make use of the "secret"
fields in the iov must use RMSTDIO.H. Otherwise,
STDIO.H is fine.
[[
Page 2-3
C Compiler and Library]]
Software Support Manual
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
Interaction with host operating system
DECnet considerations (RMS only)
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
opened:
C
program
stdin
stdout
stderr
is
started, three files are predefined and
The 'standard' input file
The 'standard' output file
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.
are normally used as follows:
They
#include <stdio.h>
/* Define standard I/O */
FILE
*ioptr;
/* Pointer to file area */
...
if ((ioptr = fopen("filename", "mode")) == NULL)
error("Can't open file");
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)
[[
Page 2-4
C Compiler and Library]]
Software Support Manual
(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(). The file should be opened with
'n' mode.)
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. fmkdl(ioptr) may be called to close and delete an
open file.
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
register int
ccount;
lcount;
[[
Page 2-5
C Compiler and Library]]
Software Support Manual
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() and feof()
functions which allow testing for error and end of file
conditions, respectively.
The package assumes that all error
conditions are lethal and force end of file.
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
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 and in some cases two different record I/O
packages (FCS and RMS). The possiblities include:
Operating systems:
[[
Page 2-6
C Compiler and Library]]
Software Support Manual
o
Native RT11
o
Native RSX-11M, RSX-11M PLUS, IAS and MICRO-RSX
o
P/OS (Professional 350 operating system)
o
RT11
o
RSX-11M emulated on RSTS/E
o
RSX-11M emulated on VAX/VMS
emulated on RSTS/E
Record I/O systems (RSX, RSTS, P/OS)
o
Native FCS-11 (RSX and friends)
o
FCS-11 emulated on RSTS/E(RSX)
o
Native RMS-11 (RSX, P/OS, RSTS/E(RSX))
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. This has
resulted in several quirks:
o
On RT11, console terminal interaction uses the .ttyout
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 is defined as if
fopen() were called).
Also, 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()
function.
o
and
regdmp()
use
the
.print
monitor
On both systems, the first true files are stdin and
stdout. These are opened on logical units 0 and 1
[[
Page 2-7
C Compiler and Library]]
Software Support Manual
(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
File and Directory Names
____ ___ _________
_____
Unfortunately, each operating system has its own way of naming
files and directories. Programs written with portability in
mind should NOT make assumptions about the format or structure
of file names.
2.5.3
Wild-Card Files
The fwild() and fnext()
'wild-card' files.
_________ _____
routines
can
be
used
to
process
On RSX-11M and VMS/RSX emulation, the file name, extension,
and/or file version may be expressed as '*' to indicate
wild-card support.
Due to restrictions in the RSX-11 Files-11
structure (ODS1), the ' ', ';0' and ';-1' version numbers 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.
With FCS, wild-card devices, units, directory names, or UIC
codes are not supported. With RMS, wildcard directory names and
UIC's are allowed, except with remote (DECnet) files. Note that
VMS V4 may support RMS-11(V2) under the (optional) AME.
Note
that,
on
RSX11
emulated
on
VMS,
the
';-1' (earliest
[[
Page 2-8
C Compiler and Library]]
Software Support Manual
version) requires special processing by
noted in the description of fwild().
the
user
program,
as
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. Since wild-card
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 wild-card
uses a 1024 byte buffer, twice the normal size, which is shared
between data and directory operations.
2.5.4
____ ______
DECnet Remote File Access
______ ______
If you are using the RMS version of the standard I/O library,
your applications automatically have access to files on remote
nodes on DECnet.
As is the case on the VAX (RMS-32), the new
RMS-11 provides transparent DECnet (DAP) remote file access.
What this means to you is that you can develop distributed
applications in DECUS C if you use the RMS flavor of the
library.
This is true of both RSX & friends and RSTS/E. If
your network consists of a mixture of host types, such as VAXen,
RSTS and RSX systems, remote file access can give you some
surprises. Most of the quirks are listed in your system's
DECnet "Cross System Notes".
On RSX and P/OS, the DECnet remote file capability presents some
interesting capabilities. For example, you may give full remote
file specifications on the command line when redirecting stdin
and stdout:
$ FOO
TT2> <NODE1"USER PSWD"::USER_ROOT:[DIR.SUB]FILE.EXT
The above would connect program FOO's "stdin" stream to a file
on a remote VAX/VMS system named "NODE1".
Note that RMS-11
accepts a full VMS-style hidden device and tree directory
specification. The default device and directory (if none is
explicitly supplied) is that of "USER" on the VAX whose password
is "PASSWORD". Note that the VMS filespec redirection was not
given on the FOO command line.
Getting foreign filespecs
through DCL requires some quote-mark
done. For example:
hacking,
but
it
can
be
$ FOO <"NODE1""USER PSWD"""::"USER_ROOT:[DIR.SUB]FILE.EXT"
but this is easier:
$ FOO <NODE1/USER/PSWD::"USER_ROOT:[DIR.SUB]FILE.EXT"
[[
Page 2-9
C Compiler and Library]]
Software Support Manual
NOTE
Someone should try building the RMS library for RSTS/E
emulator. It is supposed to work.
2.5.5
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.
If you are using the RMS flavor of the I/O library and linking
with RMSRES, you may notice that your task image is smaller than
an FCS version would be. RMS allocates all buffers and control
blocks dynamically. This means that your program will expand at
run time more than an FCS version. Keep this in mind ... RMS
tasks require quite a bit more dynamic memory then FCS ones.
2.5.6
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
A symbol refered to by a C program which is not resolved
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 emulated on
RSTS/E V7.0, the following will fail:
int eof;
/* Global
*/
[[
C Compiler and Library]]
Page 2-10
Software Support Manual
main () {
}
CHAPTER 3
SUPPORT INFORMATION
The C system has been implemented on VMS V3.4, RSX-11M V4.1,
P/OS V1.7 and V2.0 with PRO/Toolkits V1.7 and V2.0, RSTS/E V8.0,
and RT11 V5. 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,
or HT11.
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 contains information on the internals of the
compiler, assembler, and run-time libraries.
It
is
not
complete; it is probably not accurate either.
3.1
The C Compiler
___ _ ________
The compiler source is distributed on account [5,3].
four groups of files in this account:
o
There are
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??. The overlays have
the following functions:
0. Pass
0
reads
the
input
source
file,
writing a
[[
Page 3-2
C Compiler and Library]]
Software Support Manual
temporary file after processing
and #ifdef statements.
#define,
#include,
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 code
generator is contained in this file. Except 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
delete work files.
end
of
processing code to
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.
The
following
file
conventions
are
used:
VMS command files
[[
Page 3-3
C Compiler and Library]]
Software Support Manual
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 or RSX
mode. All routines should be compiled together with either
RT11.MAC (no EIS support), RT11.EIS (hardware EIS support), or
[[
Page 3-4
C Compiler and Library]]
Software Support Manual
RSX.MAC, identical copies of which are present in each account.
To build
files:
the
libraries,
RMAKLB.CMD
VMAKLB.COM
XMAKLB.CMD
MMAKLB.CMD
TMAKLB.COM
execute one of the following command
RT11
RSX
RSX
RSX
RT11
library
library
library
library
library
on
on
on
on
on
RSTS/E
VMS
RSTS/E
RSX-11 (RMS or FCS)
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 C
programs access to all RSTS/E executive functionality. There is
no documentation other than the source code and [5,6]README.506.
3.4 The RSX-11 + P/OS Extensions Library
______ __________ _______
___ ______
Account [5,7] contains a library of subroutines that allow C
programs access to all RSX-11M, M+, MICRO-RSX and P/OS executive
functionality, including AST's. Refer to [5,7]CX.DOC for more
information. This library has not been tested on 'emulated'
RSX-11M modes (under VMS or RSTS/E), nor on IAS.
This library may be built on any of the RSX-ish systems, but
several services are particular to certain systems.
The CX
build command file CXMAK.CMD allows you to build the library for
native use on RSX-11M, RSX-11M PLUS, MICRO-RSX
or
P/OS
PRO/Toolkit.
In addition, it may be build on RSX for use with
the Host Toolkit for P/OS. In the latter case, the library will
be specially named and placed in LB:[1,5], the toolkit UIC. See
[5,7]CXMAK.CMD for more information.
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.
[[
Page 3-5
C Compiler and Library]]
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 of the
run-time library.
grep
'Get regular expression pattern.' This 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
other programs.
wc
Count bytes,
files.
ccxrf
Cross-referenced listings for C source files.
words,
Please refer to README.???
for more information.
for
and
incorporation into
lines in one or more
files in the appropriate accounts
3.7 Building the Documentation
_____________
________ ___
Compiler and assembler documentation is in CC.RNO and AS.RNO
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 within the
library source (Macro) files.
To
build the library documentation, the following programs must
[[
Page 3-6
C Compiler and Library]]
Software Support Manual
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
[.COMMAND]. The running
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
[.COMMAND]. The running
stored in C:.
kwik
is stored in [5,1] or
program is normally
is stored in [5,1] or
program is normally
This is the keyword in context program which is
used to build the library index. It is built as
part of the tools build procedure.
The source of kwik.c is stored in [6,1] or
[.TOOLS].
The running program is generally
written to a public library, PUB: on RSTS/E,
BIN: on VMS.
fixdoc
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 only on
____
RSTS/E.
The control files [5,1]RGTRNO.CMD and [5,1]RGTDOC.CMD illustrate
the process on RSTS/E while VGTRNO.COM and
VGTDOC.COM illustrate it on VMS.
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
O
Switch
P
Switch
Ux[name] [attr] Define
Flow control:
L [number]
J [number]
X
N
to the string P-section (c$strn)
to the data
P-section (c$data)
to the program P-section (c$code)
program section (x == P or D)
Define a local label
Jump to a local label
Function exit
Function entry
Data reservation, etc.:
A
Generate
B [number]
Generate
D
Generate
G
Generate
H
Generate
I
Generate
Y
Generate
Special operations:
a
a
an
a
a
a
a
.even pseudo-op
.blkb [number]
external label
.globl
.byte
.word as a local pointer
.word
@
W
Q
M
No-op: generate a comment
Generate a switch table
Dump symbol table entry (-t switch)
Transmit a line number between passes
[[
Page 4-2
C Compiler and Library]]
Software Support Manual
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
as
that 'trees' are the result of compiling expressions, such
(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
name.
OP.LID
Local identifier (label), followed by number.
identifier,
followed
by
type,
and identifier
other
An operator (OP.ADD, etc.) followed by the type code.
Subsequent records contain the left subtree, then the
right subtree.
(OP.EOF is used to signal a null
subtree.)
[[
Page 4-3
C Compiler and Library]]
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
|
|
|
|
|
|
|
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
The C source code is parsed by a 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 code generator. The Sethi-Ullman
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
Dummy address expressions
&(*A) all become A.
are
eliminated:
*(&A) and
[[
Page 4-4
C Compiler and Library]]
Software Support Manual
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
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.
are
used
in
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.
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
[[
Page 4-5
C Compiler and Library]]
Software Support Manual
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
int
int
any
[LL]
inc
int
any
[LL]
add
int
any
[SRV]
int
[LL]
add
int
any
[PR]
[LL]
add
con1
; Add 1 to any integer
; Compile left (subtree)
; INC Rx
addr
; Add var. to anything
; Compile left (subtree)
; ADD var,Rx
[R]
[AR],[R]
easy
;
;
;
;
[AR],[R]
int
Setup right value,
NOP if it's an address
Compile left (subtree)
Add var,Rx
any
(sp)+,[R]
; Compile right to stack
; 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]
int
char
addr
int
any
addr
int
any
[LR]
mov[TL] [R],[AL]
int
any
int
con0
con0
easy
;
;
;
;
I = 0;
C = 0;
Get left op. address
CLR(B) var
; Compile right subtree
; MOV(B) Rx,var
char
any
int
easy
[SRV]
[SLAC]
mov[TL] [AR], [AL]
; Setup right value
; Setup left address
[[
Page 4-6
C Compiler and Library]]
Software Support Manual
int
char
any
int
any
any
int
any
[PLA]
[LR]
mov[TL] [R],@(sp)+
; Push left address
; Compile right value
Note that the "easy" storage will 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 side-effects.
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]
[ARN]
[OP.0]
[OP.1]
[TL]
[T]
[SRVA]
[SRV]
[SRAA]
[SRA]
[SLVA]
[SLV]
[SLAA]
[SLA]
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
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
Set left address
______ ____
[SLAC]
[LL]
[LL.1]
[LL.O]
[LLP.O]
[LLP.E]
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
[[
Page 4-7
C Compiler and Library]]
Software Support Manual
[LR]
[LRP.E]
[PL]
[PLA]
[PR]
[V]
[FPI]
[FPL]
[FPF]
[FPD]
[GO.TO]
[IFEIS]
[IFFPU]
[IFOP]
[ELSE]
[ENDIF]
[DEBUG]
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
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.
For more information,
consult "The C Programming Language" by Brian Kernighan and
Dennis
Ritchie
(Englewood
Cliffs,
NJ:
Prentice-Hall,
ISBN 0-13-110163-3).
Routines and global symbols beginning with '$$' 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.
[[
Page 5-2
C Compiler and Library]]
$$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 C-bit
set.
In RSX mode, the record gets padding that may be needed
by $$put.
Bugs
[[
Page 5-3
C Compiler and Library]]
$$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
[[
Page 5-4
C Compiler and Library]]
$$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.
exit from C programs.
Diagnostics
Bugs
It is called on
[[
Page 5-5
C Compiler and Library]]
$$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
[[
Page 5-6
C Compiler and Library]]
$$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 is followed by a
<newline>).
$$ctim(0) returns the
$$rtim() internally.
The
format
current
time
of
day, calling
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.
[[
Page 5-7
C Compiler and Library]]
$$ctim
Convert $$rtim Buffer to Ascii
Bugs
There is no range checking on the information passed.
[[
Page 5-8
C Compiler and Library]]
$$div2
Unsigned divide (Macro only)
5.6 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
[[
Page 5-9
C Compiler and Library]]
$$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 The
text is written to buff[]. $$dtoa() returns a 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" and "d" in the format string "%f.df" Conv is 'e',
'f', or 'g' to define the format. Note: the conversion
character must be in lower-case.
To use floating point conversion, the
reference the $$fpu global as follows:
extern
int
program must
$$fpu;
If this is not done, attempting to convert floating
point will result in your program crashing.
Bugs
Only single precision conversion is done so far.
The
machine
must
support
FPU
floating
point, which
[[
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 Scan file name for fopen
5.10
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. Used on RSX only.
Bugs
[[
C Compiler and Library]]
Page 5-14
$$flsh Flush output buffers
5.11
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 "command terminal",
the flush is to stderr.
Bugs
[[
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 is defined at assembly time by a
macro (FSRSZ$) which 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
multiply.
the
Bugs
BEWARE:
untested
compiler
to
execute
floating-point
[[
C Compiler and Library]]
Page 5-17
$$fopa Open file (RT11 only)
5.14
Open file (RT11 only)
____ ____ _____ _____
**********
* $$fopa *
**********
File name:
iofopa.mac
Usage
mov
mov
jmp
iov,r4
lun,r3
$$fopa
mov
mov
mov
iov,r4 ;r4 -> iov
lun,r3 ;r3 := lun
dblk,r1 ;r1 -> Rad50 device descriptor, followed
;by filesize word if write reqeust.
$$fopr ;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.
jmp
;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.
Description
Actually
open
the
RT11 file,
management and post-open cleanup.
Bugs
doing
data
buffer
[[
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
$$fpar Parse and Setup RMS Control Blocks
5.16 Parse and Setup RMS Control Blocks
_____ ___ _______ ______
_____ ___
**********
* $$fpar *
**********
File name:
fpar.mac
Usage
mov
call
iov,r4
$$fpar
;r4 -> iov
;C$PMTR+0(r5) => file name
;file name is parsed and FAB/RAB etc.
setup.
;r0-r3 random
;error: return to caller via $$fope
Description
Parse the file name argument, and dynamically create the
RMS-11 specific blox (FAB, RAB, NAM block, DAT block &
PRO block). Used on RSX/RMS-11 only. If possible, this
routine establishes RMS-11 wildcard context.
Bugs
[[
C Compiler and Library]]
Page 5-20
$$fsav Floating-point support routines
5.17 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 floating-point
simulation package. They are never called by the C
program.
Bugs
BEWARE:
untested.
Note also that these routines are single-precision,
whereas
C
requires
double
precision.
When/if
floating-point becomes a reality, something better will
have to be done.
[[
C Compiler and Library]]
Page 5-21
$$gcmd Parse command line
5.18
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-22
$$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 handle the Dec Internation
character set.
[[
C Compiler and Library]]
Page 5-23
$$get
Get a record
5.19
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 a block
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.
It
is fixed at 512. bytes on RT11.
If the file is defined as "stream" (the "n" flag was not
set when the file was opened using fopen()), the end of
the line will be represented by the newline (\n)
character, and NULL's will be removed.
Bugs
[[
C Compiler and Library]]
Page 5-24
$$getc Get characters
5.20
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 next
byte in the indicated file is returned in r0. All other
registers are preserved. $$getc will allocate a buffer
if necessary.
This routine removes all NULL bytes and
<CR><LF> sequences unless the file was opened
'n' (nostream) option.
<CR> from
with the
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
.gtline. There is thus
"native" system calls.
reading using either .ttyin or
special case code to force
[[
C Compiler and Library]]
Page 5-25
$$gsa
Get-space routine
5.21
Get-space routine
_________ _______
*********
* $$gsa *
*********
File name:
mygsa.mac
Usage
Internal
Inputs:
r0 --> pool free-space list (not used)
r1 =
size (bytes) of requested/released block
r2 =
0 if allocating a block, address of first
word being released if deallocating.
Outputs:
Successful allocation:
C-bit cleared and R0 --> allocated block
Unsuccessful allocation:
C-bit set
Deallocation:
Nothing returned
Description
RMS-11 pool management routine. Used to allocate and
deallocate space to meet the needs of RMS-11 operations.
[[
C Compiler and Library]]
Page 5-26
$$init One-time initialization code
5.22 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. Note the following:
On RSX11/M (even emulated), argv[0] will be set to the
task name. On RT11 modes, argv[0] will be set to a
dummy value.
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 (argv, argc) {
...
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
[[
C Compiler and Library]]
Page 5-27
$$init One-time initialization code
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.
It may not work
correctly on earlier (or later) releases.
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 (because of unbalanced quotation
marks, for example).
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.
All errors are fatal.
Bugs
suggests
a
severe
case of
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 name
[[
C Compiler and Library]]
Page 5-28
$$init One-time initialization code
translations coupled with long 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
"bin:prog".
form
of
the
"program"
command is just
On VMS V3.0 and V3.1, the distributed RSX file service
(FCS) refuses to open "stream Ascii" files. This module
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 compile-time
switch enables this patch.
There 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 fails to open stderr or
obtain partition parameters.
[[
C Compiler and Library]]
Page 5-29
$$link Print memory list
5.23
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 randomly in
memory.
Note that it preserves all registers.
Diagnostics
Bugs
[[
C Compiler and Library]]
Page 5-30
$$ltoa Convert long to Ascii
5.24
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 buffer.
The 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)
[[
C Compiler and Library]]
Page 5-31
$$main Start of C programs
5.25
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 program,
exit() is called to close all files and return to the
operating system.
The following globals are defined in this module:
$$opsy
Operating system unique value.
This
value is 7 on RT11, and set as per the
GTSK$ directive on RSX-based systems:
RSX11-D
0.
RSX11-M
RSX11-S
IAS
RSTS/E V7
VMS
1.
2.
3.
4.
5.
[[
C Compiler and Library]]
Page 5-32
$$main Start of C programs
RSX11-M+
RT11
P/OS
6.
7.
9.
$$rsts
This value is non-zero if the program is
running on RSTS/E.
It is zero if the
program is running 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
On RSX, the default UIC word from GTSK$.
Internal
All $$ values are for
runtime library routines.
internal communication among
I.e., let them alone.
Diagnostics
On RSX, the task aborts with a BPT if the standard error
file did not open.
Otherwise,
explanatory
error
messages are printed.
Bugs
[[
C Compiler and Library]]
Page 5-33
$$mchk Verify memory allocation pointers
5.26 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. $$mchk preserves all registers.
Bugs
[[
C Compiler and Library]]
Page 5-34
$$narg Define default for $$narg
5.27
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 is tested by the initialization code before the
main() program is called.
Bugs
[[
C Compiler and Library]]
Page 5-35
$$prmt Null prompt pointer
5.28
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 RSX or "Argv:" on
RT-11.
[[
C Compiler and Library]]
Page 5-36
$$prnt Print formatter
5.29
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-37
$$put
Write a record -- RSX only
5.30
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
(first).
is
to
a
terminal,
stderr will be flushed
If the RMS-11(V2) version is in use, $$put supports
updating of records within an existing sequential file,
if the new record is the same length as the old one.
Bugs
[[
C Compiler and Library]]
Page 5-38
$$putc Output one character to a file
5.31 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-39
$$qiow Call RSX executive service
5.32
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
such.
a qio$ directive
Uses r0, r1.
for
all I/O requests needing
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-40
$$rtim Date and time conversion
5.33
__________
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 compatible with the RSX11-M GTIM$ executive
service.
Bugs
[[
C Compiler and Library]]
Page 5-41
$$scan Formatted input conversion
5.34
__________
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.
description of scanf() for more details.
See
the
Bugs
$$scan() is functionally identical to the _doscan()
routine in Unix and Vax-11 C libraries.
Unfortunately,
the leading '_' conflicts with RSX FCS library name
conventions.
[[
C Compiler and Library]]
Page 5-42
$$svr1 Save registers r1-r5 on the stack
5.35 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-43
$$tens Conversion table for dtoa, atof
5.36 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-44
$$utim Convert $$rtim buffer to Unix time
5.37 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 local timezone
or daylight savings time.
Bugs
This routine works only in the range:
1970 <= year < 2100
[[
C Compiler and Library]]
Page 5-45
abort
Abort program with a BPT trap
5.38 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-46
abs
Integer absolute value
5.39
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-47
alloc
Allocate memory
5.40
Allocate memory
________ ______
*********
* alloc *
*********
File name:
alloc.mac
Usage
char *
alloc(n);
/*
-1 if no space
*/
Description
Allocate the requested
pointer to the first.
expanded as needed.
alloc() returns
allocated.
number of bytes, returning a
The program image will be
-1 if the requested space could not be
free() is used to return the buffer to free space.
See also
sbrk().
the
description
of
malloc(), realloc() and
Diagnostics
Bugs
alloc() is obsolete.
Use malloc() for new programs.
[[
C Compiler and Library]]
Page 5-48
ascr50 Ascii to Radix-50 conversion
5.41 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-49
asl$l
Shift long << long
5.42
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.
This is
compatible with the hardware ASH instruction.
Note that, if n is negative:
(l << n) == (l >> (-n))
Bugs
[[
C Compiler and Library]]
Page 5-50
asl$li Shift long << integer
5.43
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 is compatible with
the hardware shift instruction.
Bugs
[[
C Compiler and Library]]
Page 5-51
asr$u
Right shift unsigned >> integer
5.44 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 n is
negative, it acts as if (u << (-n)) were executed.
Bugs
[[
C Compiler and Library]]
Page 5-52
atod
Convert Ascii to double floating
5.45 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 "double"
number.
The BNF for numbers which can decoded 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 non-legal character.
(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:
This routine uses the table in the DOUTAB module.
[[
C Compiler and Library]]
Page 5-53
atod
Convert Ascii to double floating
[[
C Compiler and Library]]
Page 5-54
atof
Convert Ascii to double floating
5.46 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 "double"
number.
The BNF for numbers which can decoded 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 non-legal character.
(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:
This routine uses the table in the DOUTAB module.
[[
C Compiler and Library]]
Page 5-55
atof
Convert Ascii to double floating
[[
C Compiler and Library]]
Page 5-56
atofd
Convert ASCII to floating -- dummy
5.47 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-57
atoi
Convert Ascii to integer
5.48
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
stops
at
the
first
non-integer.
Leading spaces, tabs, plus-signs and/or
newlines are ignored. The integer may be preceeded by a
minus sign.
Bugs
[[
C Compiler and Library]]
Page 5-58
atoi8
Convert Ascii octal number to integer
5.49 Convert Ascii octal number to integer
_____ _____ ______ __ _______
_______
*********
* atoi8 *
*********
File name:
atoi8.mac
Usage
atoi8(p)
char
*p;
Description
Convert an Ascii octal number to an integer. No data
checking is performed.
The conversion stops at the
first
non-octal
integer.
Leading
spaces, tabs,
plus-signs and/or newlines are ignored.
[[
C Compiler and Library]]
Page 5-59
atol
Convert Ascii to long
5.50
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
stops
at
the
first
non-integer.
Leading spaces, tabs, plus-signs and/or
newlines are ignored. The integer may be preceeded by a
minus sign.
Bugs
[[
C Compiler and Library]]
Page 5-60
brk
Change memory allocation
5.51
__________
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 to
malloc() or file open routines may cause memory to be
corrupted by calling brk().
Diagnostics
Returns 0 if the brk() argument is reasonable.
-1 if it is greater than the current top of
(Use sbrk() to increase memory allocation.)
Bugs
Returns
memory.
[[
C Compiler and Library]]
Page 5-61
call
Call (Fortran) subroutine from C
5.52 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
calling sequence.
arg1
The first argument.
in
the
For example:
extern int
int
int
sort();
data_to_sort[NDATA];
ndata = NDATA;
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-62
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. Floating-point data return has not been
implemented.
[[
C Compiler and Library]]
Page 5-63
callc
Call (Fortran) subroutine from C
5.53 Call (Fortran) subroutine from C
_________ __________ ____ _
____
*********
* callc *
*********
File name:
callc.mac
Usage
integer callc
ivalue = callc(routine, arg1, ... argN)
Description
User-callable interface between
subroutines written in C.
Fortran
programs and
The arguments are as follows:
routine
The name of the C routine to
called.
arg1
The
(location
argument.
of
the)
be
first
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 C subroutine is
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 subroutines that may, in
turn, call C subroutines.
[[
C Compiler and Library]]
Page 5-64
callc
Call (Fortran) subroutine from C
The programmer can also define a dummy program that
resolves the globals referenced by CSV$ or modify
callc.mac to provide the necessary globals.
[[
C Compiler and Library]]
Page 5-65
caller Return name of profiled caller
5.54 Return name of profiled caller
________ ______
______ ____ __
**********
* caller *
**********
File name:
caller.mac
Usage
char
*
caller();
Description
If the
compiled
pointer
calling
enabled,
routine which called the current function was
using the profile option, caller() returns a
to the name of the calling function. If the
function was not compiled
with
profiling
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 have to be
modified.
Bugs
[[
C Compiler and Library]]
Page 5-66
calloc Allocate and Initialize Memory
5.55 Allocate and Initialize Memory
__________ ______
________ ___
**********
* calloc *
**********
File name:
calloc.mac
Usage
char *
calloc(n, m);
int
int
n;
m;
/* NULL if no space
/* Number of elements
/* Size of an element
*/
*/
*/
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
returns NULL.
See also
sbrk().
the
space
cannot be allocated, calloc()
description
of
malloc(), realloc() and
The space is returned by calling free().
Diagnostics
Bugs
[[
C Compiler and Library]]
Page 5-67
calltr Trace Path to the Caller
5.56
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-68
clearerr
Clear file error flags
5.57
Clear file error flags
_____ ____ _____ _____
************
* clearerr *
************
File name:
cleare.mac
Usage
clearerr(iop);
FILE
*iop;
Description
Clear the error flags for an open file. This may be
needed for interaction with the user's console terminal.
Bugs
[[
C Compiler and Library]]
Page 5-69
concat Concatenate strings
5.58
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.
pointer to the first byte of out.
Bugs
It returns a
[[
C Compiler and Library]]
Page 5-70
copy
Copy a given number of bytes
5.59 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-71
cpystr String copy
5.60
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-72
csv$
C register save and restore
5.61
___ _______
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)
|_______________|
|
|
R5 -> | Saved R5
|
|_______________|
|
|
C$AUTO-2(R5)
| Return add.
|
|_______________|
|
|
| First arg.
|
|_______________|
|
|
+2(R5)
+4(R5)
C$PMTR+0(R5)
[[
C Compiler and Library]]
Page 5-73
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 run-time
startup program from the (RSX) library.
Internal
The
global symbols needed
compiler are also included.
Bugs
for
the
Whitesmith's
C
[[
C Compiler and Library]]
Page 5-74
ctime
Convert time value to ascii
5.62 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,
localtime() to an ascii string.
The string is statically allocated.
as
returned
by
It has the format
Sun Sep 16 01:03:52 1973\n\0
012345678901234567890123 4 5
0
1
2
All the fields have constant
trailing newline, just:
char
extern char
int
*tp;
*ctime();
tvec[2];
width.
To remove the
time(&tvec);
tp = ctime(&tvec);
tp[24] = '\0';
Bugs
/* Get time
/* in Ascii
/* Fix newline
*/
*/
*/
[[
C Compiler and Library]]
Page 5-75
ctime
Convert time value to ascii
There is no range checking on the information passed.
[[
C Compiler and Library]]
Page 5-76
ctype
Character classification type table
5.63 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
included.
note
that
source
for
a
test program is
[[
C Compiler and Library]]
Page 5-77
ddtoa
Convert floating to ASCII -- dummy
5.64 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-78
delete Delete a named file
5.65
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.
If
none
is
provided,
file.nam;0 will be deleted.
Note that the 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-79
div$li Long division and modulus
5.66
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
Change one, change both.
version
of cret$ is present.
[[
C Compiler and Library]]
Page 5-80
eis$i
EIS emulator module
5.67
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
explicitly position this module
structure, refer to the title, EIS$I.
in
an
overlay
Bugs
Divide
by
remainder.
zero
yields
zero
for
the
quotient
and
[[
C Compiler and Library]]
Page 5-81
envsave Multi-level function return
5.68 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()). Envreset() may be made to look as
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
envreset():
int
illustrates
*save_frame;
use
of
envsave()
and
[[
C Compiler and Library]]
Page 5-82
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()
disaster will result.
It
is
highly
recommended
setjmp/longjmp instead.
has
already
that
returned,
programs
use
[[
C Compiler and Library]]
Page 5-83
error
Error exit from C programs
5.69
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 program
exits. If profiling was enabled, a subroutine call
trace will be written to stderr.
The exit status, $$exst, will be set to "error".
Diagnostics
Bugs
[[
C Compiler and Library]]
Page 5-84
exit
Exit from C programs
5.70
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.
2.
4.
8.
Calling
RSX
1.
0.
2.
4.
exit()
Meaning
IO_SUCCESS
IO_WARNING
IO_ERROR
IO_FATAL
with
-----
no message is printed
minor error
serious error
severe error
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 into $$exst
and exit via exit():
[[
C Compiler and Library]]
Page 5-85
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() or finalizers, or writing a
profile file.
Diagnostics
Bugs
[[
C Compiler and Library]]
Page 5-86
fabs
Floating absolute value
5.71
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-87
fclear Clear file error flags
5.72
Clear file error flags
_____ ____ _____ _____
**********
* fclear *
**********
File name:
fclear.mac
Usage
fclear(iop);
FILE
*iop;
Description
Clear the error flags for an open file. This may be
needed for interaction with the user's console terminal.
Bugs
[[
C Compiler and Library]]
Page 5-88
fclose Close a currently-open file
5.73 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.
error code is saved in $$ferr.
The
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-89
feof
Test for end of file
5.74
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-90
ferr
Test for file error
5.75
Test for file error
____ ___ ____ _____
********
* ferr *
********
File name:
ferr.mac
Usage
ferr(iop);
FILE
*iop;
Description
Return
file.
1
if
an
error
has been seen on the indicated
Bugs
Obsolete, use ferror() instead.
[[
C Compiler and Library]]
Page 5-91
ferror Test for file error
5.76
Test for file error
____ ___ ____ _____
**********
* ferror *
**********
File name:
ferror.mac
Usage
ferror(iop);
FILE
*iop;
Description
Return
file.
Bugs
1
if
an
error
has been seen on the indicated
[[
C Compiler and Library]]
Page 5-92
fflush Flush output buffers
5.77
Flush output buffers
_____ ______ _______
**********
* fflush *
**********
File name:
fflush.mac
Usage
fflush(iop);
FILE
*iop;
Description
Flush output buffers. This routine actually does I/O.
$$ferr is set if anything unexpected happens.
Bugs
[[
C Compiler and Library]]
Page 5-93
fget
Input a binary record
5.78
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.
maximum record size.
Maxbytes is the
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.
to test for end of file.
Use feof()
Fget() is not present on Unix standard I/O libraries.
Internal
On RT11, when the record is written by fput(), it is
preceeded by a two-byte byte count. This value is one
greater than the number of bytes in the record. (If a
zero count is read, it will mean "end of file.")
Bugs
[[
C Compiler and Library]]
Page 5-94
fgetname
Convert file name to Ascii
5.79
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, the correct
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.
The resulting
string can be surprisingly long if using RMS and DECnet
(DAP) file names, logicals on P/OS, etc.
If only the actual file name is needed, the following
code segment may be executed. As shown, it writes the
file name and filetype (extension) to a global "buffer".
[[
C Compiler and Library]]
Page 5-95
fgetname
Convert file name to Ascii
getfilename(fd, buffer)
FILE
*fd;
register char
*buffer;
{
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-96
fgets
Read a string from a file
5.80
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 bytes
to
read.
The string 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 newline is replaced by a null.
(This is
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 text lines packed into one logical record.
[[
C Compiler and Library]]
Page 5-97
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-98
fileno Get logical unit number
5.81
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-99
fill
Fill a Block of Memory With a Character
5.82 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 at addr
with the character ch.
Note:
To fill with zero
which is slightly faster.
Bugs
bytes, you can use zero(),
[[
C Compiler and Library]]
Page 5-100
flun
Get logical unit number
5.83
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-101
fmkdl
Mark file for deletion -- obsolete
5.84 Mark file for deletion -- obsolete
___ ________ __ ________
____ ____
*********
* fmkdl *
*********
File name:
fmkdl.mac
Usage
fmkdl(iop);
FILE
*iop;
Description
fmkdl() closes and deletes the specified file.
0 on success, -1 on error.
This routine is obsolete.
New
delete() instead.
To delete an
program may execute:
Returns
programs should call
existing file, the
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) that it shouldn't. Note that RT11 does
not flush the last buffer before deleting the file.
On VMS compatibility mode,
user's default directory.
the
file
must be in the
[[
C Compiler and Library]]
Page 5-102
fopen
C library file opener
5.85
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
jmp
iov,r4 ;r4 -> iov (or r4 == 0)
code,r0 ;r0 := error code (to go to $$ferr)
$$fope ;Error exit from fopen
;$$fope deallocates buffers
code.
Description
Fopen
mode:
opens
a
new
or
existing file in the indicated
[[
C Compiler and Library]]
Page 5-103
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 to the
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 single-character
or immediate return input. Output to the terminal will
[[
C Compiler and Library]]
Page 5-104
fopen
C library file opener
be performed without buffering, which
screen updating, but otherwise expensive.
is useful for
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 4-word
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, the program should call rewind() or freopen() to
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
Error exit from fopen
Normal open, hack append
Normal exit from fopen
[[
C Compiler and Library]]
Page 5-105
fopen
C library file opener
Warning:
fopen() in RSX/RSTS mode uses unpublished
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 is defined at assembly time by a
macro (FSRSZ$) which 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-106
fprintf Formatted Output Conversion
5.86
__________
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,
description of printf.
Bugs
please
refer
to the
[[
C Compiler and Library]]
Page 5-107
fps
Set floating point status (FPS)
5.87 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 simply
executing the LDFPS instruction.
This allows a 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 require floating
point operations.
[[
C Compiler and Library]]
Page 5-108
fput
Output a binary record
5.88
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-109
fread
Input a record
5.89
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 read. This
will be zero if an end-of-file or error was encountered.
Bugs
[[
C Compiler and Library]]
Page 5-110
frec
Return True if record-oriented file
5.90 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: in this
context, record-oriented files are not file-structured
disks, nor are they the user's console terminal. Other
terminals, along with devices such as line-printers,
qualify, however.
Bugs
[[
C Compiler and Library]]
Page 5-111
fscanf Formatted input conversion
5.91
__________
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
indicated format descriptor, storing the results in
pointer
arguments.
It
returns
the
number
successfully assigned input items.
See
the
description
documentation.
of
scanf()
for
the
the
of
further
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-112
fseek
Reposition file pointer (seek)
5.92 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
For RMS-11 versions, the sequence fseek() followed by
ftell() on the same file, with no intervening reads or
writes, will advance the position one record. This is
an unfortunate side-effect of the positioning hacks
required to make the well-behaved RMS "look" like the
crude UNIX positioning.
[[
C Compiler and Library]]
Page 5-113
fspool Spool file to default print queue
5.93 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
description of the spooling system function call.
the
[[
C Compiler and Library]]
Page 5-114
fspool Spool file to default print queue
[[
C Compiler and Library]]
Page 5-115
ftell
Get file position for subsequent seek
5.94 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" (with embedded control information).
The
[[
C Compiler and Library]]
Page 5-116
ftell
Get file position for subsequent seek
latter files may have multiple text lines embedded in
each record.
This is handled internally
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.
For RMS-11 versions, the sequence fseek() followed by
ftell() on the same file, with no intervening reads or
writes, will advance the position one record. This is
an unfortunate side-effect of the positioning hacks
required to make the well-behaved RMS "look" like the
crude UNIX positioning.
[[
C Compiler and Library]]
Page 5-117
ftime
Compute time of day (augmented)
5.95 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 system library (C:
or
sys$library: respectively).
Bugs
[[
C Compiler and Library]]
Page 5-118
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-119
ftty
Test if terminal file
5.96
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.
general, this means the user's command terminal.
In
Bugs
Obsolete
-use
transportability.
isatty(fileno(iop))
instead
for
[[
C Compiler and Library]]
Page 5-120
fwild
Wild-card file open
5.97
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
version number work correctly. Version numbers
work only if the directory has been reorganized
the SRD utility program. If the directory has
reorganized (such that the youngest version
wildcard
0 and -1
by using
not been
appears
[[
C Compiler and Library]]
Page 5-121
fwild
Wild-card file open
first
in
the
directory),
unpredictable results.
fnext()
will
yield
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 available on the various implementations of
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
wildcarded. VMS systems support ODS2.
RSX/RSTS
Uses RSTS/E wildcard conventions:
replaces
filename or filetype.
"*"
"?"
[[
C Compiler and Library]]
Page 5-122
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, "%"
match any non-blank character.
RT11/RSTS
Uses RSTS/E wildcard
above.
or
conventions
"?"
noted
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 if it
must call fnext() or if processing should be initiated
directly.
[[
C Compiler and Library]]
Page 5-123
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
module.
do not apologize for the size of this
The distribution of
source code for the
program.
the
SRD
C language system includes
(sort directories) utility
[[
C Compiler and Library]]
Page 5-124
fwrite Output a record
5.98
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-125
getchar Get characters
5.99
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
program may execute:
clearerr(iop);
Bugs
from
a
terminal
after EOF, the
[[
C Compiler and Library]]
Page 5-126
gets
Read a string from stdin
5.100
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-127
gettty Get control terminal name
5.101
________ ____
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.
This will
not
necessarily contain a valid unit number.
[[
C Compiler and Library]]
Page 5-128
getw
Input a binary integer from a file
5.102 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-129
inchr
Find Index of Character in a String
5.103 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.
If chr is not in stng, return
-1.
See also strchr().
Bugs
[[
C Compiler and Library]]
Page 5-130
index
Find First Instance of a Character in a String
5.104 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
return NULL.
stng,
return a pointer to it.
Bugs
Obsolete;
use strchr() instead.
If not,
[[
C Compiler and Library]]
Page 5-131
iov
I/O vector definition
5.105
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 titty
/* 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-132
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 and RT11 modes.
Note also that
certain bits in 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
Value Meaning
02. 002 Illegal file name
04. 004 No room for user on device
E$$FNF
E$$NOD
E$$ILU
E$$NOO
E$$EOF
05.
06.
07.
09.
11.
005
006
007
011
013
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
[[
C Compiler and Library]]
Page 5-133
iov
I/O vector definition
E$$FAT
E$$ERR
E$$FND
E$$NOC
E$$NSP
12.
13.
16.
17.
32.
014
015
020
021
040
Fatal system I/O failure
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-134
irand
Random number modulus argument
5.106 Random number modulus argument
______ _______ ________
______
*********
* irand *
*********
File name:
irand.mac
Usage
int
irand(arg)
int
arg;
Description
Generate a pseudorandom number in the range 0 ..
(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
[[
C Compiler and Library]]
Page 5-135
isalloc Check If a Pointer Points to Allocated Memory
5.107 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 25% of the time.
However, isalloc() is slower.
Bugs
Not portable.
[[
C Compiler and Library]]
Page 5-136
isalnum Return TRUE if Upper-case alphanumeric argument
5.108 Return TRUE if Upper-case alphanumeric argument
______ ____ __ __________ ____________ ________
***********
* isalnum *
***********
File name:
isalnu.mac
Usage
isalnum(c);
int
c;
Description
Return non-zero
otherwise.
Bugs
if
c
is an alphanumeric character, 0
[[
C Compiler and Library]]
Page 5-137
isalpha Test for alphabetic argument
5.109 Test for alphabetic argument
__________ ________
____ ___
***********
* isalpha *
***********
File name:
isalph.mac
Usage
isalpha(c);
int
c;
Description
Return non-zero
otherwise.
Bugs
if
c
is
an
alphabetic character, 0
[[
C Compiler and Library]]
Page 5-138
isascii Test for 7-bit Ascii character
5.110 Test for 7-bit Ascii character
_____ _____ _________
____ ___
***********
* isascii *
***********
File name:
isasci.mac
Usage
isascii(c);
int
c;
Description
Return non-zero
otherwise.
Bugs
if
c
is
a
7-bit Ascii character, 0
[[
C Compiler and Library]]
Page 5-139
isatty Test if terminal file
5.111
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 not related to
Unix file descriptors. Specifically,
isatty(0)
does not necessarily check stdin.
isatty(fileno(stdin))
instead.
Use
[[
C Compiler and Library]]
Page 5-140
iscntrl Test for control character argument ;02
5.112 Test for control character argument
____ ___ _______ _________ ________
___
***********
* iscntrl *
***********
File name:
isctrl.mac
Usage
iscntrl(c);
int
c;
Description
Return non-zero if C is a control character.
Bugs
;02
[[
C Compiler and Library]]
Page 5-141
isdigit Return TRUE if digit argument
5.113 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-142
isgraph Test for graphic alphabetic argument
5.114 Test for graphic alphabetic argument
___ _______ __________ ________
____
***********
* isgraph *
***********
File name:
isgrap.mac
Usage
isgraph(c);
int
c;
Description
Return
non-zero
otherwise.
if
c
is
a
graphic
character,
Graphics
characters
include
letters, digits,
punctuation. Space, tab, etc. are not graphics.
Bugs
0
and
[[
C Compiler and Library]]
Page 5-143
islower Test for lower-case alphabetic argument
5.115 Test for lower-case alphabetic argument
____ ___ __________ __________ ________
***********
* islower *
***********
File name:
islowe.mac
Usage
islower(c);
int
c;
Description
Return
non-zero
if C
character, 0 otherwise.
Bugs
is
a
lower-case
alphabetic
[[
C Compiler and Library]]
Page 5-144
isprint Return non-zero if printable argument
5.116 Return non-zero if printable argument
______ ________ __ _________ ________
***********
* isprint *
***********
File name:
isprin.mac
Usage
isprint(c);
int
c;
Description
Return non-zero
otherwise.
if
c
is
a
printable
character,
Printable
characters
include
letters,
punctuation, and the space character.
Tab,
etc. are not included.
Bugs
0
digits,
newline,
[[
C Compiler and Library]]
Page 5-145
ispunct Return TRUE if punctuation argument
5.117 Return TRUE if punctuation argument
____ __ ___________ ________
______
***********
* ispunct *
***********
File name:
ispunc.mac
Usage
ispunct(c);
int
c;
Description
Return
non-zero
otherwise.
Bugs
if
c
is
an
Ascii
punctuation,
0
[[
C Compiler and Library]]
Page 5-146
isspace Return non-zero if the character is "whitespace"
5.118 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,
tab,
and
form-feed. The carriage return ('\r') is also included.
Bugs
[[
C Compiler and Library]]
Page 5-147
isupper Return TRUE if Upper-case alphabetic argument
5.119 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 character, 0
otherwise.
Bugs
[[
C Compiler and Library]]
Page 5-148
isxdigit
Return non-zero if hexadecimal digit
5.120 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 (0-9,
A-F, a-f).
Bugs
This routine is not present in other C libraries.
[[
C Compiler and Library]]
Page 5-149
itoa
Integer to Ascii
5.121
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-150
itoa8
Convert integer to octal Ascii
5.122 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.
are needed, use:
sprintf(buffer, "%06o", value);
If they
[[
C Compiler and Library]]
Page 5-151
itoax
Convert an integer to hexidecimal Ascii
5.123 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-152
kbin
Single Character Terminal Input
5.124 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> ('\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, 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-153
kbinr
Terminal Input Without Wait
5.125
_______ ____
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-154
localtime
Build time of day buffer
5.126
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()
values.
converts
a
Unix time value to a vector of
Bugs
Decus C doesn't
savings time.
correct
for
time
Leap year isn't done correctly.
after Feb 28, 2100.
zone
or daylight
The routine will fail
Following Unix precedent, localt returns a pointer to a
static buffer.
[[
C Compiler and Library]]
Page 5-155
malloc Allocate and free memory
5.127
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 NULL. The
program image is expanded as needed.
free() and mfree()
Nothing is returned.
return
a
buffer
to
free space.
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-156
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.
is coalesced during the allocation search.
Free space
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-157
maxmin Maximum and Minimum Routines
5.128 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 and have some knowledge of the relative sizes
of a and b, arrange for a to be chosen most often.
(It's unlikely the difference will be noticable in
virtually all cases.)
Bugs
[[
C Compiler and Library]]
Page 5-158
memdmp Dump memory or registers
5.129
_________
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
preserved.
and/or
memory.
All
registers
are
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]]
Page 5-159
memdmp Dump memory or registers
Bugs
Condition codes are not preserved.
[[
C Compiler and Library]]
Page 5-160
msg
Print a message on the command terminal
5.130 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 routine
does not use the standard library.
Return:
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-161
msize
Get Size of a Memory Block
5.131
______ _____
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 allocations are rounded up to an even
number of bytes.)
Bugs
Not portable.
[[
C Compiler and Library]]
Page 5-162
mul$l
Multiply long * long
5.132
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. Then
A * B = Al * Bl
+
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-163
peek
Peek at a location in RSTS/E
5.133 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-164
perror Print Library Error Message
5.134
_____ _______
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). Text is prepended
to the message.
Diagnostics
Bugs
[[
C Compiler and Library]]
Page 5-165
printf Formatted print routine
5.135
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
character %. Following the %, there may be
- an
optional
minus
sign
"-"
which
by
the
specifies left
[[
C Compiler and Library]]
Page 5-166
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 '?', the next
argument is used.
- a character which indicates the
to be applied.
type
of
conversion
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-167
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.
**
**
**
**
**
**
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.
**
**
**
**
**
**
f
The 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." This is a restriction of Decus C.
e
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 to the precision
specified
for the
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
'lc' takes a long integer argument.)
r
Remote format. The next printf() argument is
the format. Note that this is not a subroutine.
that
The current format is not processed further. For
example:
bug(args)
{
[[
C Compiler and Library]]
Page 5-168
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 by all
"top-level" print functions.
It
is
functionally
identical to the Unix and Vax-11 C _doprnt() library
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,
necessarily present
"standard library."
Bugs
however, that _doprnt() is
on all implementations of
not
the
e, f, and g conversion only work for single-precision
floating point. Use of "%lf" etc. is not transportable
and may change.
It may also cause problems in the C
compiler (as the standard says that subroutine calls
take double (not short floating) arguments.
[[
C Compiler and Library]]
Page 5-169
printf Formatted print routine
[[
C Compiler and Library]]
Page 5-170
profile Print profile data
5.136
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. Changing
$$prnl to N writes N entries on each line, simplifing
post-processing (sorting) of the data. For example:
$$prnl = 0;
writes each entry on a separate line.
The following
file name:
example
shows how to control the output
extern char *$$pfil;
...
$$pfil = "ti:"; /* Output to ti:
$$pfil = NULL; /* No profile output
*/
*/
Data is written using the format string "%8s %6u". If
more than one entry is written to a line, succeeding
entries will be preceeded by one space.
[[
C Compiler and Library]]
Page 5-171
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-172
putc
Output one character to a file
5.137 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.
errors.
Bugs
EOF is returned on
[[
C Compiler and Library]]
Page 5-173
puts
Output a string to a file
5.138
__ _ ____
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.
appends a newline after the string.
It
fputs() writes a string
newline is appended.
No
fputss() writes a string
newline is appended.
Bugs
to
to
the
the
indicated file.
indicated file.
A
[[
C Compiler and Library]]
Page 5-174
putw
Output a binary integer to a file
5.139 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
returns EOF on error, 0 on success
Bugs
indicated
file.
It
[[
C Compiler and Library]]
Page 5-175
qset
Add memory to the RT11 queue area
5.140 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 of
queue elements.
If sufficient
memory
cannot
be
allocated, do nothing.
Bugs
This routine is ignored on RSX.
[[
C Compiler and Library]]
Page 5-176
r50toa Convert Radix-50 to Ascii
5.141
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-177
rand
Random number generator
5.142
_________
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-178
realloc Reallocate memory
5.143
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
sbreak().
the
description
of
malloc(),
calloc() and
The
following
program segment illustrates
realloc() to expand and compact storage.
#ifndef vms
static char *compact_work;
#endif
main() {
/*
* Initialize work element
* for compact()
*/
#ifndef vms
use
of
compact_work = malloc(1);
#endif
...
}
[[
C Compiler and Library]]
Page 5-179
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 of a
buffer allocated by malloc() or calloc().
Bugs
[[
C Compiler and Library]]
Page 5-180
rewind Rewind a file for re-reading
5.144 Rewind a file for re-reading
___ __________
______ _ ____
**********
* rewind *
**********
File name:
rewind.mac
Usage
rewind(iop);
FILE
*iop;
Description
Rewind
ok.
the
indicated file.
Return -1 if failure, 0 if
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-181
rindex Find Last Instance of a Character in a String
5.145 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-182
rstsys Execute a RSTS EMT
5.146
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-183
rtemt
Execute a RT11 EMT
5.147
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-184
salloc Allocate local memory
5.148
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
freed.
storage
so
allocated
cannot be explicitly
salloc() returns NULL if allocating the requested space
would cause the run-time stack to go below 1000 octal.
Note:
it is
"clean stack".
essential that salloc() be called with a
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-185
sbrk
Allocate memory from operating system
5.149 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
available. There is no "shortened" return.
Bugs
Internal
Sbrk() does not modify its argument.
is
not
[[
C Compiler and Library]]
Page 5-186
scanf
Formatted input conversion
5.150
__________
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:
' '
Blanks, tabs, or newlines are ignored in
format
[[
C Compiler and Library]]
Page 5-187
scanf
Formatted input conversion
strings.
To match whitespace, use "%[ \t\n]".
x
An ordinary character
next input character.
(not
%) must match the
%
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
assignment is done.
in
the
input,
no
d
o
x
An integer of the specified class (decimal,
octal, or hexadecimal)
is
expected.
The
corresponding 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".
Leading whitespace will be ignored.
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
stored
f
g
appropriately.
If the format indicator is
capitalized, or preceeded by 'l', a doubleprecision floating-point number will be stored.
The floating-point format is the same as in the
C language:
an optionally signed string of
[[
C Compiler and Library]]
Page 5-188
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: the
input field is all characters until the first
character which is not in the set
within
brackets.
Note that leading whitespace is not
ignored.
If the first character after the left bracket is
'^', the format defines a stop list: the input
field
is
all
characters until the 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
print:
input
line
is
"150 foobar", the program will
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 incorrect format, such as "%" is
encountered.
Bugs
[[
C Compiler and Library]]
Page 5-189
screen Screen I/O Primitives
5.151
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)
char
Write text to screen */
Line number
*/
Column number
*/
Text to write
*/
/* Reset buffer mode
*oldbf; /* Previous buffer
*/
*/
int
scset(newbf, size, old)
char
/* Set buffer mode
*newbf; /* New buffer
*/
*/
[[
C Compiler and Library]]
Page 5-190
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.
They work correctly with
VT52
and
VT100
(ANSI) terminals and do nothing
disasterous if the terminal is not a video terminal.
Note that they only
(stderr) terminal.
work
with
the
user's
console
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. This value will be offset by the
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.
Each buffer must be at least 12 bytes long.
[[
C Compiler and Library]]
Page 5-191
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 handler calls operating system service directly,
bypassing the "standard" I/O library. This means that
output formatting should use sprintf() to format a user
buffer which 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 the end of the current
line.
(VMS
Lib$Erase_Line)
[[
C Compiler and Library]]
Page 5-192
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 one
will be written to column lmarg.
scout(line, column, text)
Move the cursor to the indicated line and column and
output the text. If line or column are less than or
equal to zero, the cursor is not moved. If text is
equal to NULL, the internal buffers
are
flushed
(possibly after cursor movement). (VMS Lib$Put_Screen)
scput(oldbf)
Scput()
terminates the current buffering mode and
reverts to 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
[[
C Compiler and Library]]
Page 5-193
screen Screen I/O Primitives
to the previous buffer (if any). This is used for a
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
Not a video terminal
VT52 or VT100 in VT52 mode
VT100 in ANSI mode
If type has some
change the type.
other
value,
scsettype() does not
sctype()
This routine returns the terminal type.
types are defined:
0
1
1+64
1+96
The following
Not a video terminal
Unknown video terminal
VT52
VT100 type
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
*/
[[
C Compiler and Library]]
Page 5-194
screen Screen I/O Primitives
scset(mybuf, sizeof mybuf, &oldbuf);
/*
* Usage
*/
scout(1, 1, "Stuff");
/*
* Termination (force out last buffer)
*/
scout(0, 0, NULL);
scput(oldbuf);
}
Bugs
These routines
supplied.
are
fairly inefficient if no buffer is
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
characteristics" request is executed, the
proceeding as above.
"get terminal
determination
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 XM monitor.) If so, an "<ESC>/Z" is sent to request
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
interest:
The
VMS
generally
library standard assumes
return a
status
code,
be
of
that subroutines
permit
missing
[[
C Compiler and Library]]
Page 5-195
screen Screen I/O Primitives
parameters, and return error codes on being presented
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 or CO:). scget() reads from the standard
input.
[[
C Compiler and Library]]
Page 5-196
setcc
Trap Control/C (RSTS/E RT11 mode only)
5.152 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 CTRL/C was
typed during the execution of function()), the program
aborts.
Bugs
Runs on RSTS/E RT11 mode only.
[[
C Compiler and Library]]
Page 5-197
setjmp Execute non-local goto
5.153
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();
}
...
process() {
...
/* Setjmp
called
*/
[[
C Compiler and Library]]
Page 5-198
setjmp Execute non-local goto
longjmp(&env);
The routine that called setjmp() must still be active
when longjmp() is called.
Bugs
[[
C Compiler and Library]]
Page 5-199
sleep
Delay job a given number of seconds
5.154 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
executes a mark-time (MRKT$) and wait
event flag 1.
On native
request.
RT11,
sleep()
executes
Sleep flushes stdout and stderr.
by VMS, sleep()
sequence, using
a .TWAIT executive
[[
C Compiler and Library]]
Page 5-200
sprintf Formatted Numeric Conversion
5.155 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,
description of printf.
please
refer
to the
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-201
sscanf Formatted input conversion
5.156
__________
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 in
the
pointer arguments.
It returns the number of
successfully assigned input items.
See
the
description
documentation.
of
scanf()
for
further
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-202
strcat String Concatenate
5.157
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-203
strchr Find First Instance of a Character in a String
5.158 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
return NULL.
stng,
See also index().
Bugs
return a pointer to it.
If not,
[[
C Compiler and Library]]
Page 5-204
strcmp String Compare
5.159
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-205
strcpy String copy
5.160
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-206
streq
String Equality Test
5.161
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-207
strlen String length
5.162
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-208
strncat String Concatenate
5.163
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. Note that "count" does not
include the trailing null.
Bugs
[[
C Compiler and Library]]
Page 5-209
strncmp String Compare With Count
5.164
____ _____
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
returning:
most
count
-1 if s1 < s2
0 if s1 == s2
+1 if s1 > s2
Bugs
bytes
between
two
strings,
[[
C Compiler and Library]]
Page 5-210
strncpy String Copy With Count
5.165
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".
are moved from in.
trailing null.
Return out.
Note that
At most, "count" bytes
"count" includes the
If strlen(in) is less than count, "out" is null-filled.
If strlen(in) is greater than count, the output buffer
will not be null-trailed.
Bugs
[[
C Compiler and Library]]
Page 5-211
strneq String Equality Test With Count
5.166 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
returning TRUE if the the strings are equal.
Bugs
strings,
[[
C Compiler and Library]]
Page 5-212
strrchr Find Last Instance of a Character in a String
5.167 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.
Bugs
[[
C Compiler and Library]]
Page 5-213
swabb
Byte swap (argument is a buffer pointer)
5.168 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 need not be on any particular byte or
word boundary.
Bugs
[[
C Compiler and Library]]
Page 5-214
swabi
Byte swap, (argument is an integer)
5.169 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-215
time
Compute time of day
5.170
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.
non-null, the return value is also stored in
to which tloc points.
The value is the time
measured in seconds.
since
midnite,
If tloc is
the place
Jan 1, 1970,
Note
If time() appears to give the wrong value, check that
you have declared it
extern long time();
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
[[
C Compiler and Library]]
Page 5-216
time
Compute time of day
returns local time.
The leap year algorithm is only accurate in the range
1970 <= year < 2100
[[
C Compiler and Library]]
Page 5-217
toascii Convert to 7-bit Ascii
5.171
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-218
tod
Compute time of day
5.172
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.
non-null, the return value is also stored in
to which tloc points.
If tloc is
the place
tod() is fairly fast. time() computes the "Unix time"
but is much slower and larger.
Bugs
[[
C Compiler and Library]]
Page 5-219
tolower Convert upper-case to lower-case
5.173 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 lower-case
equivalent. Otherwise, return c.
Bugs
[[
C Compiler and Library]]
Page 5-220
toupper Convert lower-case alphabetic to upper-case
5.174 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 upper-case
equivalent. Otherwise, return c.
Bugs
[[
C Compiler and Library]]
Page 5-221
trace
Profile support entry module (with trace)
5.175 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
Description
This module is
compiled with the
that the stack
function executes
called whenever a function that was
profile option is executed. It checks
will remain above 600 octal when the
and optionally prints a flow-trace.
If $$flow is set to a file descriptor, the function
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 argument pointer (for local addressing within the
[[
C Compiler and Library]]
Page 5-222
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 an operating-system trap (such as an
illegal
memory
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.
See the
description there for more information.
Bugs
[[
C Compiler and Library]]
Page 5-223
traps
Operating system trap handlers
5.176 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
operating system with a "severe error" status.
Note
to the
that some errors, such as stack overflow or random
[[
C Compiler and Library]]
Page 5-224
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
implemented.
to
handle
floating-point
when
it's
[[
C Compiler and Library]]
Page 5-225
ungetc Push back a character onto an input file
5.177 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-226
unwind Execute non-local goto
5.178
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 be active
when unwind() is called.
Bugs
Obsolete -- use setjmp/longjmp instead.
[[
C Compiler and Library]]
Page 5-227
wdleng Expensive way to say sizeof(int)
5.179 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-228
wrapup Dummy routine called on exit
5.180 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-229
zero
Clear a block of memory
5.181
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
pre-processor command of the form:
#include <filename.h>
your
program
source
by
a
[[
Page 6-2
C Compiler and Library]]
Software Support Manual
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:
[[
Page 6-3
C Compiler and Library]]
fps
Bit definitions for the floating point status word
6.2 Bit definitions for the floating point status word
___ ___________ ___ ___ ________ _____ ______ ____
*******
* fps *
*******
File name:
NAME:
fps -word
fps.h
Bit
definitions
for the floating point status
SYNOPSIS:
#include <fps.h>
DESCRIPTION:
This module defines common definitions for the FP-11
floating point status word. The following are defined:
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
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)
[[
Page 6-4
C Compiler and Library]]
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. However, it is impossible to
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 could be quite expensive if they are very small
[[
Page 6-5
C Compiler and Library]]
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.
defining module includes the calls:
The
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 and FINAL generate dsect commands.
Since C
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.
[[
Page 6-6
C Compiler and Library]]
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 initialization and
finalization list.
The names 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,
non-portable. It may be possible to provide the
functionality
using different techniques;
if
what's wrong with your implementation?
AUTHOR:
Jerry Leichter
very
same
not,
[[
Page 6-7
C Compiler and Library]]
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.
[[
Page 6-8
C Compiler and Library]]
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
setjmp() and longjmp() functions.
BUGS:
that is used for the
[[
Page 6-9
C Compiler and Library]]
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
objects of this type.
and
return pointers to
NULL
I/O routines signal "rejection" by
null pointer.
EOF
The get character routine returns this value
signal end of file.
TRUE
The value 1.
returning
a
to
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
stdin
"Severe error" exit to operating system.
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
some other C systems.
are not present in <stdio.h> on
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 is neither fully
supported nor fully implemented.
[[
C Compiler and Library]]
Page 6-11
stdio
Definitions for standard i/o library
[[
C Compiler and Library]]
Page 6-12
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
buffer used by the
standard
library
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;
};
/*
/*
/*
/*
/*
/*
/*
/*
/*
of the time
localtime()
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-13
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
buffer used by the standard
It is defined as follows:
struct timeb {
long
unsigned
short
short
};
the structure of the timeb
library ftime() function.
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 of
minutes past GMT in the 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.
likely strategy is to have several kits:
The most
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 only
-- no sources.
Suggestions for improvements are welcome.
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
[[
Page A-2
C Compiler and Library]]
Getting on the Air with Decus C
compiler was written by David G. Conroy, and modified by Martin
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 may 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]
[6,2]
[6,3]
[6,4]
[6,5]
[6,6]
[6,7]
"Software tools."
Miscellaneous programs -- games and stuff.
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 README.nnn describing the
contents of the account.
For example, the README file in
account [5,1] is named README.501.
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
[[
Page A-3
C Compiler and Library]]
Getting on the Air with Decus C
X?????
RSX-11M file for the RSTS/E RSX emulator
R?????
RT-11
M?????
RSX-11M indirect command file
T?????
RT-11
.CMD
RSTS/E indirect 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
file for the RSTS/E RT-11 emulator
indirect command file
Command files used to build tools
follow the following convention:
and C-language libraries
VN????
Use the native Vax-11C compiler only.
VX????
Use Decus-C (RSX compatibilitye) on Vax/VMS.
VB????
Use
either,
invocation.
RX????
RSTS/E RSX-11M emulation mode.
RT????
RSTS/E RT-11 emulation mode.
M????
RSX-11M native.
T????
RT-11 native.
selecting
the
compiler
A.4 Distribution Contents in Detail
________ __ ______
at
command
____________
[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
[[
Page A-4
C Compiler and Library]]
Getting on the Air with Decus C
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 a new
documentation kit. To build the documentation, proceed
as follows:
1.
Build the compiler and libraries.
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 using the
BTOOLS.COM or RTOOLS.CMD command files.
[5,2]
RSTS/E only
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
command
procedures reference
account [5,2] 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.
[[
Page A-5
C Compiler and Library]]
Getting on the Air with Decus C
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
On
On
On
On
On
VMS
RSTS/E RSX mode
RSTS/E RT-11 mode
RSX native mode
RT-11 native mode
Common Library
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
source files.
contains I/O
These files
dependent run-time library
conditionally compile to
[[
Page A-6
C Compiler and Library]]
Getting on the Air with Decus C
generate code for either RSX-11M or RT-11 operating
system support.
You 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.
It 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
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]
Software Tools
C tools.
See [.tools]readme.601 for
following command files are provided:
details.
The
V?TOOL.COM
Vax/VMS:
VNTOOL uses the native
compiler VAX-11C; VXTOOL uses Decus C;
and VBTOOL allows selection of either.
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
[[
Page A-7
C Compiler and Library]]
Getting on the Air with Decus C
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 and Other Stuff
Toys,
half
baked
ideas,
and other stuff.
See
[.misc]readme.602 for details.
Command
files
are
provided to build COOKIE on RSTS/E and VMS. Some of
these files haven't been touched in years.
[6,3] [.cross]
Cross Assemblers
A variety of cross assemblers. See [.cross]readme.603
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 printf are
present. It is hoped that this account will eventually
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
[[
Page A-8
C Compiler and Library]]
Getting on the Air with Decus C
Interface
are being
product.
Vax-11 C
superseded
routines for use with Decus C programs which
transported to the native VMS C program
This library predated the released version of
and may contain modules that have
been
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
____________ ________
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.
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 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
symbol C$$EIS to zero.
to
set
The native RSX build command file inquires whether SXT
and EIS defaults must be set.
[[
Page A-9
C Compiler and Library]]
Getting on the Air with Decus C
A.5.1
Installation on RSTS/E
____________ __
______
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.
RSTS/E systems and should be deleted.
It is not needed for
The system manager should add the following commands to your
system startup command file (before executing RBUILD):
RUN $UTILTY
ADD LOGICAL disk:[account] C
CCL XCC-=C:CC.TSK;0
CCL XAS-=C:AS.TSK;0
CCL CC-=C:CC.SAV;8220
CCL AS-=C:CC.SAV;8220
CCL CRUN-=C:CRUN.*;30000
EXIT
!
!
!
!
!
!
define C logical
RSX
CC compiler
RSX
AS assembler
RT-11 CC compiler
RT-11 AS assembler
Turn CCL to chain call
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.
[[
C Compiler and Library]]
Page A-10
Getting on the Air with Decus C
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. The RBUILD command file cannot be
run directly, however.
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 FLX format, create the
various accounts and copy account [5,1] from the magtape to
account [.command]:
$
create/dir
disk:[decusc]
The VMS
follows:
disk:[decusc]
$
set
default
V2.0 file system supports relative directory access as
[-.subdirectory]
means "move to the parent of the current directory and then down
to the indicated subdirectory." This is analogous to the Unix
syntax
[[
C Compiler and Library]]
Page A-11
Getting on the Air with Decus C
../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]
[5,3]
[5,4]
[5,5]
[5,6]
[5,7]
[.command]
[]
[.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]
Command files and documentation
.DOC files
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 copy [5,1]VRKIT.COM
from the magtape to this account:
$ set default [.command]
$ mount/foreign mta0:
$ 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 MTA0:
and execute (after eventual editing) VRKIT2.COM.
The 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
A short file explaining the process
This document
The backup command file used
A model restore command file
FILEnn.BCK
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.
[[
C Compiler and Library]]
Page A-12
Getting on the Air with Decus C
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 a temporary batch control file in your login
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
V3.0 takes about 90 minutes.
A.5.3
an unloaded Vax-11/782 running VMS
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 Compiler and Library]]
Page A-13
Getting on the Air with Decus C
C distribution, it would be prudent to use separate
the various components of the distribution.
disks
for
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 systems.
Instead, you should copy the necessary files to diskette as
follows:
o
Build
an
RT-11
system
containing file
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: logical device.
o
Initialize a second
SUPORT.OBJ to it.
diskette
and
copy
transfer
CLIB.OBJ and
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 quite short, using
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
[[
C Compiler and Library]]
Page A-14
Getting on the Air with Decus 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.
[[
C Compiler and Library]]
Page A-15
Getting on the Air with 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
$$mchk
isalpha
islower
isupper
isalnum
strcat
strncat
strncpy
$$ltoa
$$fopt
isalpha
isalnum
iscntrl
isdigit
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
Verify memory allocation pointers
Test for alphabetic argument
Test for lower-case alphabetic argument
Test for upper-case alphabetic argument
Test for alphanumeric argument
a string onto another
Concatenate
a string onto another, with Concatenate
Copy one string to another, with count
long to Ascii (any radix)
Convert
fopen/fwild options argument
Scan
Test for alphabetic argument
Test for alphanumeric argument
for control character argument
Test
Test for digit argument
isgraph
islower
isprint
Test for graphic argument
lower-case alphabetic argument
Test for printable argument
Test for
C Compiler and Library
Page B-2
Library Index
ispunct
isupper
isspace
$$fcsi
$$fpar
$$dtoa
ddtoa
atofd
$$ctim
$$c5ta
r50toa
fgetname
itoa
itoax
itoa8
toascii
isascii
$$ltoa
atoi8
ascr50
atod
atof
ctime
ctime
ctime
peek
ftime
ungetc
$$clfu
getw
putw
fget
fput
msize
zero
fill
abort
localtime
swabb
$$ctim
$$utim
ctime
$$abuf
$$flsh
fflush
localtime
swabi
copy
swabb
Test for punctuation argument
upper-case alphabetic argument
Test for
Test for whitespace argument
Parse file name argument for fopen/fwild
(RMS-11Parse file name argument for fopen/fwild
floating point to ASCII
Convert
floating point to ASCII -- dummy
Convert
-- dummy
Convert ASCII to floating point
$$rtim buffer to Ascii
Convert
Convert Radix-50 to Ascii
Convert Radix-50 to Ascii
Convert file name to Ascii
Convert integer to Ascii
to hexadecimal Ascii
Convert integer
integer to octal Ascii
Convert
Convert to 7-bit Ascii
Test for 7-bit Ascii
Convert long to Ascii (any radix)
integer
Convert Ascii octal number to
Convert Ascii to Radix-50
Convert Ascii to floating point
Convert Ascii to floating point
Convert time value to ascii
time buffer to ascii
asctime Convert
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
memory for i/o buffers
Allocate
Flush output buffers
Flush output buffers
Build time of day buffer
Byte swap an integer
a given number of bytes
Copy
Swap bytes in a buffer
call
callc
$$main
$$main
csv$
subroutine from C
Call (Fortran)
subroutine from C
Call (Fortran)
variables
C library global
C main program
environment
C program execution
C Compiler and Library
Page B-3
Library Index
$$init
error
exit
csv$
call
callc
$$qiow
wrapup
caller
calltr
brk
$$cl16
ctype
fill
iscntrl
getchar
index
strchr
inchr
rindex
strrchr
putc
$$putc
$$getc
isalloc
ctype
zero
clearerr
fclear
$$main
$$cl16
fclose
$$clfu
exit
exit
iov
$$gcmd
msg
strcmp
strncmp
$$ctim
strlen
time
tod
ftime
strcat
strncat
concat
envsave
C program initialization
Error exit from C programs
Normal exit from C programs
restore
C register save and
subroutine from C
Call (Fortran)
subroutine from C
Call (Fortran)
service
Call RSX executive
Dummy routine called on exit
name of profiled caller
Return
Trace path to the caller
pointer
Change top of memory
Close all I/O channels
type table
Character classification
of memory with a character
Fill a block
Test for control character argument
Get one character from a file
first instance of a character in a stFind the
first instance of a character in a stFind the
Find the index of a character in a string
last instance of a character in a stFind the
last instance of a character in a stFind the
Output one character to a file
(internal) 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
Flush
$$exst -- Exit status code
Exit with status code
I/O error codes
Parse command line
a message on the command terminal
Print
Compare strings
count
Compare strings, with
Compute day of week
string
Compute length of a
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
Save
iscntrl
gettty
setcc
fprintf
sprintf
argument
mode only)
Test for
Get
Trap
Formatted
Formatted
control character
control terminal name
Control/C (RSTS/E RT11
Conversion
Conversion
C Compiler and Library
Page B-4
Library Index
$$tens
$$rtim
$$scan
fscanf
scanf
sscanf
$$ctim
$$utim
atofd
atoi8
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
strncpy
strneq
$$main
profile
$$rtim
time
tod
ftime
localtime
$$ctim
$$main
$$narg
fspool
$$narg
floating point
Conversion table for
Date and time conversion
Formatted input conversion
Formatted input conversion
Formatted input conversion
Formatted input conversion
Ascii
Convert $$rtim buffer to
Unix time
Convert $$rtim buffer to
floating point -- dummyConvert ASCII to
number to integer
Convert Ascii octal
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
to another, with count
Copy one string
string equality, with count
Test
$$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
for RT11 startup
Define $$narg default
iov
sleep
delete
fmkdl
kbinr
I/O vector definition
Delay job a given number
Delete a named file
Mark file for deletion
read without waiting
Delimiter-free terminal
of seconds
C Compiler and Library
Page B-5
Library Index
kbin
isxdigit
isdigit
div$li
$$div2
wrapup
atofd
ddtoa
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
profile
error
exit
exit
iov
iov
profile
fclose
delete
$$clfu
getchar
the terminal without
Test for hexadecimal
Test for
Long
Unsigned
exit
to floating point -point to ASCII --
delimiters
Read from
digit
digit argument
division and modulus
division and modulus
Dummy routine called on
dummy
Convert ASCII
dummy
Convert floating
Dump memory or registers
EIS emulator
Execute a RSTS EMT
Execute a RT11 EMT after loading r0
$$vms -- Test if VMS emulation
EIS emulator
Test for end of file
$$stnd -- Stack end point
queue
Add entries to the RT11
$$prnl -- Profile entry per line
C program execution environment
Test strings for equality
Test string equality, with count
programs
Error exit from C
Test for file error
Test for file error
I/O error codes
Clear open file's error flags
Clear open file's error flags
Print library error message
$$ferr -- File error value
Execute a RSTS EMT
loading r0
Execute a RT11 EMT after
Execute non-local goto
longjmp -- execute non-local goto
C program execution environment
Call RSX executive service
$$exst -- Exit status code
Exit with status code
routine called on exit
Dummy
profile data after exit
Print
Error exit from C programs
Normal exit from C programs
$$exst -- Exit status code
$$ferr -- File error value
$$ferr -- File error value
-- Profile output file
$$pfil
Close an open file
Delete a named file
record before closing file
Flush last
one character from a file
Get
getw
fopen
putw
puts
putc
binary integer from
Open or reopen
a binary integer to
Output a string to
one character to
a
a
a
a
a
file
file
file
file
file
Input a
Output
Output
C Compiler and Library
Page B-6
Library Index
ungetc
fgets
feof
frec
$$putc
ferr
ferror
fmkdl
rewind
ftty
isatty
$$fcsi
$$fpar
fgetname
$$fopa
fwild
fseek
ftell
fspool
clearerr
fclear
fill
maxmin
maxmin
maxmin
maxmin
index
strchr
inchr
rindex
strrchr
index
strchr
$$main
clearerr
fclear
iov
fabs
$$tens
atod
atof
atofd
fps
$$dtoa
ddtoa
$$fadd
$$fmul
$$fsav
$$clfu
back onto an input file
Push
Read a string from a file
Test for end of file
if record-oriented file
Test
one character to a file (internal)
Output
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
fopen/fwild (RMS-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
open file's error flags
Clear
open file's error flags
Clear
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
routines
Floating-point support
closing file
Flush last record before
$$flsh
fflush
$$fcsi
$$fpar
$$fopt
Flush output buffers
Flush output buffers
name argument for fopen/fwild
Parse file
name argument for fopen/fwild (RMParse file
argument
Scan fopen/fwild options
C Compiler and Library
Page B-7
Library Index
fprintf
sprintf
$$scan
fscanf
scanf
sscanf
$$prnt
printf
call
callc
fps
malloc
envsave
envsave
irand
rand
$$get
$$getc
gettty
ftell
fileno
flun
getchar
msize
$$gsa
copy
sleep
$$main
unwind
setjmp
isgraph
traps
itoax
isxdigit
$$cl16
iov
screen
iov
iov
$$abuf
$$falo
$$main
$$main
$$main
$$main
ftty
isatty
isalloc
frec
Formatted Conversion
Formatted Conversion
conversion
Formatted input
conversion
Formatted input
conversion
Formatted input
conversion
Formatted input
Formatted output
Formatted output
C
Call (Fortran) subroutine from
C
Call (Fortran) subroutine from
point status (FPS)
Set floating
Allocate and free memory
Save and restore function context
Multi-level function return
Random number generator
Random number generator
Get a record (internal)
(internal)
Get characters
name
Get control terminal
subsequent seek
Get file position for
Get logical unit number
Get logical unit number
file
Get one character from a
block
Get size of a memory
RMS Get-space routine
Copy a given number of bytes
Delay job a given number of seconds
C library global variables
Execute non-local goto
-- execute non-local goto
longjmp
Test for graphic argument
Operating system trap handlers
Convert integer to hexadecimal Ascii
Test for hexadecimal digit
Close all I/O channels
I/O error codes
Screen I/O primitives
flags and vectors
I/O system internal
I/O vector definition
Allocate memory for i/o buffers
Allocate memory for i/o subroutines
-- Operating system id.
$$opsy
$$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
wdleng
inchr
$$init
calloc
getw
Machine
Find the
C program
Allocate and
from a file
a string
independent sizeof(int)
index of a character in
initialization
initialize memory
Input a binary integer
C Compiler and Library
Page B-8
Library Index
fget
fread
$$scan
fscanf
scanf
sscanf
ungetc
index
strchr
rindex
strrchr
swabi
atoi8
atoi
asl$li
asr$u
getw
itoa
putw
itoax
itoa8
iov
$$get
$$getc
$$putc
$$main
ftty
isatty
sleep
rindex
strrchr
$$clfu
strlen
perror
$$main
profile
$$gcmd
gets
$$link
rtemt
peek
$$put
$$flun
fileno
flun
div$li
atol
mul$l
asl$l
Input a binary record
Input a record
Formatted input conversion
Formatted input conversion
Formatted input conversion
Formatted input conversion
Push back onto an input file
in a strFind the first instance of a character
in a strFind the first instance of a character
in a striFind the last instance of a character
in a striFind the last instance of a character
Byte swap an integer
Ascii octal number to integer
Convert
Convert string to integer
Shift long by integer
shift unsigned by integer
right
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 one
$$tick -- Clock interrupt rate
Test if a file is a terminal
Test if a file is a terminal
seconds
Delay job a given number of
character in aFind the last instance of a
character in aFind the last instance of a
closing file
Flush last record before
Compute length of a string
Print library error message
C library global variables
-- Profile entry per line
$$prnl
Parse command line
Read a line from stdin
Print memory list
a RT11 EMT after loading r0
Execute
Peek at a location in RSTS/E
Write a logical record
Allocate a logical unit
Get logical unit number
Get logical unit number
modulus
Long division and
Convert string to long
Multiply long by long
shift long by long
asl$li
mul$l
asl$l
$$ltoa
setjmp
Shift
Multiply
shift
radix)
Convert
-- save state for
long by
long by
long by
long to
longjmp
integer
long
long
Ascii (any
setjmp
C Compiler and Library
Page B-9
Library Index
setjmp
tolower
islower
toupper
wdleng
$$main
fmkdl
maxmin
maxmin
alloc
malloc
calloc
isalloc
zero
realloc
$$mchk
msize
$$abuf
$$falo
sbrk
$$link
memdmp
brk
fill
perror
msg
maxmin
maxmin
setcc
trace
div$li
$$div2
envsave
mul$l
$$fmul
$$main
gettty
$$fcsi
$$fpar
caller
fgetname
delete
$$narg
unwind
setjmp
exit
$$prmt
fileno
flun
non-local goto
Convert upper-case to
argument
Test for
Convert
sizeof(int)
C
longjmp -- execute
lower-case
lower-case alphabetic
lower-case to upper-case
Machine independent
main program
Mark file for deletion
Find maximum of two numbers
numbers
Find maximum of two unsigned
Allocate memory
Allocate and free memory
and initialize memory
Allocate
points to allocated memory Check if a pointer
Clear a block of memory
Reallocate memory
pointers
Verify memory allocation
Get size of a memory block
Allocate memory for i/o buffers
subroutines
Allocate memory for i/o
system
Allocate memory from operating
Print memory list
Dump memory or registers
Change top of memory pointer
Fill a block of memory with a character
Print library error message
terminal
Print a message on the command
Find minimum of two numbers
numbers
Find minimum of two unsigned
(RSTS/E RT11 mode only) Trap Control/C
Profile support module (with trace)
Long division and modulus
Unsigned division and modulus
return
Multi-level function
Multiply long by long
Floating-point multiply/divide
-- RSX-11M task name
$$task
Get control terminal name
fopen/fwild Parse file name argument for
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
irand
rand
copy
sleep
atoi8
Random
Random
Copy a given
Delay job a given
Convert Ascii octal
number
number
number
number
number
generator
generator
of bytes
of seconds
to integer
C Compiler and Library
Page B-10
Library Index
maxmin
maxmin
maxmin
maxmin
itoa8
atoi8
getchar
putc
$$putc
strncpy
setcc
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
$$fpar
calltr
peek
profile
profile
$$main
Find maximum of two
of two unsigned
Find minimum of two
of two unsigned
Convert integer to
Convert Ascii
file
Get
Output
(internal)
Output
with count
Copy
(RSTS/E RT11 mode
Push back
Concatenate a string
Concatenate a string
numbers
numbers
Find maximum
numbers
numbers
Find minimum
octal Ascii
octal number to integer
one character from a
one character to a file
one character to a file
one string to another,
only)
Trap Control/C
onto an input file
onto another
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
for fopen/fwild (RMS-11)arse file name argument
Trace path to the caller
RSTS/E
Peek at a location in
-- Profile entry per line
$$prnl
file
$$pfil -- Profile output
$$stnd -- Stack end point
$$tens
atod
atof
atofd
fps
table for
Ascii to
Ascii to
ASCII to
Set
floating
floating
floating
floating
floating
point
Conversion
point
Convert
point
Convert
point -- dummy
Convert
point status (FPS)
C Compiler and Library
Page B-11
Library Index
$$dtoa
ddtoa
brk
$$prmt
fseek
isalloc
$$mchk
isalloc
$$main
ftell
screen
msg
perror
$$link
profile
fspool
isprint
profile
$$main
profile
profile
trace
profile
caller
$$main
csv$
$$init
abort
error
exit
$$prmt
ispunct
ungetc
qset
fspool
rtemt
$$svr1
$$ltoa
ascr50
$$c5ta
r50toa
irand
rand
$$main
rewind
gets
fgets
kbin
kbinr
Convert floating point to ASCII
Convert floating point to ASCII -- dummy
Change top of memory pointer
Null prompt pointer
Reposition file pointer (seek)
allocated meCheck if a pointer points to
memory allocation pointers
Verify
memoCheck if a pointer points to allocated
(Professional)
$$pos -- Test if P/OS
seek
Get file position for subsequent
Screen I/O primitives
command terminal
Print a message on the
message
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)
$$pos
$$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
Add
file to default print queue
Spool
EMT after loading r0
Execute a RT11
Save registers r1-r5 on the stack
long to Ascii (any radix)
Convert
Convert Ascii to Radix-50
Convert Radix-50 to Ascii
Convert Radix-50 to Ascii
Random number generator
Random number generator
-- Clock interrupt rate
$$tick
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
fwrite
fput
Input a
Input a binary
Output a
Output a binary
Reallocate memory
record
record
record
record
C Compiler and Library
Page B-12
Library Index
$$put
$$get
$$clfu
frec
csv$
memdmp
$$svr1
fopen
$$fopa
fseek
csv$
envsave
caller
envsave
rewind
asr$u
$$gsa
$$fpar
$$gsa
wrapup
$$fsav
rstsys
$$main
$$main
peek
setcc
$$qiow
$$main
$$main
$$main
$$fopa
rtemt
setcc
qset
$$narg
$$ctim
$$utim
envsave
$$svr1
csv$
setjmp
$$fopt
$$main
screen
sleep
ftell
fseek
$$qiow
fps
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
Save and
caller
Multi-level function
re-reading
integer
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
restore function context
Return name of profiled
return
Rewind a file for
right shift unsigned by
RMS Get-space routine
for fopen/fwild (RParse file name argument
RMS Get-space routine
Dummy routine called on exit
support routines
Floating-point
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
Open
r0
Execute a RT11 EMT after loading
Control/C (RSTS/E RT11 mode only)
Trap
Add entries to the RT11 queue
$$narg default for RT11 startup
Define
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
for subsequent seek
Get file position
file pointer (seek)
Reposition
Call RSX executive service
status (FPS)
Set floating point
setjmp
asl$li
asl$l
asr$u
msize
longjmp
integer
setjmp -- save state for
Shift long by integer
shift long by long
right shift unsigned by
Get size of a memory block
C Compiler and Library
Page B-13
Library Index
wdleng
fspool
$$main
$$svr1
$$narg
setjmp
fps
exit
exit
gets
$$main
cpystr
strlen
strcpy
index
strchr
inchr
rindex
strrchr
strneq
fgets
strcat
strncat
puts
strncpy
atoi
atol
strcmp
concat
streq
strncmp
call
callc
$$falo
ftell
$$fadd
trace
$$fsav
swabb
swabi
sbrk
$$main
iov
traps
ctype
$$tens
$$main
$$main
msg
Machine independent sizeof(int)
print queue
Spool file to default
$$stnd -- Stack end point
r1-r5 on the stack
Save registers
default for RT11 startup
Define $$narg
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
of a character in a stFind the first instance
of a character in a stFind the first instance
of a character in a string
Find the index
of a character in a strFind the last instance
of a character in a strFind the last instance
count
Test string equality, with
Read a string from a file
Concatenate a string onto another
with counConcatenate a string onto another,
Output a string to a file
count
Copy one string to another, with
Convert string to integer
Convert string to long
Compare strings
Concatenate strings
Test strings for equality
Compare strings, with count
Call (Fortran) subroutine from C
Call (Fortran) subroutine from C
memory for i/o subroutines
Allocate
Get file position for subsequent seek
add and subtract
Floating-point
trace)
Profile support module (with
Floating-point support routines
Swap bytes in a buffer
Byte swap an integer
memory from operating system
Allocate
$$opsy -- Operating system id.
and vectors
I/O system internal flags
Operating system trap handlers
classification type table
Character
Conversion table for floating point
name
$$task -- RSX-11M task
$$task -- RSX-11M task name
on the command terminal Print a message
ftty
isatty
gettty
kbinr
kbin
Test if a file is a
Test if a file is a
Get control
waiting Delimiter-free
delimiterRead from the
terminal
terminal
terminal name
terminal read without
terminal without
C Compiler and Library
Page B-14
Library Index
isascii
isalpha
isalnum
iscntrl
isdigit
feof
ferr
ferror
isgraph
isxdigit
islower
isprint
ispunct
isupper
isspace
$$main
$$main
$$main
ftty
isatty
frec
strneq
streq
$$main
$$utim
ctime
$$rtim
time
tod
ftime
localtime
ctime
brk
calltr
trace
setcc
abort
traps
maxmin
maxmin
maxmin
maxmin
ctype
$$main
$$main
$$main
$$flun
fileno
flun
Test for 7-bit Ascii
Test for alphabetic
Test for alphanumeric
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
argument
Test for whitespace
(Professional)$$pos -- Test if P/OS
$$rsts -- Test if RSTS/E
$$vms -- Test if VMS emulation
terminal
Test if a file is a
terminal
Test if a file is a
file
Test if record-oriented
with count
Test string equality,
equality
Test strings for
rate
$$tick -- Clock interrupt
$$rtim buffer to Unix time
Convert
asctime Convert time buffer to ascii
Date and time conversion
Compute time of day
Compute time of day
Compute time of day (augmented)
Build time of day buffer
Convert time value to ascii
Change top of memory pointer
Trace path to the caller
support module (with trace)
Profile
RT11 mode only)
Trap Control/C (RSTS/E
program with a BPT trap
Abort
Operating system trap handlers
Find maximum of two numbers
Find minimum of two numbers
Find maximum of two unsigned numbers
Find minimum of two unsigned numbers
classification type table
Character
-- RSX-11M default UIC
$$uic
UIC
$$uic -- RSX-11M default
Operating-system unique variables
Allocate a logical unit
Get logical unit number
Get logical unit number
argument
argument
character argument
$$utim
$$div2
asr$u
maxmin
maxmin
$$rtim buffer to
modulus
right shift
Find maximum of two
Find minimum of two
Unix time
Convert
Unsigned division and
unsigned by integer
unsigned numbers
unsigned numbers
C Compiler and Library
Page B-15
Library Index
toupper
isupper
tolower
iov
abs
fabs
ctime
$$main
$$main
iov
iov
$$mchk
$$main
$$main
kbinr
$$ctim
isspace
kbin
kbinr
$$put
Convert lower-case to upper-case
argument
Test for upper-case alphabetic
Convert upper-case to lower-case
$$ferr -- File error value
Absolute value
Floating absolute value
Convert time value to ascii
C library global variables
unique variablesOperating-system
I/O vector definition
internal flags and vectors
I/O system
pointers
Verify memory allocation
$$vms -- Test if VMS emulation
emulation
$$vms -- Test if VMS
terminal read without waiting
Delimiter-free
Compute day of week
Test for whitespace argument
from the terminal without delimiters
Read
terminal read without waiDelimiter-free
Write a logical record
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement