Legacy Document

Inside Macintosh: Files /

Chapter 2 - File Manager / File Manager Reference

Low-Level HFS Routines / Accessing Information About Files and Directories

PBGetCatInfo

You can use the PBGetCatInfo function to get information about the files and directories in a file catalog.

FUNCTION PBGetCatInfo (paramBlock: CInfoPBPtr; async: Boolean): 
                        OSErr;

paramBlock

A pointer to a catalog information parameter block.

async

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

for files

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The result code of the function.
<->	ioNamePtr	StringPtr	A pointer to a pathname.
-->	ioVRefNum	Integer	A volume specification.
<--	ioFRefNum	Integer	A file reference number.
-->	ioFDirIndex	Integer	An index.
<--	ioFlAttrib	SignedByte	The file attributes.
<--	ioFlFndrInfo	FInfo	Information used by the Finder.
<->	ioDirID	LongInt	On input, a directory ID. On output, a file ID.
<--	ioFlStBlk	Integer	The first allocation block of the data fork.
<--	ioFlLgLen	LongInt	The logical end-of-file of the data fork.
<--	ioFlPyLen	LongInt	The physical end-of-file of the data fork.
<--	ioFlRStBlk	Integer	The first allocation block of the resource fork.
<--	ioFlRLgLen	LongInt	The logical end-of-file of the resource fork.
<--	ioFlRPyLen	LongInt	The physical end-of-file of the resource fork.
<--	ioFlCrDat	LongInt	The date and time of creation.
<--	ioFlMdDat	LongInt	The date and time of the last modification.
<--	ioFlBkDat	LongInt	The date and time of the last backup.
<--	ioFlXFndrInfo	FXInfo	Additional information used by the Finder.
<--	ioFlParID	LongInt	The directory ID of the parent directory.
<--	ioFlClpSiz	LongInt	The file's clump size.

for directories

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The result code of the function.
<->	ioNamePtr	StringPtr	A pointer to a pathname.
-->	ioVRefNum	Integer	A volume specification.
-->	ioFDirIndex	Integer	An index.
<--	ioFlAttrib	SignedByte	The directory attributes.
<--	ioACUser	SignedByte	The directory access rights.
<--	ioDrUsrWds	DInfo	Information used by the Finder.
<->	ioDrDirID	LongInt	The directory ID.
<--	ioDrNmFls	Integer	The number of files in the directory.
<--	ioDrCrDat	LongInt	The date and time of creation.
<--	ioDrMdDat	LongInt	The date and time of the last modification.
<--	ioDrBkDat	LongInt	The date and time of the last backup.
<--	ioDrFndrInfo	DXInfo	Additional information used by the Finder.
<--	ioDrParID	LongInt	The directory ID of the parent directory.

DESCRIPTION

The PBGetCatInfo function returns information about a file or directory, depending on the values you specify in the ioFDirIndex, ioNamePtr, ioVRefNum, and ioDirID or ioDrDirID fields. If you need to determine whether the information returned is for a file or a directory, you can test bit 4 of the ioFlAttrib field; if that bit is set, the information returned describes a directory.

The PBGetCatInfo function selects a file or directory according to these rules:

• If the value of ioFDirIndex is positive, PBGetCatInfo returns information about the file or directory whose directory index is ioFDirIndex in the directory specified by ioVRefNum (this will be the root directory if a volume reference number is provided).
• If the value of ioFDirIndex is 0, PBGetCatInfo returns information about the file or directory specified by ioNamePtr in the directory specified by ioVRefNum (again, this will be the root directory if a volume reference number is provided).
• If the value of ioFDirIndex is negative, PBGetCatInfo ignores ioNamePtr and returns information about the directory specified by ioDrDirID.

With files, PBGetCatInfo is similar to PBHGetFInfo but returns some additional information. If the file is open, the reference number of the first access path found is returned in ioFRefNum, and the name of the file is returned in ioNamePtr (unless ioNamePtr is NIL). The file's attributes are returned in the ioFlAttrib field. See
the description of the fields of the CInfoPBRec data type (beginning on page 2-100)
for the meaning of the bits in this field.

Note

When you get information about a file, the ioDirID field contains the file ID on exit from PBGetCatInfo. You might need to save the value of ioDirID before calling PBGetCatInfo if you make subsequent calls with the same parameter block.

With directories, PBGetCatInfo returns information such as the directory attributes and, for server volumes, the directory access privileges of the user. The directory attributes are encoded by bits in the ioFlAttrib field and have these meanings:

Bit	Meaning
0	Set if the directory is locked
1	Reserved
2	Set if the directory is within a shared area of the directory hierarchy
3	Set if the directory is a share point that is mounted by some user
4	Set if the item is a directory
5	Set if the directory is a share point
6-7	Reserved

Note

These bits in the ioFlAttrib field for directories are read-only.
You cannot alter directory attributes by setting these bits using PBSetCatInfo. Instead, you can call PBHSetFLock and PBHRstFLock to lock and unlock a directory, and PBShare
and PBUnshare to enable and disable file sharing on local
directories.

The PBGetCatInfo function returns the directory access rights in the ioACUser
field only for shared volumes. As a result, you should set this field to 0 before
calling PBGetCatInfo.

You can also use PBGetCatInfo to determine whether a file has a file ID reference.
The value of the file ID is returned in the ioDirID field. Because that parameter could also represent a directory ID, call PBResolveFileIDRef to see if the value is a real
file ID. If you want to determine whether a file ID reference exists for a file and create one if it doesn't, use PBCreateFileIDRef, which will either create a file ID or
return fidExists.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for PBGetCatInfo are

Trap macro	Selector
_HFSDispatch	$0009

RESULT CODES

noErr	0	No error
nsvErr	-35	No such volume
ioErr	-36	I/O error
bdNamErr	-37	Bad filename
fnfErr	-43	File not found
paramErr	-50	No default volume
dirNFErr	-120	Directory not found or incomplete pathname
afpAccessDenied	-5000	User does not have the correct access
afpObjectTypeErr	-5025	Directory not found or incomplete pathname