V_6.0ref Man_Jun86 V 6.0ref Man Jun86

V_6.0refMan_Jun86 V_6.0refMan_Jun86

User Manual: V_6.0refMan_Jun86

Open the PDF directly: View PDF .
Page Count: 326

Download
Open PDF In Browser	View PDF

V·System 6.0 Reference Manual

Distributed Systems Group
David R. Cheriton and Keith A. Lantz. Principal Inv~tigators
Computer Systems Laboratory
Deparanents of Computer Science and Electrical Engineering
Stanford University

20 June 1986

Hi

Preface
The following are a list of some of the major changes evident in Version 6.0 as compared to Version 5.0:
• General changes:
o Support for Sun2lS0's, Sun..3's and VaxStation-Irs.
o Better documenltation: as you can see...
• Lots of new commands. including:
o the C program development environment, including ccS8, 1 de8, and bu 11 d, an enhanced
version ofmaka
o

draw has been completely redone, including Postscript support

o

the Revision COllltrol System

o xli sp, a variant ofUsp
o 'The family ofTeX document compilers, including tax and 1 atax (sorry, no sources)
• New or changed services:
o Global authentircation scnices: Users now authenticate themselves once and need no longer
authenticate each "session" independently. This is implemented by a combination of a global
authentication server and V-to-UNIX "correspondence tables" maintained by the V servers
running under UNIX.
o Decentralized object naming: Local name servers have been eliminated in favor of each manager
maintaining the name space of the objccts it manages. Objccts are located with group [PC.
e Group IPC: Logically. messages arc now sent to groups of processes, rather than to individual

.proccsscs. ("Singleton" groups arc. in fact. special cased.) This pennits a sender to send one copy
of a message, but have it delivered to multiple recipients, in response to which multiple rcpHes
may (and can) be received.

.) "RAM disk": A V-storage-scrver-compatible server whose files arc stored in main memory.
Useful for temporary files and the like.
This reference manual attempts to be as faithful to the indicated release of the system as possible.
Unfortunately. there are almost certainly many errors - most frequently errors of omission. rlne typical
solution to this problem is to read the source code. but this too has its problems. The V-System is the product
of a r~search effort and is constantly undergoing revision. It has not always been possible to keep released
and experimental versions sUictly separated. Often. the source will include conditionally compiled code, or
dcclarnlions fhr constant'i alild dala types t11at are not fully supported in the released version of the system.
'Illerefore. programmers should be wary of using teatures found in the code that are not documented in this
manual. In brief:
W""';",.· Any
advisory.

pan of the V-System may changc without notice. As a result. this document should be regarded strictly as

Notes for installing the Y-System are to be found in Appendix C.
Contributing authors include Lance M. Rcrc. Eric 1. Berglund. Per Rothner. Kenneth P. Brooks, David
R. Chc!riton. Stephen E. Deering. J. Craig Dunwoody. Judy L. Edighoffer. Ross S. Finlayson, Cary Gray,
Bruce L. Hitson, David R. Kaelbling. Keith A. Lanu.. TimotilY P. Mann. rl110mas Maslen. Robert 1. Nagler,

V·Systelll 6.0 RCrt'ft'ncc Manual

16Junc 1986

William I. Nowicki, Joseph Pallas, Paul J. Roy, Jay Schuster, Michael Stumm, Marvin M. Theimer,
Christopher Zuleeg. and Willy Zwaenepoel.
The following arc trademarks of Digital Equipment Corporation: DEC, DECSystem-20, Tops-20, Unibus.
VAX, VAxStation. VMS, vr-100, and MicroVAX.
Ethernet is a trademark of Xerox Corporation.
SlDl Workstation is a trademark of Sun Microsystems Inc.
UNIX is a trademark of AT&T Bell Laboratories.
V-System is a trademark QfLeland Stanford Junior University.

