Important: The information in this document is obsolete and should not be used for new development.
HFS Parameter Block
Most of the low-level HFS functions exchange information with your application using the HFS parameter block, defined by the HParamBlockRec data type.
TYPE HParamBlockRec = {HFS parameter block} RECORD qLink: QElemPtr; {next queue entry} qType: Integer; {queue type} ioTrap: Integer; {routine trap} ioCmdAddr: Ptr; {routine address} ioCompletion: ProcPtr; {pointer to completion routine} ioResult: OSErr; {result code} ioNamePtr: StringPtr; {pointer to pathname} ioVRefNum: Integer; {volume specification} CASE ParamBlkType OF ioParam: (ioRefNum: Integer; {file reference number} ioVersNum: SignedByte; {version number} ioPermssn: SignedByte; {read/write permission} ioMisc: Ptr; {miscellaneous} ioBuffer: Ptr; {data buffer} ioReqCount: LongInt; {requested number of bytes} ioActCount: LongInt; {actual number of bytes} ioPosMode: Integer; {positioning mode and newline char.} ioPosOffset: LongInt); {positioning offset} fileParam: (ioFRefNum: Integer; {file reference number} ioFVersNum: SignedByte; {file version number (unused)} filler1: SignedByte; {reserved} ioFDirIndex: Integer; {directory index} ioFlAttrib: SignedByte; {file attributes} ioFlVersNum: SignedByte; {file version number (unused)} ioFlFndrInfo: FInfo; {information used by the Finder} ioDirID: LongInt; {directory ID or file ID} ioFlStBlk: Integer; {first alloc. blk. of data fork} ioFlLgLen: LongInt; {logical EOF of data fork} ioFlPyLen: LongInt; {physical EOF of data fork} ioFlRStBlk: Integer; {first alloc. blk. of resource fork} ioFlRLgLen: LongInt; {logical EOF of resource fork} ioFlRPyLen: LongInt; {physical EOF of resource fork} ioFlCrDat: LongInt; {date and time of creation} ioFlMdDat: LongInt); {date and time of last modification} volumeParam: (filler2: LongInt; {reserved} ioVolIndex: Integer; {volume index} ioVCrDate: LongInt; {date and time of initialization} ioVLsMod: LongInt; {date and time of last modification} ioVAtrb: Integer; {volume attributes} ioVNmFls: Integer; {number of files in root directory} ioVBitMap: Integer; {first block of volume bitmap} ioAllocPtr: Integer; {first block of next new file} ioVNmAlBlks: Integer; {number of allocation blocks} ioVAlBlkSiz: LongInt; {size of allocation blocks} ioVClpSiz: LongInt; {default clump size} ioAlBlSt: Integer; {first block in volume map} ioVNxtCNID: LongInt; {next unused node ID} ioVFrBlk: Integer; {number of unused allocation blocks} ioVSigWord: Integer; {volume signature} ioVDrvInfo: Integer; {drive number} ioVDRefNum: Integer; {driver reference number} ioVFSID: Integer; {file-system identifier} ioVBkUp: LongInt; {date and time of last backup} ioVSeqNum: Integer; {used internally} ioVWrCnt: LongInt; {volume write count} ioVFilCnt: LongInt; {number of files on volume} ioVDirCnt: LongInt; {number of directories on volume} ioVFndrInfo: ARRAY[1..8] OF LongInt); {information used by the Finder} accessParam: (filler3: Integer; {reserved} ioDenyModes: Integer; {access mode information} filler4: Integer; {reserved} filler5: SignedByte; {reserved} ioACUser: SignedByte; {user access rights} filler6: LongInt; {reserved} ioACOwnerID: LongInt; {owner ID} ioACGroupID: LongInt; {group ID} ioACAccess: LongInt); {directory access rights} objParam: (filler7: Integer; {reserved} ioObjType: Integer; {function code} ioObjNamePtr: Ptr; {ptr to returned creator/group name} ioObjID: LongInt); {creator/group ID} copyParam: (ioDstVRefNum: Integer; {destination volume identifier} filler8: Integer; {reserved} ioNewName: Ptr; {pointer to destination pathname} ioCopyName: Ptr; {pointer to optional name} ioNewDirID: LongInt); {destination directory ID} wdParam: (filler9: Integer; {reserved} ioWDIndex: Integer; {working directory index} ioWDProcID: LongInt; {working directory user identifier} ioWDVRefNum: Integer; {working directory's vol. ref. num.} filler10: Integer; {reserved} filler11: LongInt; {reserved} filler12: LongInt; {reserved} filler13: LongInt; {reserved} ioWDDirID: LongInt); {working directory's directory ID} fidParam: (filler14: LongInt; {reserved} ioDestNamePtr: StringPtr; {pointer to destination filename} filler15: LongInt; {reserved} ioDestDirID: LongInt; {destination parent directory ID} filler16: LongInt; {reserved} filler17: LongInt; {reserved} ioSrcDirID: LongInt; {source parent directory ID} filler18: Integer; {reserved} ioFileID: LongInt); {file ID} csParam: (ioMatchPtr: FSSpecArrayPtr;{pointer to array of matches} ioReqMatchCount: LongInt; {max. number of matches to return} ioActMatchCount: LongInt; {actual number of matches} ioSearchBits: LongInt; {enable bits for matching rules} ioSearchInfo1: CInfoPBPtr; {pointer to values and lower bounds} ioSearchInfo2: CInfoPBPtr; {pointer to masks and upper bounds} ioSearchTime: LongInt; {maximum time to search} ioCatPosition: CatPositionRec;{current catalog position} ioOptBuffer: Ptr; {pointer to optional read buffer} ioOptBufSize: LongInt); {length of optional read buffer} foreignPrivParam: (filler21: LongInt; {reserved} filler22: LongInt; {reserved} ioForeignPrivBuffer: Ptr; {privileges data buffer} ioForeignPrivReqCount: LongInt; {size of buffer} ioForeignPrivActCount: LongInt; {amount of buffer used} filler23: LongInt; {reserved} ioForeignPrivDirID: LongInt; {parent directory ID of } { foreign file or directory} ioForeignPrivInfo1: LongInt; {privileges data} ioForeignPrivInfo2: LongInt; {privileges data} ioForeignPrivInfo3: LongInt; {privileges data} ioForeignPrivInfo4: LongInt); {privileges data} END;The first eight fields are common to all ten variants. Each variant also includes its own unique fields.Field descriptions common to all variants
Field descriptions for the
qLink
- A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.)
qType
- The queue type. (This field is used internally by the File Manager.)
ioTrap
- The trap number of the routine that was called. (This field is used internally by the File Manager.)
ioCmdAddr
- The address of the routine that was called. (This field is used internally by the File Manager.)
ioCompletion
- A pointer to a completion routine to be executed at the end of an asynchronous call. It should be
NIL
for asynchronous calls with
no completion routine and is automatically set toNIL
for all synchronous calls. See "Completion Routines" on page 2-238 for information about completion routines.ioResult
- The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field; it's set to a positive number when
the call is made and receives the actual result code when the call
is completed.ioNamePtr
- A pointer to a pathname. Whenever a routine description specifies that
ioNamePtr
is used--whether for input, output, or both--it's very important that you set this field to point to storage for aStr255
value (if you're using a pathname) or toNIL
(if you're not).ioVRefNum
- A volume specification (volume reference number, working directory reference number, drive number, or 0 for default volume).
ioParam
variant
- ioRefNum
- The file reference number of an open file.
ioVersNum
- A version number. This field is no longer used and you should always set it to 0.
ioPermssn
- The access mode.
ioMisc
- Depends on the routine called. This field contains either a new logical end-of-file, a new version number, a pointer to an access path buffer, or a pointer to a new pathname. Because
ioMisc
is of typePtr
, you'll need to perform type coercion to interpret the value ofioMisc
correctly when it contains an end-of-file (aLongInt
value) or version number (aSignedByte
value).ioBuffer
- A pointer to a data buffer into which data is written by
_Read
calls and from which data is read by_Write
calls.ioReqCount
- The requested number of bytes to be read, written, or allocated.
ioActCount
- The number of bytes actually read, written, or allocated.
ioPosMode
- The positioning mode for setting the mark. Bits 0 and 1 of this field indicate how to position the mark; you can use the following predefined constants to set or test their value:
CONST fsAtMark = 0; {at current mark} fsFromStart = 1; {from beginning of file} fsFromLEOF = 2; {from logical end-of-file} fsFromMark = 3; {relative to current mark}
- You can set bit 4 of the
ioPosMode
field to request that the data be cached, and you can set bit 5 to request that the data not be cached. You can set bit 6 to request that any data written be immediately read; this ensures that the data written to a volume exactly matches the data in memory. To request a read-verify operation, add the following constant to the positioning mode:CONST rdVerify = 64; {use read-verify mode}Field descriptions for the
- You can set bit 7 to read a continuous stream of bytes, and place the ASCII code of a newline character in the high-order byte to terminate a read operation at the end of a line.
ioPosOffset
- The offset to be used in conjunction with the positioning mode.
fileParam
variant
Field descriptions for the
ioFRefNum
- The file reference number of an open file.
ioFVersNum
- A file version number. This field is no longer used and you should always set it to 0.
filler1
- Reserved.
ioFDirIndex
- An index for use with the
PBHGetFInfo
function.ioFlAttrib
- File attributes. The bits in this field have these meanings:
Bit Meaning 0 Set if file is locked 2 Set if resource fork is open 3 Set if data fork is open 4 Set if a directory 7 Set if file (either fork) is open ioFlVersNum
- A file version number. This field is no longer used and you should always set it to 0.
ioFlFndrInfo
- Information used by the Finder.
ioDirID
- A directory ID.
ioFlStBlk
- The first allocation block of the data fork. This field contains 0 if the file's data fork is empty.
ioFlLgLen
- The logical end-of-file of the data fork.
ioFlPyLen
- The physical end-of-file of the data fork.
ioFlRStBlk
- The first allocation block of the resource fork.
ioFlRLgLen
- The logical end-of-file of the resource fork.
ioFlRPyLen
- The physical end-of-file of the resource fork.
ioFlCrDat
- The date and time of the file's creation, specified in seconds since midnight, January 1, 1904.
ioFlMdDat
- The date and time of the last modification to the file, specified in seconds since midnight, January 1, 1904.
volumeParam
variant
Field descriptions for the
filler2
- Reserved.
ioVolIndex
- An index for use with the
PBHGetVInfo
function.ioVCrDate
- The date and time of volume initialization.
ioVLsMod
- The date and time the volume information was last modified. (This field is not changed when information is written to a file and does not necessarily indicate when the volume was flushed.)
ioVAtrb
- The volume attributes.
ioVNmFls
- The number of files in the root directory.
ioVBitMap
- The first block of the volume bitmap.
ioAllocPtr
- The block at which the next new file starts. Used internally.
ioVNmAlBlks
- The number of allocation blocks.
ioVAlBlkSiz
- The size of allocation blocks.
ioVClpSiz
- The clump size.
ioAlBlSt
- The first block in the volume map.
ioVNxtCNID
- The next unused catalog node ID.
ioVFrBlk
- The number of unused allocation blocks.
ioVSigWord
- A signature word identifying the type of volume; it's $D2D7 for MFS volumes and $4244 for volumes that support HFS calls.
ioVDrvInfo
- The drive number of the drive containing the volume.
ioVDRefNum
- For online volumes, the reference number of the I/O driver for the drive identified by
ioVDrvInfo
.ioVFSID
- The file-system identifier. It indicates which file system is servicing the volume; it's zero for File Manager volumes and nonzero for volumes handled by an external file system.
ioVBkUp
- The date and time the volume was last backed up (it's 0 if never backed up).
ioVSeqNum
- Used internally.
ioVWrCnt
- The volume write count.
ioVFilCnt
- The total number of files on the volume.
ioVDirCnt
- The total number of directories (not including the root directory) on the volume.
ioVFndrInfo
- Information used by the Finder.
accessParam
variant
Field descriptions for the
filler3
- Reserved.
ioDenyModes
- Access mode information. The bits in this field have these meanings:
Bit Meaning 0 If set, request read permission 1 If set, request write permission 2-3 Reserved; must be 0 4 If set, deny other readers access to this file 5 If set, deny other writers access to this file 6-15 Reserved; must be 0 filler4
- Reserved.
filler5
- Reserved.
ioACUser
- The user's access rights for the specified directory. The bits in this field have the following meanings:
Bit Meaning 0 Set if user does not have See Folder privileges 1 Set if user does not have See Files privileges 2 Set if user does not have Make Changes privileges 3-6 Reserved; always set to 0 7 Set if user is not owner of the directory filler6
- Reserved.
ioACOwnerID
- The owner ID.
ioACGroupID
- The group ID.
ioACAccess
- The directory access privileges. See the section "Directory Access Privileges," beginning on page 2-18, for a complete description of this field.
objParam
variant
Field descriptions for the
filler7
- Reserved.
ioObjType
- A function code. The values passed in this field are determined by the routine to which you pass this parameter block.
ioObjNamePtr
- A pointer to the returned creator/group name.
ioObjID
- The creator/group ID.
copyParam
variant
Field descriptions for the
ioDstVRefNum
- A volume reference number for the destination volume.
filler8
- Reserved.
ioNewName
- A pointer to the destination pathname.
ioCopyName
- A pointer to an optional name.
ioNewDirID
- A destination directory ID.
wdParam
variant
Field descriptions for the
filler9
- Reserved.
ioWDIndex
- An index to working directories.
ioWDProcID
- The working directory user identifier.
ioWDVRefNum
- The volume reference number for the working directory.
filler10
- Reserved.
filler11
- Reserved.
filler12
- Reserved.
filler13
- Reserved.
ioWDDirID
- The working directory's directory ID.
fidParam
variant
Field descriptions for the
filler14
- Reserved.
ioDestNamePtr
- A pointer to the name of the destination file.
filler15
- Reserved.
ioDestDirID
- The parent directory ID of the destination file.
filler16
- Reserved.
filler17
- Reserved.
ioSrcDirID
- The parent directory ID of the source file.
filler18
- Reserved.
ioFileID
- The file ID.
csParam
variant
Field descriptions for the
ioMatchPtr
- A pointer to an array of
FSSpec
records in which the file and directory names that match the selection criteria are returned. The array must be large enough to hold the largest possible number ofFSSpec
records, as determined by theioReqMatchCount
field.ioReqMatchCount
The maximum number of matches to return. This number should be the number ofFSSpec
records that will fit in the memory pointed to byioMatchPtr
. You can use this field to avoid a possible excess of matches for criteria that prove to be too general (or to limit the length of a search if theioSearchTime
field isn't used).ioActMatchCount
The number of actual matches found.ioSearchBits
- The fields of the parameter blocks
ioSearchInfo1
andioSearchInfo2
that are relevant to the search. See "Searching a Volume" beginning on page 2-38 for constants you can add to determine a value forioSearchBits
.ioSearchInfo1
- A pointer to a
CInfoPBRec
parameter block that contains values and the lower bounds of ranges for the fields selected byioSearchBits
.ioSearchInfo2
- A pointer to a second
CInfoPBRec
parameter block that contains masks and upper bounds of ranges for the fields selected byioSearchBits
.ioSearchTime
- A time limit on a search, in Time Manager format. Use this field to limit the run time of a single call to
PBCatSearch
. A value of 0 imposes no time limit. If the value of this field is positive, it is interpreted as milliseconds. If the value of this field is negative, it is interpreted as negated microseconds.ioCatPosition
- A position in the catalog where searching should begin. Use this field to keep an index into the catalog when breaking down the
PBCatSearch
search into a number of smaller searches. This field is valid wheneverPBCatSearch
exits because it either spends the maximum time allowed byioSearchTime
or finds the maximum number of matches allowed byioReqMatchCount
.- To start at the beginning of the catalog, set the
initialize
field ofioCatPosition
to 0. Before exiting after an interrupted search,PBCatSearch
sets that field to the next catalog entry to
be searched.- To resume where the previous call stopped, pass the entire
CatPosition
record returned by the previous call as input
to the next.ioOptBuffer
- A pointer to an optional read buffer. The
ioOptBuffer
andioOptBufSize
fields let you specify a part of memory as a read buffer, increasing search speed.ioOptBufSize
- The size of the buffer pointed to by
ioOptBuffer
. Buffer size effectiveness varies with models and configurations, but a 16 KB buffer is likely to be optimal. The size should be at least 1024 bytes and should be an integral multiple of 512 bytes.foreignPrivParam
variant
filler21
- Reserved.
filler22
- Reserved.
- ioForeignPrivBuffer
- A pointer to a buffer containing access-control information about the foreign file system.
- ioForeignPrivReqCount
- The size of the buffer pointed to by the ioForeignPrivBuffer field.
- ioForeignPrivActCount
- The amount of the buffer pointed to by the ioForeignPrivBuffer field that was actually used to hold data.
filler23
- Reserved.
- ioForeignPrivDirID
- The parent directory ID of the foreign file or directory.
- ioForeignPrivInfo1
A long word that may contain privileges data.- ioForeignPrivInfo2
A long word that may contain privileges data.- ioForeignPrivInfo3
A long word that may contain privileges data.- ioForeignPrivInfo4
A long word that may contain privileges data.
© Apple Computer, Inc.
2 JUL 1996