Legacy Document

Inside Macintosh: Files /

Chapter 2 - File Manager / File Manager Reference

Low-Level Volume Access Routines / Obtaining Volume Information

PBHGetVInfo

You can use the PBHGetVInfo function to get detailed information about a volume.

FUNCTION PBHGetVInfo (paramBlock: HParmBlkPtr; async: Boolean): 
                        OSErr;

paramBlock

A pointer to a basic HFS parameter block.

async

A Boolean value that specifies asynchronous (TRUE) or synchronous (FALSE) execution.

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The result code of the function.
<->	ioNamePtr	StringPtr	A pointer to the volume's name.
<->	ioVRefNum	Integer	On input, a volume specification. On output, the volume reference number.
-->	ioVolIndex	Integer	An index used for indexing through all mounted volumes.
<--	ioVCrDate	LongInt	The date and time of initialization.
<--	ioVLsMod	LongInt	The date and time of last modification.
<--	ioVAtrb	Integer	The volume attributes.
<--	ioVNmFls	Integer	The number of files in the root directory.
<--	ioVBitMap	Integer	The first block of the volume bitmap.
<--	ioVAllocPtr	Integer	The block at which the next new file starts.
<--	ioVNmAlBlks	Integer	The number of allocation blocks.
<--	ioVAlBlkSiz	LongInt	The size of allocation blocks.
<--	ioVClpSiz	LongInt	The default clump size.
<--	ioAlBlSt	Integer	The first block in the volume block map.
<--	ioVNxtCNID	LongInt	The next unused catalog node ID.
<--	ioVFrBlk	Integer	The number of unused allocation blocks.
<--	ioVSigWord	Integer	The volume signature.
<--	ioVDrvInfo	Integer	The drive number.
<--	ioVDRefNum	Integer	The driver reference number.
<--	ioVFSID	Integer	The file system handling this volume.
<--	ioVBkUp	LongInt	The date and time of the last backup.
<--	ioVSeqNum	Integer	Used internally.
<--	ioVWrCnt	LongInt	The volume write count.
<--	ioVFilCnt	LongInt	The number of files on the volume.
<--	ioVDirCnt	LongInt	The number of directories on the volume.
<--	ioVFndrInfo	ARRAY[1..8] OF LongInt
			Information used by the Finder.

DESCRIPTION

The PBHGetVInfo function returns information about the specified volume. If the value of ioVolIndex is positive, the File Manager attempts to use it to find the volume; for instance, if the value of ioVolIndex is 2, the File Manager attempts to access the second mounted volume in the VCB queue. If the value of ioVolIndex is negative, the File Manager uses ioNamePtr and ioVRefNum in the standard way to determine the volume. If the value of ioVolIndex is 0, the File Manager attempts to access the volume by using ioVRefNum only. The volume reference number is returned in ioVRefNum, and the volume name is returned in the buffer whose address you passed in ioNamePtr. You should pass a pointer to a Str31 value if you want that name returned. If you pass NIL in the ioNamePtr field, no volume name is returned.

If you pass a working directory reference number in ioVRefNum (or if the default directory is a subdirectory), the number of files and directories in the specified directory (the directory's valence) is returned in ioVNmFls.

You can read the ioVDrvInfo and ioVDRefNum fields to determine whether the specified volume is online, offline, or ejected. For online volumes, ioVDrvInfo contains the drive number of the drive containing the specified volume and hence is always greater than 0. If the value returned in ioVDrvInfo is 0, the volume is either offline or ejected. You can determine whether the volume is offline or ejected by inspecting the value of the ioVDRefNum field. For online volumes, ioVDRefNum contains a driver reference number; these numbers are always less than 0. If the volume is not online, the value of ioVDRefNum is either the negative of the drive number (if the volume is offline) or the drive number itself (if the volume is ejected).

You can get information about all the online volumes by making repeated calls to PBHGetVInfo, starting with the value of ioVolIndex set to 1 and incrementing that value until PBHGetVInfo returns nsvErr.

SPECIAL CONSIDERATIONS

The values returned in the ioVNmAlBlks and ioVFrBlk fields are unsigned integers. You need to exercise special care when reading those values from Pascal. See "Determining the Amount of Free Space on a Volume" on page 2-46 for one technique you can use to read those values.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro for PBHGetVInfo is _HGetVolInfo.

RESULT CODES

noErr	0	No error
nsvErr	-35	No such volume
paramErr	-50	No default volume