PDP-10.its/doc/sysdoc/ufd.100

Copyright (c) 1999 Massachusetts Institute of Technology
See the COPYING file at the top-level directory of this project.
------------------------------

Disk file directories are each one disk block
of data (2000 words).  The file directory contains
all the data necessary to maintain the actual files on the disk.
The directory is arranged in two main portions.  The name area
contains identification data for every file said
to be "in that directory", including the file's names, time of
creation, and a pointer to the descriptor area.  The descriptor
area portion of a file directory describes exactly where on the disk
the files are.

The file SYSTEM; FSDEFS > contains a page beginning
";UFD INFO", UFD meaning "user file directory".
This page contains the assignment of most of the important
symbols which define the directory format parameters.  The following
description assumes the values of the parameters when this
document was written, and although most of the parameters are not
apt to change, there is this possibility.

The first word of the file directory contains a pointer to the beginning
of the descriptor area, and the second word points to the beginning
of the name area.  The third word of the directory contains the sixbit
user name of the directory.

The name area of the directory contains 5 words
of information for every file.

1 - FN1 (SIXBIT)
2 - FN2 (SIXBIT)
3 - STATUS BITS & RANDOM INFO
4 - CREATION DATE
5 - DATE LAST REFERENCED

The fourth word contains the compacted date and time of
creation for the file.  The right half of this word is the
time of day since midnight in half-seconds.  Bits 3.1-3.5
are the day, bits 3.6-3.9 are the month, and bits 4.1-4.7
are the year.  The fifth word's left half holds the date the
file was last referenced.  This is in the same format as the
creation date.

	4.9-4.8 - UNUSED
	4.7-4.1 - YEAR (RELATIVE TO 1900)
	3.9-3.6 - MONTH (1=JAN)
	3.5-3.1 - DAY (1-31)
	2.9-1.1 - (RH) # HALF-SECS SINCE LAST MIDNIGHT (4th wd only)

The third word in the name area for every file contains all
the information about the file's status, with bits
indicating things such as whether the file has been deleted,
whether it is open for writing, etc.

	4.9  -  FILE DUMPED TO TAPE
	4.8  -  UNUSED
	4.7-3.7 - # WORDS IN LAST BLOCK OF FILE
	3.6  -  FILE DELETED FROM UNMOUNTED PACK
	3.5  -  FILE WILL DISAPPEAR WHEN CLOSED BY ALL WHO HAVE IT OPEN
	3.4  -  UNUSED
	3.3  -  OPEN FOR WRITING
	3.2  -  UNUSED
	3.1  -  THIS FILE IS LINK
	2.9-2.5 - PACK # FILE STORED ON
	2.4-1.1 - BYTE ADDR PTR TO START OF FILE'S DESCRIPTOR BYTES

2.4-1.1 is actually a byte address relative to a point 11.
words from the beginning of the directory.  The byte size is
6 characters, so the word address is the pointer divided by
6, and the byte within that word can easily be determined by
the remainder of the division.  Once the correct byte
pointer is determined, successive ILDBs will get the
descriptor bytes of the file.  Assuming the contents of A
points to the third word of the name block for a file, here
is a piece of code which will generate the correct byte
pointer in N, all set for ILDBing, with N indexing B, which
holds the correct word address:
;B=2
;C=3
;UFDBYT==6		;SIZE OF BYTES
;UFDBPW==36./UFDBYT	;NUMBER OF BYTES PER WORD
;FDIRBF IS FIRST LOCATION IN DIRECTORY, UDDESC IS 11..

	LDB B,[1500,,A]		;GET BYTE ADDRESS
	IDIVI B,UFDBPW		;CHANGE TO WORD ADDRESS
	ADDI B,FDIRBF+UDDESC
	MOVNI N,-UFDBPW(C)
	IMULI N,UFDBYT		;Only works because UFDBYT divides 36.
	HRLI N,060200		;ASSUMING B=2 !!!!
	ROT N,30.
;END OF ROUTINE

If the file is a link, the descriptor bytes themselves specify
what directory and file names this file is linked to.  These
three args are the only pieces of information in the descriptor
area for links.  Each name is terminated by a semicolon unless
it is a full six characters long.  Colon quotes the character
that follows it.

For normal disk files, every descriptor byte tells where the
next block, or group of blocks, of the file resides on the
disk.  A byte with a value of 0 ends the description.  A byte
with the value 31. (UDWPH) is an ignored place-holder.  If
the byte is from 1 through 12. (UDTKMX), that many blocks
of the file reside contiguously.  If the byte is from 13.
through 30., skip that many blocks minus 12., and the next
block, after the ones skipped, is in the file.  If the 40
bit of the byte is set, the low 4 bits of that byte together
with the next 2 bytes tell where the next block of the file
is to be found.  When the 40 bit is set, the 20 bit is a
flag which, if on, says that blocks that follow each contain
a word count in their last word.

Occasionally when a program tries to open a file for
writing, there is no more room in the file directory for the
file's specifications, not because there is really no room,
but because non-existant (deleted) files still have
descriptors etc. taking up unnecessary room.  When this
happens, the system rearranges the directory, a
"housekeeping" chore known as garbage collecting.  Garbage
collecting a file directory takes about 1-2 minutes of
realtime waiting, usually.  If the system is provoked to
garbage collect FOO's file directory, it announces the
occasion on the system job console with the message "GC OF
USER DIR FOO".  During the ordeal, the job provoking the
collection may not be control-Zed amongst other things.  If
you try to control-Z it, however, the only noticeable
difference to you will be a long wait before DDT knows to
recognize your request for interruption.  If ^Z seems not to
be "doing much", try checking the system job console to see
if you are being garbage collected.

File directories are read by timesharing programs the way
any disk files are read.  Merely use the file name .FILE.
(DIR) for the .OPEN, and the system will supply you with the
directory instead of a file.  If the mode is ASCII, the data
you receive after .OPENing .FILE.  (DIR) is the ASCII string
you normally see, upon doing :LISTF DSK: or DSK in DDT or
EYDSK: in TECO.  If the mode for the .OPEN is image, the
data you receive is the actual file directory as advertised,
and as stored on the disk.  As already mentioned, it is
exactly 2000 octal words long, and is organized exactly as
described above.  Any program opening disk file directories
for the purpose of seeing what files are on the directory
will be far more efficient opening the directory in image as
opposed to ASCII mode.  Such programs, when written in MIDAS
assembly language, should .INSRT SYSTEM; FSDEFS > and use
the symbolic definitions therein, for greater clarity and
immunity to system changes.