PREFACE(0)
NAME
preface - purpose, organization, conventions, related manuals
PURPOSE OF THE MANUAL
This manual describes the programming features of the DG/UX
system. It provides neither a general overview of the them nor
details of their implementation. It is intended for experienced
programmers and advanced users. See MANUAL SET, below, for
references to other manuals in the DG/UX System manual set.
ENTRY NUMBERING
This manual is divided into two volumes. Volume 1 contains
chapters 1 and 2 and Volume 2 contains chapters 3 through 6.
Each chapter is made up of entries. An entry is a set of pages
that describe a command (or a set of related commands).
Entries in these two volumes are identified by a name and a
number. An entry's name is followed by a number, which
designates what chapter the entry is in. A letter may be
appended to an entry number; the letter indicates that the entry
is a member of a special set of commands (e.g., all C runtimes
described in chapter 3 have the suffix (3C)).
On each page in this manual, the entry name and number appear at
the top left or right as headers to assist you in finding entries
quickly. Entries within a chapter are ordered alphabetically by
entry name. Page numbering is applied within each entry (i.e.,
each entry begins on a page numbered 1), and appears at the
bottom center of each page.
Entries in these volumes are of the form name(0), name(2),
name(3x), (where x is C, S, M, X, or N, name(4), name(5), or
name(6).
The name(0) entries are either part of the front matter of the
manual (preface, table of contents, etc.) or are appendices.
The name(2) entries describe system calls; they can be
incorporated into application programs.
The name(3x) entries include an introduction (3) and six kinds of
runtime libraries: C (3C), C I/O (3S), math (3M), special (3X),
and networking (3N).
The name(4) entries describe file formats that are used in the
system.
DG/UX 4.00 Page 1
Licensed material--property of copyright holder(s)
PREFACE(0)
The name(5) entries contain miscellaneous information, such as an
ASCII chart and a representative file system hierarchy.
The name(6) entries describe networking protocols.
The manuals' numbering system is an important part of the online
documentation system; see ONLINE INFORMATION, below, and man(1)
in the User's Reference for the DG/UX (Trademark) System.
References to manual entries not of these forms refer to entries
in the User's Reference for the DG/UX (Trademark) System (entry
suffixes 1) and System Manager's Reference for the DG/UX
(Trademark) System (entry suffixes 1M, 7, 8).
ORGANIZATION
A descriptive Table of Contents and a Permuted Index appear just
after this preface.
Volume 1 is divided into two chapters:
1. Commands
2. System Calls
Volume 2 is divided into 4 chapters:
3. Subroutines and Libraries
3 & 3C. C Library
3S. C Standard I/O Library
3M. Math Library
3X. Other Libraries
3N. Internet Network Library
4. File Formats
5. Miscellany
6. Networking Protocol
Chapter 2 (System Calls) describes the entries into the
system kernel, including the C language interface.
Chapter 3 (Subroutines and Libraries) describes the
available subroutines and tells how to provide for their
inclusion in programs that you write. The binary versions
of these subroutines reside in various system libraries in
the directories /lib and /usr/lib. See intro(3) for
descriptions of these libraries.
Chapter 4 (File Formats) documents the structure of
particular kinds of files. For example, the format of the
DG/UX 4.00 Page 2
Licensed material--property of copyright holder(s)
PREFACE(0)
output of the link editor is given in a.out(4). In general,
the C language struct declarations corresponding to these
formats can be found in the directories /usr/include and
/usr/include/sys.
Chapter 5 (Miscellany) contains a variety of things,
including descriptions of character sets, macro packages,
etc.
Chapter 6 (Networking Protocol) describes the network
facility for communicating between processes on the same
system.
Each chapter consists of a number of independent entries,
each beginning at the top of a page. The name of the entry
appears in the upper corners of the page, and entries within
chapters appear in alphabetical order. An intro() entry
begins each chapter.
Note: Finding What You're Looking For
Some entries may describe several routines or commands. In
those cases, the entry only appears once, under its "major"
name. For example, getgrent, getgrgid, getgrnam, setgrent,
endgrent, and fgetgrent all appear under the entry
getgrent(3C). If you need information about a routine, but
you don't know the "major" name under which it's listed, you
can find it by looking it up as a keyword in the Permuted
Index. Every routine has its own entry there. (See Using
the Permuted Index, below, if you don't know how to use a
key-word-in-context index).
ENTRY FORMAT
All entries are based on a common format. Some entries may not
have all of the parts listed below.
NAME gives the name(s) of the routine(s) described in the
entry and briefly states its purpose.
SYNTAX shows how the routine or command is used in a program
(or on a command line, if appropriate).
DESCRIPTION discusses the subject at hand, describing
effects and listing options.
EXAMPLES gives examples of how to use the command and/or
shows one or two interesting things that it can do.
FILES lists the files that are used by the program.
DG/UX 4.00 Page 3
Licensed material--property of copyright holder(s)
PREFACE(0)
SEE ALSO gives pointers to other entries and/or other
manuals to consult on the subject.
DIAGNOSTICS discusses the diagnostic information that may be
produced. However, error messages that (a) are part of the
program and (b) are deemed "self-explanatory" are not
listed.
WARNINGS and CAVEATS point out potential pitfalls.
BUGS tells about known problems or "deficiencies."
Occasionally a possible fix is suggested.
SYNTAX CONVENTIONS
We use the following notation conventions to describe syntax:
Element Meaning
bold string A literal to be typed just as it appears
roman string A place holder representing a literal or other
value that you supply
[ ] Delimiters for an optional argument
... Optional repetition of the preceding argument
EXAMPLE CONVENTIONS
We use the following notation conventions in examples:
Element Meaning
$ The standard shell primary prompt (indicating the
shell is ready to accept command input)
> The DG/UX secondary prompt (indicating the shell
needs more input to complete a command)
% The C shell primary prompt
[ ] Literal brackets to be typed exactly as they
appear
{ } Literal braces to be typed exactly as they appear
DG/UX 4.00 Page 4
Licensed material--property of copyright holder(s)
PREFACE(0)
WARNING
Many arguments to commands begin with a minus (-) or plus (+)
sign. Never create filenames that begin with those symbols.
Files named that way will cause at least an "illegal option"
error when they're put in a command line as arguments. The
command line parser may think that you're giving it a switch,
rather than a filename.
ONLINE INFORMATION
All of the entries in this manual, the Programmer's Reference for
the DG/UX (Trademark) System, and the System Manager's Reference
for the DG/UX System are supplied in machine-readable form on the
release tape. Whether they are actually online depends on your
system manager. See man(1) in the User's Reference for the DG/UX
(Trademark) for instructions.
USING THE PERMUTED INDEX
There is a special kind of index used in the reference manuals.
The keyword-in-context, or permuted, index lists each entry in
the manual under a number of keywords. The keywords are
extracted from a line of information about the entry, and always
include:
1. The entry's name, followed by a colon (If the entry does not
share a name with one of the routines or commands discussed
under it). If several commands or routines are being
described, only the last one will be followed by a colon; the
others will be followed by a comma. (For ctime(3C), the
names included are ctime, localtime, gmtime, asctime, and
tzset).
2. Words extracted from a concise phrase that tells about the
entry. The phrase used is the same one listed under the NAME
part of the entry; it also appears as the entry's description
in the Table of Contents. The phrase for ctime(3C) is
convert date and time to string
The lines of information are permuted circularly in creating
index entries. That means that when you find your keyword in the
index, it may be in the middle of the line of information. You
read the line to the right as far as you can, then skip back to
the beginning of the line (if necessary to pick up the rest of
the information. If a slash (/) appears in the line, it means
that there wasn't room to put all of the information on the line;
some of it was truncated.
DG/UX 4.00 Page 5
Licensed material--property of copyright holder(s)
PREFACE(0)
Example
To look up something in the index, first pick a keyword. Let's
say that you're looking for a subroutine that will return the
Greenwich Meridian Time. Take "time" as your keyword. Then
trace down the margin of space that runs down the center of the
index. All index lines are alphabetized by the word that appears
just to the right of that centerline of space.
You will find several lines that have "time" in that position.
All that remains is for you to read those lines and pick the one
that sounds like the one you want. In this case, the line would
look like this:
ctime, ..., tzset: convert date and time to string
Trace that line to the right margin, and there you will see the
name of the manual entry that has the information you want, in
this case ctime(3C).
If you had chosen "GMT" as your keyword, you may have recognized
that gmtime sounded about right.
In case of frustration
If you can't find an entry for your keyword, try another keyword.
It's possible that some entries have keywords that you wouldn't
have picked as first choice.
MANUAL SET
These books make up the manual set for the DG/UX System.
User's Reference for the DG/UX (Trademark) System (093-701007).
For all users. Contains one chapter. Commands and
Application Programs lists everything that can be invoked
from the command line. The Introduction provides an
overview of all of the commands and application programs.
Programmer's Reference for the DG/UX (Trademark) System (Volume
1) (093-701041). For programmers and advanced users. Lists
programming features of the system, including commands and
system calls.
Programmer's Reference for the DG/UX (Trademark) System (Volume
2) (093-701042). For programmers and advanced users. Lists
programming features of the system, including runtime
libraries, file formats, and networking protocols.
DG/UX 4.00 Page 6
Licensed material--property of copyright holder(s)
PREFACE(0)
System Manager's Reference for the DG/UX (Trademark) System
(093-701008). For administrators and systems programmers.
Contains commands and application programs that report
system status in detail, maintain the system resources, and
run system accounting procedures. Also contains booting and
maintenance procedures, and special files that refer to
hardware peripherals and system device drivers.
RELATED MANUALS
Entries in this manual refer to the following manuals:
AOS/VS Link and Library File Editor User's Guide (093-000245).
AOS/VS Macroassembler Reference Manual (093-000242).
AOS/VS Pascal Reference Manual (093-000290).
C Language Reference and Runtime Manual (093-000204).
Data General/Graphics Interface Programmer's Reference Manual
(093-701020).
Data General/Graphics Toolkit Programmer's Reference Manual
(093-701021).
FORTRAN 77 Reference Manual (093-000162).
Principles of Operation: 32-Bit ECLIPSE Systems (014-000704).
Using DG/VIEW (069-000130).
DG/UX 4.00 Page 7
Licensed material--property of copyright holder(s)