Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Chapter 2 - File Manager / File Manager Reference

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

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 to NIL 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 a Str255 value (if you're using a pathname) or to NIL (if you're not).
ioVRefNum
A volume specification (volume reference number, working directory reference number, drive number, or 0 for default volume).
Field descriptions for the 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 type Ptr, you'll need to perform type coercion to interpret the value of ioMisc correctly when it contains an end-of-file (a LongInt value) or version number (a SignedByte 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}
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.
Field descriptions for the fileParam variant

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.
Field descriptions for the volumeParam variant

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.
Field descriptions for the accessParam variant

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.
Field descriptions for the objParam variant

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.
Field descriptions for the copyParam variant

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.
Field descriptions for the wdParam variant

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.
Field descriptions for the fidParam variant

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.
Field descriptions for the csParam variant

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 of FSSpec records, as determined by the ioReqMatchCount field.
ioReqMatchCount

The maximum number of matches to return. This number should be the number of FSSpec records that will fit in the memory pointed to by ioMatchPtr. 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 the ioSearchTime field isn't used).
ioActMatchCount

The number of actual matches found.
ioSearchBits
The fields of the parameter blocks ioSearchInfo1 and ioSearchInfo2 that are relevant to the search. See "Searching a Volume" beginning on page 2-38 for constants you can add to determine a value for ioSearchBits.
ioSearchInfo1
A pointer to a CInfoPBRec parameter block that contains values and the lower bounds of ranges for the fields selected by ioSearchBits.
ioSearchInfo2
A pointer to a second CInfoPBRec parameter block that contains masks and upper bounds of ranges for the fields selected by ioSearchBits.
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 whenever PBCatSearch exits because it either spends the maximum time allowed by ioSearchTime or finds the maximum number of matches allowed by ioReqMatchCount.

To start at the beginning of the catalog, set the initialize
field of ioCatPosition 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 and ioOptBufSize 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.
Field descriptions for the 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

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

Mailing Lists

RSS Feeds

Copyright © 2016 Apple Inc. All rights reserved.

Terms of Use

Privacy Policy

	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

	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

	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