V·Syst('ft16.0 Reference Manual

16 June 1986

,

Table of Contents
Preface .'
1. Introduction

1.1. The Hardware Environment
1.2. The User Model
1.3.. The System Model
1.4. The Application Model
1.5. Outline

iii
1·1

1-1
1-1
1-2
1-4

1-7

Part I. Using V'
2. User Interface Overview

2.1. The User Interface Architecture
2.2. Oetting Started
2.3. VOl'S Conventions ."
2.4. Workstation ~fanagement
2.5. Line Editing Faci1iti(~
2.6. Paged Output Mode
2.7. Sending Mouse Events to Text-:oriented Applications
2.8. Emulating the Mouse with the Keyboard
2.9. STS Conventions
3. Using the V executive

3.1. Introduction
3.2. Naming
3.3. Logging [n and Out
3.4. Remote Program Execution on a Unix Server
3.5. Remote Exccution on V Hosts
3.6. Facilities for Command Specification and Modification
3.7. Support for Heterogeneous Processors
4. Command Summary

4.1. Workstation Comm2lnds
4.2. Commands on Non-V Hosts
5. am,aze: A Maze Game
6. checkers
7. bits: a bitmap and faInt editor

7.1. Command Input
7.2. Rasters
7.3. Changing Raster Siz1e
7.4. Bitmap I/O
7.5. Painting
7.6. Inverting a Raster
7.7. Raster Operations (BitBlt)

V-System 6.0 Reference Manual

2·1

2-1
2-4
2-6

2-7
2-10
2-11

2-11
2-12
2-13
3-1

3-1
3-1
3-2
3-3
3-4
3-4

3-7
4·1
4-1

4-9
5-1

6·1
7·1

7-1
7-1
7-1

7-2
7-2
7.. 2
7.. 2

17.June 19M

7.8. Reflection and Rotation
7.9. [Replace in table]
7.10. Making a Copy of the Screen,; CURRENTLY NON-WORKING
7.11. Fonts
7.12. Sample Texts
7.13. Printing a Raster
7.14. Bugs and Problems
8. build: Maintaingroups of dependent programs

7-2
7-2
7-2
7-3
7-3
7-4
7-4
8·1

8-1
8-1
8-1

8.1. Macros
8.2. Including other dependency files
8.3. Conditional dependency rules
8.4. Search paths
8.5. Dependency patterns:··';
8.6. Suggestion
.. ~.; .
8.7. Bugs

8-r . ..

8-2
8-2
8-2

9. debug: The V Debugger

9-1

9.1. Synopsis
9.2. Description
9.3. Commands
9.4. Bugs

9-1
9-1
9-2 ..
9-6

10. draw: A Drawing Editor

10·1

10.1. Conceptual Model
10.2. Screen Layout
10.3. Generalstyle ofintcraction
10.4. Control Points and Sticky Points
10.5. Mouse Duttons
10.6. Verbs
10.7. Nouns
. 10.8. Attributes
10.9. Commands
10.10. groups
10.11. Inserting Draw pictures in text documents
10.12. Joumalling

10-1
10-1
10-3
10-3
10-4
10-4
10-5
10-6
10-7
10-9
10-9
10-11

11. hack: Exploring The Dungeons of Doom

11·1

11.1. Command format
11.2. Description
11.3. Options
11.4. Authors
11.5. Files
11.6. Bugs

11-1
11-1 .
11-2
11-2
11-2

ll-2

12. siledit: A Simple Illustrator

12.1. Dasic Operation
12.2. Commands.
12.3. Selecting Alternate Fonts
12.4. Generating Printed Copy

V'Syst"m 6.0 Reference Manual

'12·1
-·1

12-1
12-1
12-3
12-3

17 June 1986

vii

13. timeipc: A V Perfornlance Measu rement Tool

13.1. Types of Tests
13.2. Process Configurations
13.3. Input to limeipc
13.4. Output from limeipc
13.5. ~arnings and Precautions
14. ved: A Text Editor

13-1
13-3
13-4
13-5
13-6

''; I

14.1. Starting up
14.2. Some Notational Conventions
14.3. Special Commands
14.4. Cursor Motion
14.5. Paging and Scrolling
14.6. Special Characters
14.7. The Kill Buffer
14.8. Ba<;ic Editing Commands
14.9. Mark and Region
14.10. C-Spccific Editing Commands
14.11. Searching and Replacing
14.12. File Access
14.13. Windows and 8utT(~rs
14.14. lbe Mouse
14.15. lbe Right Hand and the Left
14.16. Ved Initialization
14.17. Crash Recovery
14.18. Some Hints on Usage

14-1

'"

-.1

15. xlisp: An Experimental Object Oriented Language

15.1. Introduction
15.2. A Note From the Alllthor
15.3. XLISP Command Loop
15.4. Break Command Loop
15.5. Data Types
15.6. lhe Evaluator
15.7. Lexical Conventions
15.8. ObjeCts
15.9. Symbols
15.10. Evaluation Functions
15.11. Symbol functions
15.12. Property List Functions
15.13. r.ist Functions
15.14. I >CStnictivc loist Functions
15.1.5. Predicate Function:s
15.16. Control Functions
15.17. Looping Functions
15.18. The Program Featlllre
15.19. Debugging and Error Handling
15.20. Arithmetic Functions
15.21. nitwisc I.ogical FUllctions
15.22. Relational Functions
15.2.3. String Functions

V'Syslcm 6.0 Reference Manual

13-1

14-1
14-1
14-2
14-2
14-3
14-3
14-3
14-3
14-4
14-4
14-5
14-5
14-6
14-7
14-8
14-9
14-12
14-13
15-1

15-1
15-1
15-2
15-2
15-2
15-3
15-3
15-4
15-6
15-6
15-7
15-8
15-9
15-11
15-12
15-13
15-14
15-15
15-16
15-17
15-18
15-18
15-19

17 Junr 1986

nU
15.24. Input/Output Functions
15.25. File 110 Functions
15.26. System Functions
16. Standalone Commands
16.1. Vload
16.2. Netwatch··. "
16.3. Postmortem
16.4. Diskdiag-

15-19
15-21
1S~21

16-1
16-1 l
16-4
16-6
16-6

.

Part II. V Programmi"ng'
.'

'(:;i

17. Program Environment Overview.
17.l. Groups of Functions .:
17.2. Header Files
18. Program Construction and.:~xecutlon
18.1. Writing the C Program '.
18.2. Compiling and Linking
18.3. Program Execution
"
18.4. Program Initialization ',.
19. The V·System Configuration. Database
19.1. Querying the Database:· ~,:
19.2. Currently Defined Keywords
19.3. Implementation
19.4. Usage
20. Control of Executives
21. Fields: Using an AVT as a Menti ~
21.1. Formats·
,I
2L2.1be l--ield Table as a Menu: Selecting an Action
21.3. Displaying Fields
21.4. User Input to Fields
21.5. An Example:
21.6. Limitations
22. Input and Output
22.1. Standard C I/O Routines
22.2. V I/O Conventions
22.3. V 110 Routines
22.4. Portable binary integer I/O
23. Intra-Team Locking
24. Memory Management" ,
24:1. Usc in multi-process teams
25. Naming
25.1. Current Context
25.2. Descriptor Manipulation
25.3. Local Names or Aliases
25.4. Naming Protocol Routines
25.5. Direct Name Cache Manipulation
11\

,,',

V'SyslC!m 6.0 R~rcrc.'ncc Manual

11-1
17-1 j
17-2
18·1
18-1
18-1.
18..2
18-3
19·1
19-1
19..1
19.-2
19-3
20·1
21·1
21-1
21-2
21-2
21-2
21-3
21-4
22·1
22-1

22-1
22-2
22-9
23·1
24·1
24'-2
25·1

25-1
25-1

25-2
25 .. 3
25-4

17 .June 1986

Ix

25.6. Environment Variables
26. Numeric and Mathematical Functions

26.1. Numeric Functions
26.2. Mathematical Functions
27. Processes and Interprocess Communication

27.1. Process-Related Kernel Operations
27.2. Logical Host-Related Functions' .. '
27.3. Other Process-Relat(:d Functions
27.4. Process Group Operations
27.5. Interprocess CommUlnicritioii"
28. Program Execution Functions

28.1. Program Execution "
28.2. Host Selection
28.3. Remote Exccutio~,~fUnix Commands
28.4. Other Program Executio~ I~outines
29. User Interface Funct,ions

29.1. Virtual Tenninal and View Management
29.2. ANSI Tenninal Emulation
29.3. Graphical Output
29.4. Graphical Input
29.5. Miscellaneous Functions
29.6. Example Program
29.7. Some Logistics
29.8. Rolling Your Own
30. Miscellaneous Functions

30.1. Time Manipulation Functions
30.2. Strings
30.3. Exception Handling Functions
30.4. Other Functions

2S-S
26·1

26·1
26-1
27·1

.27-1
"27-6
'21-7
27-8
"'27-9
~8·1

. ·28-1
i ;28-3
; .. ,28-3
'\ .-28-4
.29·1

29-1
29-2
29-5
, 29~12
29-14
29-15
29-17
29-17
30·1

30-1
30-2
30-4
30-4

Part UI. V Servers
31. Servers Overview

31.1. The 8asic Servers - hI Isolation
31.2. 'Inc System in Operation
31.3. Summary
32. Message Codes and Format Conventions

32.1. Message Fonnat Conventions
32.2. Byte-Ordering Considerations
32.3. Standard System Request Codes
32.4. Standard System Reply Codes
33. Tho

V-Syste~

1/0 Pr'otocol

33.1. CREATE INSTANCE
33.2. QUERY INSTANCE
33.3. CREATE DUPLEX INSTANCE
33.4. RELEASE INSTANCE
33.5. READ INSTANCE

V·System 6.0 Rdercncc Manual

31·1

31-1
31-5
31-8
32·1

32-1
32-1
32-2
32-2
33·1

33-3
33-4
33-4
33-5
33-6

17 June 1986

x

33.6. WRITE INSTANCE
33.7. SEf INSTANCE OWNER
33.8. SET BREAK PROCESS
33.9. SET PROMPI'
33.10. QUERY FILE and NQUERY FILE
33.11. MODIFY FILE and NMODIFY FILE
34. The V-System Naming Protocol

34.1. Overview
34.2. Character String Names
34.3. Contexts and Context Ids
34.4. Prefix Caching
~4.5. Static Context Identifiers
34.6. Generic Names and Group Names
34.7. Name Request Fonnat.
34.8. Name Lookup Algorithm
34.9. Standard CSNH Server Requests
34.10. Context Directories and Object Descriptors
35. Authentication and the Authentication Server

35.1. Authserver
35.2. User Numbers
35.3. Authentication Library Functions
35.4. Adding a New User
35.5. Authentication Database .
36. Device Server

36.1. Ethernet
36.2. Disk
36.3. Mouse: The Graphics Pointing DeviCe
36.4. Serial Line
36.5. Console
36.6. Framcbuffer
36.7. Null Devices
37. Exception Server
38. Exec Serve~
39. Internet Server

39.1. Running the Internet Server
39.2. Acccs.c;ing the Internet Server
39.3. DARPA Internet Protocol (lP)
39.4. DARPA Transmission Control Protocol (rCP)
39.5. Adding New Protoculs
39.6. Monitoring and Debug Facilities
40. Memory Server
41. Pipe Server
42. Team Server

42.1. Overview
42.2. Team I.oading
42.3. Team Tennination and Exit Status Values
42.4. Host Status

V·System 6.0 Ih,rercnce Manual

33-6
33-7
33-7
33-8

33-8
33-8
34·1

34-1
34-2
34-2

34-3
34-3
34-4
34-5
34-5
34-6
34-9
35·1

35-1
35-1
35-2
35-4
35-4
36-1

36-1
36-2
36-2
36-3
36-3
36-3

36-4
37·1
38·1
39·1

39-1
39-1
39-2
39-2

39-3
39-11
40-1
41·1
42·1

42-1
42-1
42-2
42-2

17 .Junt 1986

xi

42.S. Remote Execution
42.6. Round-Robin Scheduling
42.7. Exception Handling
42.8. Migration
43. Unix Server

42-2
42-3
42-3
42-3
43-1

43.1. Sessions
43.2. File Access
43.3. Program Execution,
43.4. File Descriptors
43.5. Debugging Se·ssions

43-1
43-2
43-3
43-3
43-4

44. Workstation Agents

44-1

44.1. Implementation of Workstation Agents
45. Simple 'Terminal Server

45.1. STS Line Editing Facilities
45.2. Hardware Environment
45.3. Remote Tenninal Server
46. Virtual Graphics Terminal Server

46.1. Current VOTS Versions
46.2. Avr Escape Sequences
46.3.~OTS Message Interface
46.4. Internal Organization
46.5. Debugging the VOTS

44-1
45-1

4S-1
4S-1
4S-2
46-1

46-1
46-1 .
46-3
46-4
46-S

Part IV. Appendices
Appendix A. A V-System Bibliography
Appendix B. C Programming Style

0.1. General Format
0.2. Names

R.3. Comments
8.4. Indenting
B.s. File Contents
0.6. Parentheses
B.7. Messages
Appendix C. Installatioln Notes

C.l. V-System Distribution Tapes
C.2. Binary Distribution Tape
C.3. Source Distributiol1l Tape
Appendix O. List of Library Functions defined in libc
Index

V'System 6.0 Rder('ncc M:mual

A-1
B-1

0-1
8-1
8-2
8-3

U-J
8-4

8-S
C-1
C-l
C-l
C-7
0-1
Index-1

17 June 1986

xii

'List of Figu res
Figure t-l: A workstation-based distributed system.
Figure 1-2: rille distributed V kernel.
Figure 1-3: Client interfaces to the V-System
Figure 1-4: Some possible applications.
Hgure 10-1: The Draw menu
Figure 10-2: An example figure
.
Figure 31-1: The V-System: A single workstation view.
Figure 31-2: VOTS process structure.
Figure 31-3: Loading a team.
Figure 31 -4: Handling an exception.
Figure 34-1: Decentralized Global Directory

V·System 6.0 Hdcrrnce Manual

1-2
1-3
1-4
1-6
10-2
10-10
31-2
31-4
31-6
31-7
34-2

.7 June 1986

"iii

List of T'ables
Table 2-1: Accelerators thr workstation management functions.
Table 2-2: Events that generate escape sequences.
Table 29-1: Encodings for graphical escape sequences.

V·S1~tCn1

6.0 RcCercll('e Manuol

2-10
2-12
29-4

17 JUlie 1986

1·1

-1I nt rod u ction
The V-System is a message-based distributed operating system designed primarily for high-performance
workstations connected by local networks. It permits the workstation to be treated as a multi-function
component of the distributed system. rather than solely as a intelligent terminal or personal computer.
Ultimately. it is intended to provide a general-purpose program execution environment similar to some
degree to UNIX. The programs are intended to interact with each other, and with programs running on
traditional timesharing systems. to produce an integrated distributed system.

1.1. The Hardware Environment
1be V-System is targeted for a hardware environment consisting of(sce Figure 1-1):
• powerful workstationsl with:
o a high-resolution (e.g. 1024 by 1024) raster display;
o a general-purpose 1 MIPS (or better) processor;
o 2 Mbytes or motre oflocal memory;
o a large (greater than 20 bits) virtual address space;
o a graphics input device, such as a mouse: and optionally,
o adist
which. typically. will be dedicated to a single u~r at a time;
• a fast (greater than 1 ~,1H7.) communications network that wil1link the works~1tions;
• a number of dedicatc~d processors providing printing, file storage. general computation support. and
other services; and
• access to time-sharing or special-purpose computers and to long-haul computer networks.
This release of the system runs on Sun and VaxStation workstations interconnected by either 3 or 10 Mb
Ethernet "Guest-lever' implementations are available for 4.2BSD and 4.38SD UNIX systems (with Stanford
enhancements).

1.2. The Use r Model
One of the most important functions for the workstation is to provide state-of-the-art user interface support.
rille workstation should function (1S a frolll elld to all available resourccs. whether lncal to the worksL1tion or
remote. To do so. tJ1C V-System adhercs to tJuee fundament,,1 principles:
1. '1111e interface to app~ication programs is (reasonably) independent of particular physical devices or
intervening networks.
2. The user is allowed to perform multiple tasks simultaneously.
3. Response to user interaction is fast
Adhering to these principles. the V-System supports a reasonably sophisticated "window system", Multiple
exccutives or shells may be run simultaneously. each of which may run one "pptication in the "foreground"
and any number in tJ1C "background" (a la the UN IX C-shell). Applications may nm local to thc workstation
or remote. r.:ach application may be associatcd with one or more scptlratc.,irlualtermillals, each of which may

V'S,stclIU 6.0 Rderence Manual

17 June 1986

IntrodlictioD

1-1

Cluster

.,

Network

User

Cluster

Cluster

Network

Network

User

User

User

USer --==-----.

User

t.=::cr--.

a.==...---_

Trunk
Network

Long-haul

Gateway

Network
Workstation
Printer Server
File Server
Timesharing System

14'igurc I-I: A workstation-based distributed system.

-be used to emulate either a vr-lOO terminal or-A 2-D "structured graphics" tenninal.

1.3. The System Model
The V-System adheres to the server model: rille world consists of a concetion of resources al'Cessible by

diellls l and managed by servl'rs. 1\ server dcfines the abstract reprcsentation of its rcsourcc(s) and the
operations on Ulis representatiun. A resuurce may only be "cccs.~d or manipulaled through its server.

Because servers are constructed with well-defined interfaces. Ule implementation demils of a resource are of
concern only to its server. Note that a server frequen~ly acts as a client when it accesses resources managed by
other servers. Thus. client and server are merely roles played by a process.
Clients and servers may be distributed throughout the (inter)network. By default. access to resources is
network transparent; a client may llCCCSS a remote resource with the same semantics as it accesses a local
resource. The result is an environment in which clients may communicate with servers without regard for the
1A client is a program requesting access to a resource, typically on behalf or a human

V-System 6.0 Reference Manual

US".
17 June 1986

The System Model

1-3

topology of the distributed system as a whole. However. we do not intend that a client cannot detenninc or
influence the location of a particular resource, rather that a transparent mechanism is available. Moreover. we
allow for clients and servers that were not written with network-transparent access in mind.
'
Architecturally. then. the V-System consists of a distributed kernel and a distributed set of server processes.
1.3.1. the Distributed ICernel

The distributed kernel consists of the collection of kernels resident on each participating machine (see
Figure 1-2). Each host kernel provides process management. interprocess communication. and low-level
device management faciliti'cs. All other operating system services are implemented as (collections) of
processes outside the kernel. A host kernel may be implemented at a base level (as on the SUN workstation) or
a guest/evel (as under 4.2BSD).

workstation

r

I11

-

-

-

---01

____

~

distributed

-1'--

kernel

kernel

----- -------1-1
kernel

kernel

II

1

interkernel protocol

IL ------- -

- - - -

______ ___.__________________
~

I

_~

__ I

~Arl.I~-----------------

r

Ethernet

Figure 1-2: The distributed V kernel.

The host kernels arc integrated via a low-overhead illler-kenlel protocol (lKP) that supports transparent
interproces.') communication between machincs. IKP is a reliable request-response protocol. intermediate in
complexity between conventional datagram and virtual circuit protocols.
1.3.2. Servers

Servers include:
virtual graphics lenninal server
Provides all terminal management functions. including Vr-lOO emulation and 2-D
graphics. One per workstation.
.
.
interne! server'

Provides network and transport level support for'traditional network nrchitcctures. nnmcly,
ARPA Inllernet and Xerox PUP. Higher-level protocols. such a~ TEI.NET. are provided as
separate packages that interface to the internet servcr.

V,SYS."nI 6.0 Reference Manual

17.June 1986

IntroducUOD

1-4

pipe server
Provides asynchronous, butTered communication facilities similar to UNIX pipes.
team server
Provides team creation, destruction, and management One per workstation.
exception server Fields process exceptions and dispatches them to registered handlers, such as debuggers.
One per workstation.
storage server
Provides file storage.
device server(s) Interfaces to a specific physical device, such as the console, mouse, serial1inc, or disk.

1.4. The Application Model
In general. it is just as easy to write applications to run under the V-System as it is to write applications to
run under any traditional operating system. such as UNIX. A standard program environment is defined, the
principal instance of which is the C program library. The C library provides runtime suppon for standard C
and UNIx-like library functions, including both byte-stream and block-I/O facilities (see Figure 1-3). In
effect. these libraries can be used to "hide" the underlying V-System kernel ~ thus facilitating the porting
of existing C programs.

User Programs

" .. '
C Library

Byte Stream Library

_JL_
1/0 Protocol

- - - - --T.-- - - - - Kernel Stub Library

" "
Kernel

Figure 1-3: Client interfaces to the V-System
On the other hand. an application programmer may choose to ~1ke advan~,ge of the enhanced £.1Cilities
provided by the V-System. These Ihcililic..'S fall in two major categories: user interaction and concurrent
programming. Additional advantage accrues from tJle fact that applications may be distributed across
multiple m~lchincs.

V'Systl'm 6.0 Reference Manual

17 June 1986

The ApplicatioD Model

1·5

1.4.1. User Interaction

With respect to user intc:raction, the V-System provides two principal enhancements over traditional
UNIx-like systems. First, a program may manipulate multiple vinual tenninals (windows) simultaneously.
Second. an application may employ structured graphics. Specifically. a graphical object can be defined in
terms of other objects, which can in turn be defined in terms of yet other objects. Thus. the VGTS supports
structured display files rather than the more common segmented display files. The resulting l'irtual graphics
tenninal protocol (VGTP) is a high-level object-oriented protocol that minimizes both the frequency of
communication between application and VGTS and the amount of data transmitted at anyone time.
1.4.2. Concurrent Programming

Using the distributed kernel well requires understanding the model of processes and messages that the
kernel provides, and how they ar~ intended to be used. Processes represent logical activities within the
application. 'Illey are intended to be sufficiently inexpensive to allow the use of multiple processes to achieve
the desired level of concurrency. In panicular. multiple processes may share the same address space or leam.
to facilitate fine-grain sharing of code and data. A team must be entirely contained on a single machine.
Processes can be dynamically created and destroyed. When a process is created, it is assigned a unique
process identifier that is used subsequently to specify that process.
Synchronous messagc-pas.~ing &1Cititates communication between processes that looks to the sender like a
procedure call. That is, the sender blocks until a reply to his request is received. Greater flexibility is
provided to the receiver to allow scheduling of requests. Messages are addressed to thc process identificr of
the recipient; thcre is no con1cept of a mailbox or port distinct from a process.
Messages arc short and fixed-length. To facilitate transfer of large amounts of data. a separate data transfer
facility is provided. Spccifically. a process can pass. in a message. access to an area in its team space. This
facility follows the procedure paradigm in being used primarily to access what are logically "cail-byrefcrencc" parameters. Sync:hronil.ation between the two processes involved in the data transfer is guaranteed
by vinue of thc fact that the recipient will not reply to the sender (and hence awaken him) until the transfer is
complete.
lbe lcernet also provides process groups and group interprocess communication. Each process can create,
join. and leave groups dymllmically. and can belong to many groups simultaneously. A message sent to a
group is delivered reliably tu the first group member lo reply, and unreliably to the rest Replies subsequent
to the first may be received (unreliably) by the sender. or ignored. at its option.
Procc.'SS scheduling is stric:tly priority~bascd. The effcctive priority of a process is the sum of its process
priority and its team priority. Team priorities are dynamically varied by the team server to provide timeslicing.
.
.
1.4.3. Classes of Applic:ations

From the previous discussion it should be apparent that applications may run local to the user's workstation
or on any other host accc~ssibic via the various network protocols. Ultimately. all applications must
communicate with the user via the virtual graphics tenninal server (VGTS) resident Oil the user's workst41tion.
The application inter'lacc to Ilhe VGTS is referred to as the virtual graphics tenninal protocol (VGTP).
111e VGTP is cons~'nt over all applications. However, some applications have no knowledge of the VGTP
and some applications arc running on machines that do not support the interproccss communication
mechanisms underlying the' VGTP. The following situations arise (see Figure 1-4, in which each intcrmachine arc is labeled with an example (presentation pr%col. transport protocol) pair):
• Application A runs (>n the workstation and communicat~ via the VGTP. Current examples includc text
editors, document illustrators, ~md design aids, many of which arc documented here.
• Application B runs on a machine that supports V kernel services, specifically, network-transparent

V·Syslem 6.0 Reference Manual

17 June 1986

Introductioa

1-6

VAX
VLSI Layout
Editor

SUN
Compiler

VGTP

VGTP

RTP/BSP

IKP

DEC·20

VAX

Local
Illustrator

Text Editor
Tetnet

TCP

Distributed
Game
Custom
NaP

Figure 1-4: Some possible applications.
interproccss communication via IKP. B communicates with the VGTS via the VGTP, as in the case of a
application A.
• Application C nms on a machine that docs not suppon IKP. but docs support a traditional network
architecture such as the (ntemet protocol filmily. In addition. a VOTP interface package is available
that encapsulates the VOTI' within the appropriate transport protocol. Similarly. a local agent fhr the
application. C: is created on the workstation to d(.'Capsulate the VOTP. 'l1lUs. the application may still
be written in tcnns of the VOTP and neither it nor the VOl'S have any knowledge that the other is
remote. Our VLSllayout editor, for example. can be run in this fashion under VAX/UNIX.
• Application D has no knowledge of the VOTS or the VOTP; it wishes to regard the workstation as just
another tcmlinal. The local agent, D: is "user TELNET" and pcrfonns the appropriate translations
between Tl!LNET and VGTP. Any pre-existing application that runs on a remote host falls into this

class.
• Application E is distributed hetween the workstltion and one or more other machincs. 'Ine local agent,
E: is responsible for representing the multitude to the VOTS. It must perfonn the appropriate set of
protocol conversions indicated above. In addition. it may wish to perfonn application-sp<.'Cific
functions. such as caching. In that case, the protocol used to communicate with the remote applications
may require more than simple transpon service. The Amaze game documented herein is an example of
such an application.

V-System 6.0 Rdercft(,c Manual

17 June 1986

The Application Model

1·7

1.5. Outline
The remainder of this manual c?nsists of four parts:
Part'l
Using V: describes the user interface and available application programs.
Part 2

V Programming: defines the V-System program environment in terms of the existing C
program Inbrary.

Part 3

V Servers:: defines the standard message fonnats, request and reply types, and protocols;
presents the various server-specific protocols: and gives some implementation details. .

Part 4

Appcndic(s: a V-System bibliography, notes on programming style, installation notes, and
a list of where the various library functions are defined. •

V·System 6.0 Reference Manual

17.June 1986

Part I:

Using V

2·1

-2-

User Interface Overview
This chapter presents an overview of what it is like for the user to interact with the V-System. Details of
tenninal emulation or graphics support' are not 'discussed, since that is best described by the programmer's
interface in Chapter 29. Rather. the basic stylistic conventions are presented. including an o\"erview of how
applications' actions are manifested to the user. Also included is a discussion of the the basic architecture of
the user interface. in the hop·e that it will enable the us~r to better understand the style of inte:-dction and the
facilities available to him. 111e user who is "in a hurry" to get started may skip this discussion, at least on first
readin& and begin with Section 2.2. The following chapter discusses command interpretation in some detail.

2.1. '·he User Interface Architecture
In a typical operating syst1em, the user is presented with the illusion of interacting with a single, unified
front end. often referred to as an "executive" or "shell". However, in contemporary workstation-based
systems., this front end actuaUy provides three basic levels of interaction:
"
l. dc,ice 110: Manipulation of input devices and generation of output on output devices.
2. command interpretation: Command (or argument) specification and response handling, and invocation
. of applications.

3. window management:

~,fanagement

of multiple simultaneous applications (in separate "windows").

Rather than combine these three levels of function in one module, the V-System distinguishes three
separate software components - respectively:
1. the workslation agent,
2. the execU/ive. and
3. the work.slalion ma"agi~r.
This separation was inspired by a desire to be able to configure each component independent of the others.
While this release of the V-System docs not reflect the ideal realil.ation of this separation. it nevertheless fits
the basic framework.
Womilf,: The workstation agcnt was originally refcrred to as the terminal agent. The two tenns arc used int.crchangc:lbly.

" 2.1.1. Workstation Agents

The workstation agent provides the lowest-level interface between the hardware and the rest of the system.
One of it') principal functions is to hide any idiosyncrasies of that hardware - through a virtual tenninal
interface.
2.1.1.1. Virtual Terminals

Rather than dealing with Ithe "raw" hardware. applications internet with a virtual tenninal. They request
input from a virtual keyboard or mouse, for example. and write output to a virtual stocc. Depending on the
"class" of reat tenninal (workstation) being emulated. the characteristics of the virtual input and output
devices may vary widely. In the simplest implementation. each workstltion agent emulatl.'S exactly one class
of real tenllinal: emulating a different tenninal requires a new workstation agent More sophi3ticated
workstation agents emulate multiple classes pf tenninals simultaneously. Note that the number of classes 0/
lenninGls emulated is independent of the number of virlual/enuillals being emulated at anyone time.

Using V

17 June 1986

User Interface Ove"iew

1·1

Historically, the most common clas.ct of terminal emulated has been the page-mode (character) tenninalexemplified by the DEC Vr-lOO. Even in this case. the workstation agent can be thought of as emulating
different types of terminals, corresponding to the various input and output modes provided by a Vf-lOOcharacter-at-a-time versus block transmission. local editing facilities, and the like. In general. the workstation
agent. through its virtual tenninals, provides a set of facilitics that might be refcrred to as "cooked lion ranging from character cc:hoing to line-editing to page-editing to graphics-editing. These facilities are enabled
and disabled on a virtual terminal by virtual terminal basis.
True to its name, a virtual terminal nced have no physical, real-world manifestation. In particular, it is
possible to write output to a virtual terminal without seeing that output displayed on the screen. Hence, any
application may run and change the store of any virtual tenninal at any time.
While it is common for multiple applications to be generating output simultaneously, it has historically (if
erroneously) been thought less desirable to permit the user to direct input to multiple applications
simultaneously. True to this historical bias, the V-System currently restricts input to one application at a time.
We refer to the application and associated virtual tenninals as being "selected" (for input). Selection for
input has no effect on the underlying application's ability to generate output. As with output, however, it is
possible to generate kcyboard input for a virtual tenninal without having the virtual tcnninal mapped to the
screen; users should be wary of the possible consequencesl
2.1.1.2. Views

In order for the user to actually see the output from or generate graphical input to a virtual terminal, the
virtual tcnninal must bc mapped to thc· screcn through a view. A view defines thc portion of the vinual
tenninars store that should be displayed, the area on thc screen in which it should be displayed, and the
transformation that should be applied whcn mapping thc store to the screcn. Using traditional graphics
tenninology, the store is referred to as the display file, the portion of the store is a Willdow, the area of the
screen is a viewport. and the transfonnation is a viewing Irans/onnalion. 2 Viewportsarc invariably rectangular, ...
although there l'i no conceptual reason for this to b.e the case.
Typically. an .lpplication will create one view of a virtual tcnninal at the same time it creates the virtual
terminal. Nevc,thelcss, vicws are main~1ined as entities distinct from virtual terminals because, in general,
each virtual terminal may have more than one view associated with it When using the YGTS. for example,
the same picture. maintained as one entity by the program. may appear in two separate view ports on the
screen. possibly with different viewing transformations. That is. a second view may look upon a different
portion of the virtual terminal's store from the first. or at a different magnification.
Note: UCCIUSC a view is the physical mnnircstation of a vinuallCrminal on the di!q)lay scrccrt. we will tend to U.4iC the lcnn
"vicw" rathcr than "vinual tcrminal" when discussing screen management is.\"Ues. Where ncccssary to be even more
specific. we wil~ usc the tcrm "viewport".

So. a virtual tenninal may be ac;.c;ociated with more than one view. On the other hand because the virtual
terminal is independent of its physical manifestation. there need be no views associated with it Destruction
of all views does not in any way affect the virtual terminal. though it will make it rather difficult for the user to
sec what is going on.
.
One common policy is that views are the domain of the user. A program that creates a virtual terminal
should create a view of it. so that the lIser knows lhat it exists. hut "fler that. in the ordinary course ur things.
the program should leave the view alone. The program should not depend on the continue existence of that
view, nor need it be aware of any other views of the virtual terminal that the user chooses to create. Let the
user decide where on the screen he wants views to be, and how big. and with what viewing transformations.
That is what the workstation manager is for.

2UnronUnalCly, traditional "window systcm" tcrminology tends to usc the word "window" to mean any or aU
defincd). vicwpon.. view. or vinual tcnninai.

17 .June 1986

V·Sys'~m

or window (as just

6.0 Rcrcrcncc Manual

The Uscr Interrace Architecture

2.1.1.3. V-System Agents

1·3

."

•t

lbe V-System currently supports two workstat~on agents. the simple lenninai server (STS) and the ~irtual
graphics tenninal server (VGTS). The STS providcs basic text tenninal emulation by making the workstation
appear as a single. traditional. page-mode tenninal - compatible with ANSI standard X3.64.) Character
echoing and line-editing arc optional. The STS is used principally to interface to ASCII terminals. but it can
also be used over remote tc:rminal connections and as the interface to the nonnal workstation keyboard and
display.
. The VGTS provides considerably greater functionality, including support of what is commonly referred to
as a window system (more on this later). Any "window" may emulate the same type of terminal provided by
the STS. Alternatively. a window may emulate a (structured) graphics terminal that provides roughly the
tacilities available in the ISO standard Graphical Kernel System, together with rudimentary modeling
facilities in the fonn of stru1ctured display files. Thus, the VGTS provides simultaneous support for two very
different types of real teoninal. Each virtual terminal may have any number of views associated with it. Any
number of views of any number of virtual terminals can be mapped to the screen at the same time.
Applications arc unaware of the number of views or what is being displayed in them. except insofar as
graphical input events return the appropriate world coordinatcs. The VGTS is used when it is desired to
make the best use of devic(:s typically found on contemporary workstati9ns - such as bit-mapped displays,
en~odcd keyboards, and mice.
While the abstractions lfor keyboard and mouse are common across (existing) virtual terminals, the
abstractions for the store are quite different, as discussed in Chapter 29. When neccs.~ry to distinguish the
two classes of virtual terminals currently supported,· we wilt refer to the type of virtual terminal that emulates an ANSI standard tenninal as an ANSI virtual tennillai (A Vf) and the type of virtual terminal that emulates a
structured graphics tenninal as a structured graphics virlual tenninal (SGV1).
'
Wami",: The "store" of an AVT is referred to as a pad UnfortunalCly~ that lCnn has been most frequently (and
erroneously) used ac; a plateholder for the complete AVI' abstraction, While this manual attempts to use each lenn where it
-is appropriate, thc code uses "pad" almost exclusively, Consequently, many of the routines described herein also refer to
"pad", Similarly, the term "vinual graphics tcnnina'" (or VG1,) has been used almost exclusivcly in the code, rather than
the lcnn "structured graphics vinual tcnninal", In both cases, we trust the readcr will be able to make thc appropriate
semantic substibJtions.

The bulk of the discussion to fonow assumes usc of the VOTS.
2.1.2. Workstation Managers

111e workstation manager permits the user to control multiple simultaneous execlltives -- with
accompanying applications.. 'lluough it executives are created and destroyed. programs arc interrupted and
kH1ed. and both virtual telnninal and views arc manipulated. With respect to the last. in particular, the
workstation manager is the module that enforccs the cOllslraillls on view management that the user desires.
For example, it enforces thc~ precise position and front-to-back "ordering" of view ports.
It is crucial to appreciat:e the distinction between workstntion managers and workslc1tion agents. rille
manager exerts "control" over the "facilitics" provided by the agent. while at the same time using those
facilities to internct with thc~ user. Different users may want diflerent styk.'S of control. For example. one user
may prefer to spccify all views llIanually~ where~ls ,mother user may prefer the system to determine the "best"
view "ulUmatically: one user may prefer his view ports to be tiled. whereas another may prefer them to
overlap. 'I1,CSC styles are independent of the basic facilities provided by the workstation agent.
In principle. it should be possible to define the ideal workstation manager. independent of all workstation
agents. But, just as workstation agents arc limited in pmctice by the classes of real terminals they support,
workstation managers are -limited in practice by the av,lilable classes of workstation agents.. For example, the
VGTS comes with a large and powerful workstation agent, called the view manager, which is accessed via

lrhc most widcsprc:ld examplc of a lcrminaladhcring to this standard is the Doc vr -100,

UsllII V

17 JUlie 1986

User laterfate OYeniew

popup menus. Many of its commands require the user to select or position view ports on the screen. Such "::\..
interaction works best in an environment with a mouse, for example. yet some workstation agents may not'
provide an efficient emulation of a !Jlouse. The S1'S, on the other hand. has only a trivial vestige of a
workstation manager. Its primary function is to guarantee thc existence of one cxecutive running on the
tenninal at aU times.
. ~L ,'_ :"

2.1.3. Executives

;.: .... '" \~ t...l

'_

Workstation agents and managers provide the basic facilities by which the user interacts with the
workstation. But little has been said about how the user actually specifics commands and applications. In
fact. these functions are providcd by executives (or shells).
Some systems penn it only one executive. often running only one application at a time, but sometimes
capable of running multiple applications at' time - onc in the Uforegroundtt and the rest in the
"background", for example. Under the STS. the V-System provides one executive (of the latter variety).
Under thc VGTS, multiple executives are supponed simultaneously; the view manager is responsible for
creating (and destroying) them.
,.,.
:~r:,'v,:
": .1:

a

,~;\

"

!

.'

..

,',

- :

...

2.1.4. Summary

We have outlined th'e ba.c;fc concepts underlying thc user interface to the V-System. The rest of this chapter
discusses the more practical details of how the user actually interacts with the system via its workstation agents.: ':; . .'
and workstation managers. Interaction with executives is discussed in thencxt chapter. .

2.2. Getting Started" .. '.

, '. ':II:;

When you come up to an idle workstc1tion, it may be in one of several states. If the screen is blank. it is
probably running V, but idle. The VGTS blanks the screen on idle workstations after a few minutes of
inactivity. Move the mouse slightly or press any key on the keyboard to restore the display. A previous user
may have left one or more of his sessions (see below) active. The command

logout

, :":1;

will tenninate them all and get you otT to a fresh start. If the workstation is running something other than V,
is dead. powered down. or the like. it will be necessary to reboot it. as described in the following paragraphs;
2.2.1. Booting the Workstation,

As previously noted. the V-System runs on a variety of workstations. Hooting procedures vary depending
on the manuf:,cturer and un the model. Section 16.1 describes in detail how to boot al1 of the workstt1tion
, configurations supponed with this rel~1SC. 'lbe following is an overview that should cover most situations.
2.2.1.1. Vax Stations

When in the PROM monitor VaxS~,tinns display a »> prompt If the works~'tion is not in this state. press
the hal t bullon twice (once to put it in. once to bring it OUl). If this utx,.'sn"t h"lt the machine, prcs.c; reset.
These bultuns are on the front panel of the Vax Station CPU. Once at the PROM prompt. the command b
xqaO will cause the workstation to boot over the ethe~net
2.2.1.2. SM. Workstations,

. .:;
An SMI workstation in a random state can be reset to the PROM monitor by holding down thc key in the
upper left hand corner of the keyboard. and hitting the "A" key. (,Ille key in the upper Jefl hand corner may
be laheled either LI. SI~r-UI). or ERASE EOF depending on the exact muueI.) There is no reset button on SMI
workstations. so a very serious crash can make it necessary to power-cycle the workstation.

17 June 1986

·t,.

V'Sysl(,DI 6.0 Rererence I\-lanunl

.• ".!

1·5

Getting Started

Once you have gotten into the PROM monitor. the next thing to do is to type the k2 command, which
simulates a power-up reset (Shortcuts are sometimes possible. but k2 is the safest route.) After the power-up
memory test i.4\ completed, the workstation will try to boot its default program. Most Sun workstations at
Stanford are configured to boot the V-System with VOTS. The bootstrap program first loads the
workstation's configuration file (see Chapter 19) to find out what its defaults are. It next prints "V-System" or
"xV-System" to ind!cate whc:thcr the production or experimental version of V is being loaded, then prints the
filenames. of the kernel and initial team as it loads them.
If you notice the workstaHon is not booting what you want it to, you can interrupt the autoboot with the
reset key sequence described above. then type in the exact boot command you want. Most of the time, one of
the following simple commands will do the job:
Boots the default program.
b
", ' . .'.• j

Boots the production verSion of the V'System, with the VOTS.

b V

Boots the experimental version of the V-System, with the VOTS.
b xV
General boot commands and the V bootstrap loader are described fully in section 16.

: .!'

,',111

I'

Note: M~t SMt workstati(ms at Stanford use the Sun-2 processor board. but a few Sun-Is have not been upgraded. The
above description is correct for SMI workstations with Sun-l processors as well as Sun-2s, but the details of the general boot
command and other PROM monitor commands vary. The V k.ernel tickles a bug in the current Sun-3 PROMS. Rebooting a
Sun-3 usually requires pow~r cycling the workstation.

2.2.1.3. Cadlinc Workstations

.''

..

A Cadlinc workstation in a random state can be reset to the PROM monitor by typing
pressing the reset button. or (in desperation) power-cyc1ing the workstation. It is best
to try prcs.~ing the comma klcy on a Cadlinc's numeric keypad before resetting it If the V kernel is act~ve at
that point this key instructs it to turn off the mouse, necessary for proper operation of the PROM monitor.
Otherwise. you may have to power cycle the workstation or keyboard to regain controL

ks first for a V program in the current context (i.e.• current working directory),
then il1l the [bin] context You can specify a different search path using the PATH environment variable
(section 3.6.7). If the command is not found on your search path, the exec will try to execute it remotely, on
the server that is providing your current c~>ntext
The executive waits for c~ach command to exit. unless the last field on the command line is the single
character &. In this case, the command runs in the background, while the executive continues to accept
commands from the keyboard. The View Manager and STS provide mechanisms for stopping or interrupting
a command running in the foreground. A program running in the background may be terminated using the
des troy command (see chapter 4).
Other exec features arc described in section 3.6.

3 . 2. Naming
A context in the V system is similar to the directories provided by other systems such as Unix. Each process
(and thus each executive) h;ils its own current context, i.e., current 'working directory. A filename is normally
interpreted in the current context. unless it begins with a square bracket f['). The square bracket flags the
name as being either an absolute name, or a local alias.
In V. the first component of an absolute name generally specifies the type of object or service being named.
The second component often specifics a particular server. For example,
[storage/pescadero]/etc/passwd
names the liJe letc/passwd on the storage server pescadero. 'nle closing square bracket is optional
here. Most servers accept it as an alternative to the sumdard slash character f r) used to separate name
components.
Usel's can define their own local aliases for contexts. using the define and undefine commands. For
example,
define 9 [sto~age/gregorio]/user/mann
defines, [g] as an abbreviation for user Mann's home directory on the storage server Gregorio. The
comm,and
undef1ne 9

Using V

7.June 1986

Using the V Exccati.e

removes this definition. The command

printdef
lists the local aliases that are currently defined. Several other standard aliases are automatically defined by the
executive when you log in. These include
[home]
The 10~ged-in lIser's home directory.

[sys]
[b 1 n]

The directory containing standard V-System files.
The directory from which standard V-System commands are loaded. Normally the same as

[sys]b1n.

[V]

The directory containing standard production V-System files. The same as [sya] if you
are running the production V-~ystem.

[xV]

The directory containing standard experimental V-System files. The same as [sys] if you
are running the experimental V-System.

The "home" server used for program execution. Nonnally [team/local], the local
team server. See section 3.6.9.
.
When running with the VGTS, aliases defined in any exec created by the view manager are global to all such
execs. since all the execs run on the same team. A program run under the exec inherits a copy of the exec's
aliases. Later changes to the exec's aliases do not affect it.

[hom.x]

3.2.1. Changing the Current Context '

The cd (change directory) command can be used to change the current context for an exec. The command
format is
cd pathflame

The path name is interpreted in the (previous) current context. If the path name is omitte file
or

cmd »

file

The latter form specifies that the output should be appended to the ft1e whereas the first form wi1t overwrite
any data ulready existent in the ft1e. Error output can be redirected by specifying >1 or »1. The forms >&
and> >& redirect both stand,llrd output and standard error to the same file.
A special fonn of redirection is available for bidirectional ft1es, such as the serial lines available on Suns.
Specifying
.

cmd <> file
cmlses the command's input and output to be redirected to the same file. To be precise. the file is opened in
FCREATE mode, and standard output is redirected lo the ins~1nce thus created. Sl4mdurd input is redirected
to come frum an instUlce whiose id is equal to the output instance id plus 1. This matches a convention used
by severul V-System I/O servers. 111e fonn <>& also redirects standard error to the same instance as standard
output
Pipes can be set up between several commands by separating them with a I·on the command line. Thus.
for exumple. the command line
cmd1 I cmd2 I cmd3 > log
will create two pipes and redirect [/0 so that the output of cmdl wilt be used as the input to cmd2. the output

Using V

7 .June 1986

Using the VExecud,e

of cmd2 will be used as the input to cmd2•.and the output of cmd2 will be redirected into the file log.
All the special characters described above must be surrounded by spaces for the executive to recognize
them. Redirection clauses must appear after all arguments to be passed to the command.
3.6.6. Quoting Command Arguments

Sometimes it is desirable to include a space in a single argument to a command. To do thi~ put a pair of
either single quotes (t) or double quotes (") around the argument An argument quoted by one ofthesc may
contain the other. Unmatched quotes are ma~hed by ,the end of the line.
3.6.7. Environment Variables

The command
setenv vaT valut
sets the environment variable WlT to the character-string value value. (The latter should be quoted if it
contains spaces.) As with local aliases for context names, environment variables are shared among all execs
created by the View Manager. and are inherited by programs run under any excc.
.
The command
unsetenv vaT
removes the definition of var, while the command
pr 1ntenv var
prints its definition. The pr 1ntdet command with no arguments prints all environment variables.
A command argument that begins with a dollar sign ('$') is replaced by, the value of the rest of the nrgument
interpreted as an environment variable, if such a variable is defined. Otherwise the argument is left
unchanged.

When trying to execute a V command. the exec detennines the search path to be used from the
environment variable PATH. if it is set. as ~o all programs that use the stand1rd V-System program execution
library routines. The value of PATH should be a list of context names separated by spaces. The default path,
used if PATH is not set. is"./ [bin)".
3.6.8. Concu rrent Commands

, Commands can be specified as beillg concurrent by including an .. at the end of the command line. This
causes the executive to return immediately to the user for another command rather than waiting until the
current command completes. Also. while nonconcurrent (foreground) commands are tenninated if their
executive is deleted. concurrent (background) commands will continue even if the executive that initiated'
them goes away. In fact, concurrent commands continue to execute even if the user that initiated them logs
out
The &must be preceded by a space for the executive to recognize iL
3.6.9. Execution of Commands on Another Host

','

Commands can be designated to execute on another host by including
i ]

[]

The unit of migration is the logical host. not individual teams. All remotely executed
programs are created in their own logical host. whereas all locally executed programs are
run in the system logical host, which never migrates. Thus only remotely executed "guest"
programs will ever migrate. Currently there is noway to create a locally invoked program
in a separate logical host other than to invoke it remotely from another machine.
If no arguments are specified then all guest programs on a machine are migrated to "lightly
loaded" machines.. where lightly loaded is defined in the same sense as any is defined
when initially executing a program remotely. The -p flag specifies that information about
what programs are being migrated where should be printed out The -h flag allows
specification of a particular machine to migrate to. The machine to migrate to may be
specified by either the hex pid of its team server (in the form Ox(pid» or by giving its
official string name (e.g. sun-mj416). If specific programs are specified then only those
programs are migrated. Programs may be specified by the hex pid of one of their processes
or by theill' full invocation name, as stored by the team server.

mon

This program monitors resource utilization of the workstation and presents it graphically.
The -d fla,g specifies a vertical display ("down") instead of horizontal. The default display
shows percentage used of memory and processor, and the number of incoming Ethernet
packets per second. The flags em, -p, and -e limit' the display to only those specified. The
-f flag violates the user interface standards by putting the display in the upper right corner
of the workstation instead of requiring th~ user to position it with the mouse.

name

Prints the login name of the user under whose account the command is running.

newterm

Change te:rminal agents. Takes one argument. the filename of a new terminal agent to take
the place of the existing one. All executives running underthe old terminal agent are
destroyed; the new one will presumably provide means of creating a new one. For
example. :newterm sts replaces the VGTS with the Simple Terminal Server~ which does no '
graphics 'but simply presents the workstation as an ascii terminal. If no argument is given,
it defaults to "vgts".
Wambrr: If the named program is not in fact a terminal agent. you will probably lose control of your
workstation.

18 June 1986

4-6

pagemode

password

pc68
pwd
pwx

Q
query

Command Summary

Enable or disable paged output mode in the current executive. Takes one argument, which
may have one of two values: "on" or "otr'. When paged output mode is on. the tcnninal
agent stops writing to a AVT when the AVT fills up with output The terminal agent then
displays the message ''Type (space) for next page" and waits for the user to issue a
command which unblocks the AVT. The user interface for paged output mode is
described in section 2.6.
Use this program to change your V password, home directory, or personal name. The V
superuser can also use it to create new accounts or modify other users' accounts. Uses the
f1el ds package (section 21). To modify the displayed Name, fname, or Home, click on
the old value with the mouse, use the normal line-editor commands to change the value,
then hit return. To make the change take effect, click on Alodify and supply your old and
new passwords.
Other functions: click on find to flDd another user's authentication database entry. Click
add to add a new user account (a unique user number is selected for you). Click delete to
delete the displayed account Qick exit to leave the program.
Compiles Pascal source programs for running on the m68000 processors. See the Unix
man page. The flags are similar to those ofcc68.
Prints the absolute name of the current working directory. Built in to the exec.
Prints the (absolute) name of your current execution context-see section 3.6.9. This
command is built into the exec.
This is an experimental interactive functional programming language (m68k only). See Per
Bothner (bothner@su-pescadero) for information and a user guide.
Prints out the result of perfonning various 'query' operations. In particular, query
kernel prints the result of the QueryKernel () library routine (see page 27-3), query
conf1 g prints the contents of the workstation's configuration file (see Chapter 19), and
query ethernet prints the result of querying the "ethemet" device (see section 36.1).
query ? lists the possible options.
"

queryexec

Find out the status of the specified executive. Useful mainly for system testing.

ranlib68

Identical to the UNIX ran 11 b command, but handles archives of either m68k or vax
binaries. This command is installed on UNIX under the name ranl1b88, and on V
under both the names ranl1b and ranl1b88.
Part of the Revision Control System. Described by a UNIX manual page.
Part of the Revision Control System. Described by a UNIX manual page.
Part of the Revision Control System. Described by a UNIX manual page. Currently, this
program must remotely execute the rd"1ff3 and merge programs of RCS on a UNIX
host, since the latter have not been ported to V.

res
rcsdiff

rcsmerge

rename

rlog
rm

18 June 1986

Renames the object specified by the first argument to the name given as the second
argument Will not move objects from one server to another: there are also restrictions on
moving objects within one server (for example, from one file system to another under the
Unix server).
Part of the Revision Control System. Described by a UNIX manual page.
Takes one or more filenames as arguments, and removes each file. The -f flag suppresses
error messages if some of the files do not exist
Note that in particular, rm may be used, as an alternative to the destroy command, to
destroy one or more teams (by name). For example.
rm [team/toto/[b1n]1nternetserver

V-System 6.0 Rererence Manual

4-7

Workst:1tion Commands

will 'remove' (i.e. destroy) the program "{bin]intemetserver' that was executing on host
"toto". Unlike the des,troy command, the fhll program name must be given.
sed

Stream editor. Described by a UNIX manual page.

serial

This program provides a full-duplex conversation between its standard input and output,
and a device connected to one of the serial ports of the workstation. The argument is a
device name, specifying the line to be opened. It defaults to [device]seriaIO if omitted.
Names of the form [device]serialn (with n a single digit) can be abbreviated by giving only
the digit If the serial line, is connected to a modem or a terminal port on another
computer. this program allows the workstation to act as a terminal. The flag -b b i trate
can be used to specify the bit rate (baud rate) of the connection; it defaults to 9600 bps.

show

Displays a • dv1 file or a • press file. It creates a menu in the invoking window;
commands are normally selected with the mouse. A new window is created for displaying a
page from the • dv1 or • press file. You can invoke the program with show filename, or
you can set the filename in the menu. More details are given by the "helptt command
(type h o:r select [He 1p] with the mouse). TeX generated dv 1 files are handled pretty
well, except for possibly missing fonts (and perhaps speed). The press support is pretty
minimal.

sleep

Delays for a time, then exits. The delay time (in seconds) must be specified as an
argument.

sort

This command has the same syntax and semantics as under Unix 4.2BSD.

startexec

Create an exec in a new AVT. The new exec will have the same context as the exec from
which startexec was invoked, not the [home] context For most purposes the view
manager's Create Executive commands are to be preferred over this one, as the view
manager will not work on an executive created by startexec. startexec prints out
the exec id and process id of the new exec.

storagestats

Obtains accesS statistics collected by the V storage server and disk driver. The -c flag
causes the statistics to be cleared to zero.

stuffboot

A program that stuffs the file named in argument 2 into the boot block of the disk named

as argument 1. The file to be stuffed normally will be Vload and is needed during autoboot when the boot program is read out of the boot block on the root disk device. Ifa third
argument is present, it is taken as the name of a file to copy into block #0 of the root
device (tbe disk label).
tail

This comrnand has the same syntax and semantics as under Unix 4.2BSD.

talk

Allows interworkstation communication among V hosts similar to talk under Unix.
Invoked as
ta'i k [person]
Person is optional. If person is 'specified, it can either be in the form us 8 r 1d to specify a
user on doe first host we find that user to be logged in, user1d8host to specify a
particular user on a particular host, or 'host to get anyone on that host
Once inside ta 1k, you can enter commands by first typing [ESq, and then another letter.
The available commands are:
invite a new user. You are prompted for, who you want to invite, and
you can respond in any of the ways mentioned for person above.
log in AVT. This allows you to,see in a temporal fashion who says whaL
You are prompted for a new' AVT to write the log in. Giving this
command again terminates logging.

18 June 1986

Command SUmJDarr

4·S

q

quit Only you quit; any other persons engaged in the conversation can
continue to do so, even, if you were the one who initiated the
conversation.

r

read from file. It reads the tile into the conversation such that it looks as
though you typed it all. However, there is currently no pagenation. If
what was read is very long it will quickly get overwritten.

w

write to tile. This is the same as "log in AIT' above, except logging is
done to a file you specify. Giving this command again terminates
writing.
WIII'JIi",: tal k runs only under the VOTS. There is currently a compiled in maximum of six talkers
in one conversation. tal k AVTs are fixed at 24 by SO.

Due to om'ent VOTS restrictions. tal k is forced to initiate a conversation by writing to the VOTS
AVT (the small one originally in the lower ri&ht hand comer) and then opening a new AYr. which
gives the victim a PAD cursor. To accept the invitation the AYr is placed normally: to reject the
invitation click all three mouse buttons. This is bad if the VOTS AVT is obscured- the victim win
let a beep and a Avr prompt and not know why.

tel net

IPrfCP-based tel net implementation. It can run under the S1'S, or in a VGTS AVf. A
destination host name or address may be given as a command argument; if none is given,
telnel prompts for one. A host name is a string of non-white-space characters starting with
a non-numeric character. A host address is a string of the form a.b.c.d, where a,b,c and d
are decimal integers. Both names and addresses may be followed by a dot and a decimal
port number (with no intervening spaces).
If the -e flag is given when it is invoked, lelnet recognizes a set of commands prefixed by
ctrl-t while connected to a remote host Ctrl-t? prints a list of all such commands. These
functions are not available by default because they sometimes interfere with higher level
protocols such as that used by the VGTS.

After disconnecting from a remote hos~ lelnet prompts for another host To exit lelnet,
enter ctrl-c or ctrl-z in response to the prompt
If there is no internet server on your workstation when lelnet is loaded, it runs one in the
background. The -I flag inhibits loading a local server instead looking for a public internet
server running on another V host.
The -d flag enables debug mode. In this mode, all transmitted and received telnet protocol
commands are printed, and all received non-printable characters are printed in an escaped
notation. Debug mode can be toggled on and off by typing ctrl-t d while connected to a
remote host if the -e option is specified on the command line.
9

The -g flag enables logging mode, which implies the -d debug mode above. A file,
"telnetloigfile" will be created in the current directory. This file will contain a complete
transcript of bothe sides of the telnet session. Lines preceded by "(" originated from the
host while those preceded by">" originated from the workstation. All non-printing
characters are quoted and all tel net proteol commands are printed. Password input is
automatically deleted. This mode is transparent to both sides of the connection. Logging
mode can be toggled on and off by typing ctrl-t g while connected to a remote host if the -e
option is specified on the command line.
telne tse rver

IPrfCP teinet listener. This program listens for incoming telnet connections on the local
, intemetserver, spawning a remote terminal server (RTS) for each connection received.

testexcept

Simple interactive program for testing the exception server.

timeipc

Perfonns timing tests of the V interprocess communication primitives. See chapter 13.

time kernel

Program to measure the time for Send/Receive/Reply kernel p,rimitives.

IS June 1986

V·Syslem 6.0 Rererence Manual

Workstation Commands

4·9

tsart

Topological sort. Identical to the UNIX program of the same name.

type

Type out one or more files on the tenninal. Types a page-full and then stops and waits for
input. Pn~sing [SPACE] brings up another page, while [RETURN] brings up another line..
Hit q or tC to quit

undefine

Removes the definitions of one or more local context names (aliases). Built in to the exec.

ved

A text editor, somewhat similar to Emacs, that runs under the VGTS. Described in
Chapter 14.

vemacs

A version of the Emacs text editor that can, among other things. make use of the window
features of the VGTS. When vemacs is invoked without any arguments, it will display a
help file d.~scribing how vemacs differs from standard Emacs.

w

Lists logged-in V users throughout the network.

we

Counts characters, words, and lines in a text file.
documentation.

wh

Usts hosts on the network together with information such as logical host name, free
memory, average processor usage, number of free process descriptors, host type, etc.,
sorted by host name.

whi

Lists curre:ntly executing teams for each host. If one or more 'host' arguments are givetly
then only the teams on the specified host(s) are listed. Such arguments can take the
following form: a hostname, a pid (Ox ••• ), or "0" (indicating the local host).

See the UNIX manual for full

4.2. Commands on Non-V Hosts
There are also several useful commands that can be invoked on non-V hosts (usually a Vax/Unix system).
Use these commands once you have logged into a machine through a tel net connection. Most of these
commands also have versions that run locally on the workstation under the VGTS, and the Unix versions can
also be run remotely under the VGTS, using the exec's remote execution feature (section 3.4).
dale
A version of the Yale layout editor that runs under the VOTS.
draw

An interactive drawing program that runs under the VGTS. See Chapter 10.

photo

Reads and displays a .sun" format raster file.

siledit

A program which edits .SIL format files. SIL, a Simple Interactive Layout program, is a
graphics editor for logic designs and illustrations.

silpress

A program which takes a .sil format me and produces a .press format file that can be
printed on the Dover.
.

U

18 June 1986

5-1

-5-

amaze: A Maze Game

Amaze is a game for two to five players which runs under the STS on a workstation with a framebuffer. If
you see the letters VGTS in a small window on your screen you are not running the STS. See section 2.2 for
instructions on how to start up the STS.
To run amaze, type the command

amaze
If no one else is playing•. it will type "New game starting" and then draw the maze. Otherwise it responds
with "Joining game as player number x" and then draws the maze. Your player token. called a monster, will
be sitting in the center of the screen just above a checkered flashing door. From this point, you control your
monster through the keyboard. The commands are:

i
,
j
1
k.

a
e
e
s
f

h
v

o
1
2
3
4

5

Move the monster up.
Move the monster down.
Move the monster lef~.
Move the monster right.
Hold the monster at its current position.
Let the monster's moves be se 1elcted randomly.
Fi re the monster's missile
Fi re the monster's missile
Fi re the monster's missile
Fire the monster's missile
(Note: the missile can be
seconds.)

up.
down.
left.
righ·t.
fired only once every six

Hide the monster from other players -- no shooting allowed
while hidden.
Let the monster be seen again -- can shoot again, too.
(Note: monsters stay hidden for ten seconds, but once
they become visible, they remain visible for 16 seconds.)
Set
Set
Set
Set
Se't
Set

monster
monster
monster
monster
monster
monster

velocity
velocity
velocity
velocity
velocity
velocity

to
to
to
to
to
to

o.

1.
2.

3 -- the starting velocity.
4.

5.

q

Quit the game. but continue to watch other players.
Rejoin the game just above the door.
r
Rejoin the game at a random corner in the maze.
Ctrl-C Terminate your involvement with the game.
t

R

Redraw the maze and players.

Notc that to leave thc game entirely you hold down the CfRL key and type 'c'.

Using V

30 April 1986

amaze: A Maze Game

To rejoin the game after being shot by another monster. usc either the t or the r command. The game
currently docs not keep score of the number of hits you inflict or suffer.
Problems and questions should be directed to Eric Berglund.

30 April 1986

V·Syslent 6.0 Rderrttcc Manual

6-1

-6-

checkers

checkers allows you to playa game of checkers against the computer. The default version of the program
.
executes entirely on the players workstation.

On starting the program. the view manager will prompt you for the position of the
checkerboard..

sovr representing the

The player moves the 'red' (white) pieces; the progrclm's pieces are black. You are expected to make the
first move. You can, however, force the program to move first by "passing". (Sec the paragraph describing the
menu, to follow.) To make a move, move the mouse to the square containing the piece that you wish to move,
and click either the left or the middle mouse button. If this piece can be legally moved. it will then be
highlighted. Complete the move by moving the mouse to the destination square and once again clicking the
left or the middle button.
If the move that you have selected is legal, your piece will be moved, and the program will then make its
move. Note that having selected a piece to move. you can abort this selection by clicking all illegal destination
square (the source square itSi~lf, for example). If a capture of an opposing (ie. black) piece is possible, your
next move must be a capture. A message indicating such "forced captures" will be displayed just below the
board. In such a case, the program will not allow you to make a move that is not a capture. Multiple captures
arc handled correctly - if you move a piece by making a capture, your mov.c will not be completed until all
possible captures with this piece have been made.
The standard rules of checkers apply. If a piece reaches the eighth rank of the board, it is promoted to a
king; kings may move in any direction. A side wins either by capturing all of the opposing pieces, or if the
opposing side can make no legal move.
When it is your turn to move, you 'may also usc the right mouse button to select from a menu of options,
which are described below:
'
Redraw
This caUS<:8 the VaTS to redraw the entire board. This command should rarely be
necessary.
Pass (skip turn)

This command can be used if you want the program to make the first move. You can also
use this to avoid any capturing obligations.
.

Change search depth
By default, the program searches 4 half-moves ahead when choosing its next move. That is,
.
it considers its own move, your response to this move. its next move. and your response to
that The "Change search depth" command ullows you to change the depth of lookahead
to any value from 1 to 8. Don't select any of the higher depths unless you have a lot of
putience, however. '111e program takes about 20s to respond to a typical opening move
when the depth is 6, about 50s when the gepth is 7. and about) minutes when the depth is
8. (These times were taken on a 10 MHz SMI workstation - Cadlincs will be slightly
slower.) Note that you may find out the current search depth by selecting "Change search
depth", and then clicking outside the 'depth' menu.
Edit board

This command puts you into /;:dilmodc. which allows you to cheat by adding pieces to, or
removing pieces from, the board. Edit mode is described below.

Back up one moveThis allows you to retract (eg. to correct) your last movc.
Resign

Usin. V

The quick and cowardly way to end the game.

1 May 1986

dlecken

The program chooses it's move by performing a 'brute-force' search, using alpha-beta pruning. It evaluates
the board positions at the 'leaves' of the search tree using a simple heuristic based on the number and position
of pieces on each side. A 'value indicator' to the right of the board indicates the value of the current position;
as seen by the program. (If the indicator is above the halfway mark, for example, then the program 'believeS'
that you are winning.) There are also counters immediately above and below the value indicator, giving the
number of pieces on eac~ side. 'lbe value indicator and the piece counters are updated whenever the program
completes its move.

'.

:"

You can malec 'changes to the board (between moves) in Edit mode. In this mode, a special menu is
displayed to the right of the board. To add a piece to the board (or change an existing piece), click the square
in the menu that contains that piece. You may place a copy of this piece on any (shaded) square of the board,
by click ing that square. You may do this repeatedly; it is not necessary to select from the menu each time.
Note that you use the 'empty square' to delete one or more pieces from the board. You may remove aU pieces
from the board by clicking "Clear". When you have finished making changes to the board, click "Done" to
leave Edit mode. It will still be your tum'to move next.
-

. ,-:.")

A distributed version of the game may be started by specifying the r flag: checkers -r . The
program. will then try to create up to NoOfSlaves slave processes on lightly loaded remote workstations, that
help in the search of the alpha-beta search tree. As far as the player in concerned, the only two noticeable
differences to the default sequential version of the game, arc the pos.'iible improved response times and that
the computers moves may be nondeterministic. (Note: it is only worthwhile to play the distributed version of
the game if the search depth is chosen greater than four.)
Mail comments and/or gripes to stumrn@p~dero.

I May 1986

V-System 6.0 Rderence Manual

-7-

bits: a bitmap and font editor:
"

b 1 t3 is a special-purpose editor for working with bitmaps and fonts. It makes intensive use of the VGTS.
The virtual terminal Qf tll(~ executive under which b 1ts is started up, is used to display various status
informatio~ as well as being the menu of commands to execute. When started. b 1ts will ask for you to
create a new view (of a new virtual terminal) in which the actual editing is performed. If you request to view
sample text, you will be asked to create a third virtual terminal (see below). These las~ two vinual terminals
are SGVT's and can be zoomed.
. . . . . . ; . . "'1
(Note: If you are using a Sun-120 framebuffer (including a model SO), you should read the Bugs section!)

7.1. Command Input
In this chapter, when you are asked to do the command [xxx], it means that you should select and cUc(
the mouse at the field [xxx] of the status/command virtual terminal. You get the same feedback as witt\.
pop-up menus, with the field in inverse video. Some of these fields, when activated. expect you to type in ..
some number or string. In those cases, you have the full power of the line editor, until you type a 

---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.3
Linearized                      : No
XMP Toolkit                     : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37
Create Date                     : 2003:10:11 13:58:14-07:00
Modify Date                     : 2014:10:14 08:47:12-07:00
Metadata Date                   : 2014:10:14 08:47:12-07:00
Producer                        : Adobe Acrobat 9.55 Paper Capture Plug-in
Format                          : application/pdf
Document ID                     : uuid:99c177b6-69b1-914f-b129-f08348692606
Instance ID                     : uuid:dba67156-d17a-8e4b-b2d9-2f5373b4e1c8
Page Layout                     : SinglePage
Page Mode                       : UseOutlines
Page Count                      : 326

EXIF Metadata provided by EXIF.tools