Path: utzoo!mnetor!uunet!lll-winken!lll-lcc!ames!pasteur!ucbvax!decwrl!tle.dec.com!rmeyers
From: rmeyers@tle.dec.com (Randy Meyers 381-2743 ZKO2-3/N30)
Newsgroups: comp.sys.amiga
Subject: The zero lock
Message-ID: <8805032135.AA26451@decwrl.dec.com>
Date: 3 May 88 21:35:51 GMT
Organization: Digital Equipment Corporation
Lines: 90

A couple of weeks ago there was a discussion in .tech on the special
lock 0.  Several people were badly confused as to what a lock with a
value of zero means, and what operations are valid using this lock.

AmigaDOS supports a special lock who's value is zero.  The CLI
created when the Amiga is booted and Workbench processes all start
out with a current directory lock of zero.  This special lock is a
lock not on any particular file or volume: it is a lock on the device
DF0:.

Since the zero lock is a lock on the device DF0:, any volume mounted in
DF0: when the lock is used will be the volume referenced.  For example,
if the initial CLI never issues a CD command, a DIR command will take
the directory of whatever floppy mounted in DF0: when the DIR command is
given.  This feature can be very useful when browsing through several
floppies.

Not many people know the meaning of the zero lock because it is somewhat
poorly documented in "The AmigaDOS Manual."  The describes the zero lock
as "referring to the root of the initial filing system."  This has caused
some people to think that the zero lock is a lock on the boot floppy
instead of the device DF0:.  For example, Robert Peck's "Programmer's
Guide to the Amiga" mistakenly claims that the zero lock is lock that
can be used to determine the volume name of the boot volume and that
"No matter how many disk swaps you perform, along with ASSIGN statements,
the system still remembers which disk volume name was used for the
original boot."  This is wrong on both counts.  The system completely
forgets which volume was the original boot volume if all the assignments
(like SYS:, DEVS:, LIBS:, etc.) are changed, and the zero lock (and
Peck's example program) always refers to the volume mounted in DF0:.

A good part of the confusion about the zero lock is because most of the
documentation about the zero lock does not occur in the section of the
AmigaDOS on calling AmigaDOS functions, instead it occurs in the section
on AmigaDOS data structures and sending packets to handlers.

The zero lock is a legitimate argument for any AmigaDOS function that
takes a lock as an argument.  All of the AmigaDOS functions do the
right thing when passed a zero lock.  At no time do they cause a system
crash, or even an error return from the function call.

Here is the list of AmigaDOS functions that take a lock as an argument
and what the function does when passed a zero lock:

CurrentDir	Set the current directory to DF0:.  Any reference to
		a file in the current directory will get a file in
		whatever volume is currently mounted in DF0:.  If no
		floppy is mounted in DF0:, the system will display a
		requester, "No disk present in unit 0."  At that point
		you can either place a floppy in DF0: or abort the
		operation.

DupLock		Will return zero as the duplicated lock.  This behavior
		is required by the documentation on sending packets to
		handlers.  (The value of IoErr is not changed by
		DupLock(0)!  If it was zero before the call, it will be
		zero after.)

Examine		Returns information about the volume currently mounted
		in DF0:.

ExNext 		Returns information about the files in the volume currently
		mounted in DF0:.

Info		Returns information about the volume currently mounted
		in DF0:.

ParentDir	Returns zero (DF0: is its own parent).  IoErr is cleared.

UnLock		Takes no action (the zero lock remains an active lock
		after being unlocked).  This behavior is documented in
		the section on sending packets to handlers.  (The value
		of IoErr is not changed by UnLock(0)!  If it was zero
		before the call, it will be zero after.)

As you can see, the zero lock is a perfectly good lock.  The only thing
that you cannot do with it is convert it to a pointer to a struct FileLock
by shifting it left by two.

There is a chance that Kickstart 1.3 could change the meaning of the
zero lock.  The autoboot feature might change the meaning of the "root
of the current filing system" to be the boot device.  Perhaps, C/A
can comment?

All of this contains a lesson for anyone writing a AmigaDOS handler.  If
your device supports locks, it should correctly support zero locks as well.

----------------------------------------
Randy Meyers, not representing Digital Equipment Corporation
	USENET:	{decwrl|decvax|decuac}!tle.dec.com!rmeyers
	ARPA:	rmeyers%tle.dec.com@decwrl.dec.com