File Manager Reference

Framework	CoreServices/CoreServices.h
Declared in	Files.h hfs_format.h

Overview

The File Manager was a core service in OS X that managed the organization, reading, and writing of data located on physical data storage devices such as disk drives. The File Manager was designed to provide an abstraction layer that hides lower-level implementation details such as different file systems and volume formats. For legacy apps that needed to have the same view of the file system seen in the OS X user interface, the File Manager was an appropriate tool. For example, the File Manager was often used in application frameworks such as Carbon and Cocoa to implement file-related operations.

A number of deprecated functions in the File Manager were inherited from earlier versions of Mac OS and have been carried along to facilitate porting legacy applications to OS X. You should avoid using these deprecated functions. In particular, you should avoid any function or data structure that uses the FSSpec data type. This reference document clearly marks every deprecated function and, in most cases, provides a recommended replacement.

Functions by Task

Accessing Information About Files and Directories

Accessing the Desktop Database

Allocating Storage for Files

Changing File Permissions, ACLs, and Ownership

Closing Files

Comparing File System References

Controlling Directory Access

Controlling Login Access

Converting Between Paths and FSRef Structures

Copying and Moving Files

Copying and Moving Objects Using Asynchronous High-Level File Operations

Copying and Moving Objects Using Synchronous High-Level File Operations

Creating a File System Reference (FSRef)

Creating and Deleting File ID References

Creating and Deleting Named Forks

Creating Directories

Creating FSFileSecurity Objects

Creating File System Specifications

Creating Files

Creating, Calling, and Deleting Universal Procedure Pointers

Deleting Files and Directories

Determining the Unicode Names of the Data and Resource Forks

Exchanging the Contents of Two Files

Getting and Setting Volume Information

Getting Volume Attributes

Iterating Over Named Forks

Locking and Unlocking File Ranges

Locking and Unlocking Files and Directories

Manipulating File and Fork Size

Manipulating File Position

Manipulating the Default Volume

Mounting and Unmounting Volumes

Mounting Remote Volumes

Moving, Renaming, or Replacing Files or Directories

Obtaining File and Directory Information Using a Catalog Iterator on HFS Plus Volumes

Obtaining File Control Block Information

Obtaining File Permissions, ACLs, and Ownership Information

Obtaining Fork Control Block Information

Opening Files

Opening Files While Denying Access

Reading and Writing Files

Resolving File ID References

Searching a Volume

Searching a Volume Using a Catalog Iterator

Updating Files

Updating Volumes

Using Change Notifications

Not Recommended

This section lists functions that are not recommended and you should no longer use.

Callbacks by Task

File Operation Callbacks

Miscellaneous Callbacks

Callbacks

FNSubscriptionProcPtr

Callback delivered for directory notifications.

typedef void (*FNSubscriptionProcPtr) (
   FNMessage message,
   OptionBits flags,
   void * refcon,
   FNSubscriptionRef subscription
);

If you name your function MyFNSubscriptionProc, you would declare it like this:

void MyFNSubscriptionProc (
   FNMessage message,
   OptionBits flags,
   void * refcon,
   FNSubscriptionRef subscription
);

Parameters

message: An indication of what happened.
flags: Options regarding the delivery of the notification; typically kNilOptions.
refcon: A pointer to a user reference supplied with subscription.
subscription: A subscription corresponding to this notification.

Availability

Available in OS X v10.1 and later.

Declared In

Files.h

FSFileOperationStatusProcPtr

Defines a status callback function for an asynchronous file operation on an FSRef object.

typedef void (*FSFileOperationStatusProcPtr) (
   FSFileOperationRef fileOp,
   const FSRef *currentItem,
   FSFileOperationStage stage,
   OSStatus error,
   CFDictionaryRef statusDictionary,
   void *info
);

If you name your function MyFSFileOperationStatusProc, you would declare it like this:

void MyFSFileOperationStatusProc (
   FSFileOperationRef fileOp,
   const FSRef *currentItem,
   FSFileOperationStage stage,
   OSStatus error,
   CFDictionaryRef statusDictionary,
   void *info
);

Parameters

fileOp: The file operation.
currentItem: A pointer to an FSRef variable. On output, the variable contains the object currently being moved or copied. If the operation is complete, this parameter refers to the target (the new object corresponding to the source object in the destination directory).
stage: The current stage of the operation.
error: The current error status of the operation.
statusDictionary: A dictionary with more detailed status information. For information about the contents of the dictionary, see “File Operation Status Dictionary Keys”. You are not responsible for releasing the dictionary.
info: A pointer to user-defined data associated with this operation.

Discussion

When you call FSCopyObjectAsync, FSMoveObjectAsync, or FSMoveObjectToTrashAsync, you can specify a status callback function of this type. The function you provide is called by the File Manager whenever the file operation changes stages (including failing due to an error), or as updated information is available limited by the status change interval of the operation. If you need to save any of the status information beyond the scope of the callback, you should make a copy of the information.

Availability

Available in OS X v10.4 and later.

Declared In

Files.h

FSPathFileOperationStatusProcPtr

Defines a status callback function for an asynchronous file operation on an object specified with a pathname.

typedef void (*FSPathFileOperationStatusProcPtr) (
   FSFileOperationRef fileOp,
   const char *currentItem,
   FSFileOperationStage stage,
   OSStatus error,
   CFDictionaryRef statusDictionary,
   void *info
);

If you name your function MyFSPathFileOperationStatusProc, you would declare it like this:

void MyFSPathFileOperationStatusProc (
   FSFileOperationRef fileOp,
   const char *currentItem,
   FSFileOperationStage stage,
   OSStatus error,
   CFDictionaryRef statusDictionary,
   void *info
);

Parameters

fileOp: The file operation.
currentItem: The UTF-8 pathname of the object currently being moved or copied. If the operation is complete, this parameter refers to the target (the new object corresponding to the source object in the destination directory).
stage: The current stage of the operation.
error: The current error status of the operation.
statusDictionary: A dictionary with more detailed status information. For information about the contents of the dictionary, see “File Operation Status Dictionary Keys”. You are not responsible for releasing the dictionary.
info: A pointer to user-defined data associated with this operation.

Discussion

When you call FSPathCopyObjectAsync, FSPathMoveObjectAsync, or FSPathMoveObjectToTrashAsync, you can specify a status callback function of this type. The function you provide is called by the File Manager whenever the file operation changes stages (including failing due to an error), or as updated information is available limited by the status change interval of the operation. If you need to save any of the status information beyond the scope of the callback, you should make a copy of the information.

Availability

Available in OS X v10.4 and later.

Declared In

Files.h

FSVolumeEjectProcPtr

typedef void (*FSVolumeEjectProcPtr) (
   FSVolumeOperation volumeOp,
   void * clientData,
   OSStatus err,
   FSVolumeRefNum volumeRefNum,
   pid_t dissenter
);

If you name your function MyFSVolumeEjectProc, you would declare it like this:

void MyFSVolumeEjectProc (
   FSVolumeOperation volumeOp,
   void * clientData,
   OSStatus err,
   FSVolumeRefNum volumeRefNum,
   pid_t dissenter
);

Parameters

volumeOp
clientData
err
volumeRefNum
dissenter

Availability

Available in OS X v10.2 and later.

Declared In

Files.h

FSVolumeMountProcPtr

typedef void (*FSVolumeMountProcPtr) (
   FSVolumeOperation volumeOp,
   void * clientData,
   OSStatus err,
   FSVolumeRefNum mountedVolumeRefNum
);

If you name your function MyFSVolumeMountProc, you would declare it like this:

void MyFSVolumeMountProc (
   FSVolumeOperation volumeOp,
   void * clientData,
   OSStatus err,
   FSVolumeRefNum mountedVolumeRefNum
);

Parameters

volumeOp
clientData
err
mountedVolumeRefNum

Availability

Available in OS X v10.2 and later.

Declared In

Files.h

FSVolumeUnmountProcPtr

typedef void (*FSVolumeUnmountProcPtr) (
   FSVolumeOperation volumeOp,
   void * clientData,
   OSStatus err,
   FSVolumeRefNum volumeRefNum,
   pid_t dissenter
);

If you name your function MyFSVolumeUnmountProc, you would declare it like this:

void MyFSVolumeUnmountProc (
   FSVolumeOperation volumeOp,
   void * clientData,
   OSStatus err,
   FSVolumeRefNum volumeRefNum,
   pid_t dissenter
);

Parameters

volumeOp
clientData
err
volumeRefNum
dissenter

Availability

Available in OS X v10.2 and later.

Declared In

Files.h

IOCompletionProcPtr

Defines a pointer to a completion function. Your completion function is executed by the File Manager after the completion of an asynchronous File Manager function call.

typedef void (*IOCompletionProcPtr) (
   ParmBlkPtr paramBlock
);

If you name your function MyIOCompletionProc, you would declare it like this:

void MyIOCompletionProc (
   ParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the parameter block that was passed to the asynchronous File Manager function.

Return Value

Discussion

When you execute an asynchronous File Manager function (an Async function), you can specify a completion routine by passing the routine’s address in the ioCompletion field of the parameter block passed to the function. Because you requested asynchronous execution, the File Manager places an I/O request in the file I/O queue and returns control to your application—possibly even before the actual I/O operation is completed. The File Manager takes requests from the queue one at a time and processes them meanwhile, your application is free to do other processing.

A function executed asynchronously returns control to your application with the result code noErr as soon as the call is placed in the file I/O queue. This result code does not indicate that the call has successfully completed, but simply indicates that the call was successfully placed in the queue. To determine when the call is actually completed, you can inspect the ioResult field of the parameter block. This field is set to a positive number when the call is made and set to the actual result code when the call is completed. If you specify a completion routine, it is executed after the result code is placed in ioResult.

The File Manager, when the File Sharing or AppleShare file server is active, will execute requests in arbitrary order. That means that if there is a request that depends on the completion of a previous request, it is an error for your program to issue the second request until the completion of the first request. For example, issuing a write request and then issuing a read request for the same data isn't guaranteed to read back what was written unless the read request isn't made until after the write request completes.

Request order can also change if a call results in a disk switch dialog to bring an offline volume back online.

Special Considerations

Because a completion routine is executed at interrupt time, it should not allocate, move, or purge memory (either directly or indirectly) and should not depend on the validity of handles to unlocked blocks.

If your completion routine uses application global variables, it must also ensure that register A5 contains the address of the boundary between your application global variables and your application parameters.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

Data Types

AccessParam

Defines a parameter block used by low-level HFS file and directory access rights manipulation functions.

struct AccessParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   short filler3;
   short ioDenyModes;
   short filler4;
   SInt8 filler5;
   SInt8 ioACUser;
   long filler6;
   long ioACOwnerID;
   long ioACGroupID;
   long ioACAccess;
   long ioDirID;
};
typedef struct AccessParam AccessParam;
   typedef AccessParam * AccessParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).
ioVRefNum: A volume reference number, 0 for the default volume, or a drive number.
filler3: Reserved.
ioDenyModes: Access mode information.
filler4: Reserved.
filler5: Reserved.
ioACUser: The user’s access rights for the specified directory.
filler6: Reserved.
ioACOwnerID: The owner ID.
ioACGroupID: The group ID.
ioACAccess: The directory access privileges.
ioDirID

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

AFPAlternateAddress

Defines a block of tagged addresses for AppleShare clients.

struct AFPAlternateAddress {
   UInt8 fVersion;
   UInt8 fAddressCount;
   UInt8 fAddressList[1];
};
typedef struct AFPAlternateAddress AFPAlternateAddress;

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

AFPTagData

Defines a structure which contains tagged address information for AppleShare clients.

struct AFPTagData {
   UInt8 fLength;
   UInt8 fType;
   UInt8 fData[1];
};
typedef struct AFPTagData AFPTagData;

Fields

fLength: The length, in bytes, of this data tag, including the fLength field itself. See “AFP Tag Length Constants.”
fType: The type of the data tag. See “AFP Tag Type Constants” for the constants which you can use here.
fData: Variable length data, containing the address.

Discussion

The new tagged data format for addressing allows for changes in addressing formats, allowing AppleShare clients to support new addressing standards without changing the interface. The AFPAlternateAddress data structure uses the AFPTagData structure to specify a tagged address.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

AFPVolMountInfo

Defines a volume mounting structure for an AppleShare server.

struct AFPVolMountInfo {
   short length;
   VolumeType media;
   short flags;
   SInt8 nbpInterval;
   SInt8 nbpCount;
   short uamType;
   short zoneNameOffset;
   short serverNameOffset;
   short volNameOffset;
   short userNameOffset;
   short userPasswordOffset;
   short volPasswordOffset;
   char AFPData[144];
};
typedef struct AFPVolMountInfo AFPVolMountInfo;
   typedef AFPVolMountInfo * AFPVolMountInfoPtr;

Fields

length: The length of the AFPVolMountInfo structure (that is, the total length of the structure header described here plus the variable-length location data).
media: The volume type of the remote volume. The value AppleShareMediaType (a constant that translates to 'afpm') represents an AppleShare volume.
flags: If bit 0 is set, no greeting message from the server is displayed.
nbpInterval: The NBP retransmit interval, in units of 8 ticks.
nbpCount: The NBP retransmit count. This field specifies the total number of times a packet should be transmitted, including the first transmission.
uamType: The user authentication method used by the remote volume. AppleShare uses four methods, defined by the constants described in “Authentication Method Constants.”
zoneNameOffset: The offset in bytes from the beginning of the structure to the entry in the AFPData field containing the name (as a pascal string) of the AppleShare zone.
serverNameOffset: The offset in bytes from the beginning of the structure to the entry in the AFPData field containing the name (as a pascal string) of the AppleShare server.
volNameOffset: The offset in bytes from the beginning of the structure to the entry in the AFPData field containing the name (as a pascal string) of the volume.
userNameOffset: The offset in bytes from the beginning of the structure to the entry in the AFPData field containing the name (as a pascal string) of the user.
userPasswordOffset: The offset in bytes from the beginning of the structure to the entry in the AFPData field containing the user’s password (as a pascal string).
volPasswordOffset: The offset in bytes from the beginning of the structure to the entry in the AFPData field containing the volume’s password (as a pascal string). Some versions of the AppleShare software do not pass the information in this field to the server.
AFPData: The actual volume mounting information, offsets to which are contained in the preceding six fields. To mount an AFP volume, you must fill in the structure with at least the zone name, server name, user name, user password, and volume password. You can lay out the data in any order within this data field, as long as you specify the correct offsets in the offset fields.

Discussion

The only volumes that currently support the programmatic mounting functions are AppleShare servers, which use a volume mounting structure of type AFPVolMountInfo.

To mount an AppleShare server, fill out an AFPVolMountInfo structure using the PBGetVolMountInfo function and then pass this structure to the PBVolumeMount function to mount the volume.

Version Notes

AppleShare clients prior to version 3.7 mount volumes over AppleTalk only. For maximum compatibility set the uamType field to 1 for guest login or 3 for login using a password.

To mount volumes using IP addresses and other address formats, use the AFPXVolMountInfo structure.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

AFPXVolMountInfo

Defines a volume mounting structure for an AppleShare server, for AppleShare 3.7 and later.

struct AFPXVolMountInfo {
   short length;
   VolumeType media;
   short flags;
   SInt8 nbpInterval;
   SInt8 nbpCount;
   short uamType;
   short zoneNameOffset;
   short serverNameOffset;
   short volNameOffset;
   short userNameOffset;
   short userPasswordOffset;
   short volPasswordOffset;
   short extendedFlags;
   short uamNameOffset;
   short alternateAddressOffset;
   char AFPData[176];
};
typedef struct AFPXVolMountInfo AFPXVolMountInfo;
   typedef AFPXVolMountInfo * AFPXVolMountInfoPtr;

Fields

length: The length of the AFPXVolMountInfo structure (that is, the total length of the structure header described here plus the variable-length location data).
media: The volume type of the remote volume. The value AppleShareMediaType (a constant that translates to 'afpm') represents an AppleShare volume.
flags: Volume mount flags. See “Volume Mount Flags” for a description of the bits in this field. In order to use the new features of the extended AFP volume mount structure, you must set the volMountExtendedFlagsBit bit.
nbpInterval: The NBP retransmit interval, in units of 8 ticks.
nbpCount: The NBP retransmit count. This field specifies the total number of times a packet should be transmitted, including the first transmission.
uamType: The user authentication method used by the remote volume. AppleShare uses four methods, defined by the constants described in “Authentication Method Constants.”
zoneNameOffset: The offset in bytes from the beginning of the structure to the entry in the AFPData field containing the name (as a pascal string) of the AppleShare zone.
serverNameOffset: The offset in bytes from the beginning of the structure to the entry in the AFPData field containing the name (as a pascal string) of the AppleShare server.
volNameOffset: The offset in bytes from the beginning of the structure to the entry in the AFPData field containing the name (as a pascal string) of the volume.
userNameOffset: The offset in bytes from the beginning of the structure to the entry in the AFPData field containing the name (as a pascal string) of the user.
userPasswordOffset: The offset in bytes from the beginning of the structure to the entry in the AFPData field containing the user’s password (as a pascal string).
volPasswordOffset: The offset in bytes from the beginning of the structure to the entry in the AFPData field containing the volume’s password (as a pascal string). Some versions of the AppleShare software do not pass the information in this field to the server.
extendedFlags: Extended flags. See “Extended AFP Volume Mounting Information Flag.”
uamNameOffset: The offset in bytes from the beginning of the structure to the entry in the AFPData field containing the user authentication module name (as a pascal string).
alternateAddressOffset: The offset in bytes from the beginning of the structure to the entry in the AFPData field containing IP addresses, specified as a block of tagged data. This block of tagged data begins with a version byte and a count byte, followed by up to 255 tagged addresses. See AFPAlternateAddress.
AFPData: The actual volume mounting information, offsets to which are contained in the preceding fields. To mount an AFP volume, you must fill in the structure with at least the zone name, server name, user name, user password, and volume password. You can lay out the data in any order within this data field, as long as you specify the correct offsets in the offset fields.

Discussion

To mount an AppleShare server, fill out an AFPXVolMountInfo structure using the PBGetVolMountInfo function and then pass this structure to the PBVolumeMount function to mount the volume.

The extended AFP volume mount information structure requires AppleShare client 3.7 and later. The new fields and flag bits allow you to specify the information needed to support TCP/IP and User Authentication Modules.

Note that, for all fields specifying an offset, if you wish to leave the string field in the AFPData field empty, you must specify an empty string and have the offset in the corresponding offset field point to that empty string. You cannot simply pass 0 as the offset.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

CatPositionRec

Defines a catalog position structure, which maintains the current position of a catalog search between calls to PBCatSearchSync or PBCatSearchAsync.

struct CatPositionRec {
   long initialize;
   short priv[6];
};
typedef struct CatPositionRec CatPositionRec;

Fields

initialize: The starting point of the catalog search. To start searching at the beginning of a catalog, specify 0 in this field. To resume a previous search, pass the value returned by the previous call to PBCatSearchSync or PBCatSearchAsync.
priv: An array of integers that is used internally by PBCatSearchSync and PBCatSearchAsync.

Discussion

When you call the PBCatSearchSync or PBCatSearchAsync function to search a volume’s catalog file, you can specify, in the ioCatPosition field of the parameter block passed to PBCatSearchSync and PBCatSearchAsync, a catalog position structure. If a catalog search consumes more time than is allowed by the ioSearchTime field, PBCatSearchSync and PBCatSearchAsync store a directory-location index in that structure; when you call PBCatSearchSync or PBCatSearchAsync again, it uses that structure to resume searching where it left off.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

CInfoPBRec

Defines a catalog information parameter block for file and directory information.

union CInfoPBRec {
   HFileInfo hFileInfo;
   DirInfo dirInfo;
};
typedef union CInfoPBRec CInfoPBRec;
typedef CInfoPBRec * CInfoPBPtr;

Fields

hFileInfo
dirInfo

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

CMovePBRec

Defines a parameter block, used with the functions PBCatMoveSync and PBCatMoveAsync.

struct CMovePBRec {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   long filler1;
   StringPtr ioNewName;
   long filler2;
   long ioNewDirID;
   long filler3[2];
   long ioDirID;
};
typedef struct CMovePBRec CMovePBRec;
   typedef CMovePBRec * CMovePBPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).
ioVRefNum: A volume reference number, 0 for the default volume, or a drive number.
filler1: Reserved.
ioNewName: The name of the directory into which the specified file or directory is to be moved.
filler2: Reserved.
ioNewDirID: The directory ID of the directory into which the specified file or directory is to be moved.
filler3: Reserved.
ioDirID: The current directory ID of the file or directory to be moved (used in conjunction with the ioVRefNum and ioNamePtr fields).

Discussion

The low-level HFS function PBCatMove uses the catalog move parameter block defined by the CMovePBRec data type.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

CntrlParam

Defines a parameter block used by control and status functions in the classic Device Manager.

struct CntrlParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   short ioCRefNum;
   short csCode;
   short csParam[11];
};
typedef struct CntrlParam CntrlParam;
   typedef CntrlParam * CntrlParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).
ioVRefNum: A volume reference number, 0 for the default volume, or a drive number.
ioCRefNum: The driver reference number for the I/O operation.
csCode: A value identifying the type of control or status request. Each driver may interpret this number differently.
csParam: The control or status information passed to or from the driver. This field is declared generically as an array of eleven integers. Each driver may interpret the contents of this field differently. Refer to the driver's documentation for specific information.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

ConstFSSpecPtr

Defines a pointer to an FSSpec structure.

typedef const FSSpec*  ConstFSSpecPtr;

Discussion

The only difference between “const FSSpec*” and the ConstFSSpecPtr data type is that, as a parameter, a ConstFSSpecPtr data type is allowed to be NULL. See FSSpec.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

ConstHFSUniStr255Param

Defines a pointer to an HFSUniStr255 structure.

typedef const HFSUniStr255*  ConstHFSUniStr255Param;

Discussion

See HFSUniStr255.

Availability

Available in OS X v10.0 and later.

Declared In

hfs_format.h

CopyParam

Defines a parameter block used by low-level HFS file copying functions.

struct CopyParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   short ioDstVRefNum;
   short filler8;
   StringPtr ioNewName;
   StringPtr ioCopyName;
   long ioNewDirID;
   long filler14;
   long filler15;
   long ioDirID;
};
typedef struct CopyParam CopyParam;
   typedef CopyParam * CopyParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).
ioVRefNum: A volume reference number, 0 for the default volume, or a drive number.
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.
filler14: Reserved.
filler15: Reserved.
ioDirID: A directory ID.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

CSParam

Defines a parameter block used by low-level HFS catalog search functions.

struct CSParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   FSSpecPtr ioMatchPtr;
   long ioReqMatchCount;
   long ioActMatchCount;
   long ioSearchBits;
   CInfoPBPtr ioSearchInfo1;
   CInfoPBPtr ioSearchInfo2;
   long ioSearchTime;
   CatPositionRec ioCatPosition;
   Ptr ioOptBuffer;
   long ioOptBufSize;
};
typedef struct CSParam CSParam;
   typedef CSParam * CSParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.

ioCmdAddr

The address of the function that was called. This field is used internally by the File Manager.

ioCompletion

A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).

ioVRefNum

A volume reference number, 0 for the default volume, or a drive number.

ioMatchPtr

A pointer to an array of FSSpec structures 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 structures, as determined by the ioReqMatchCount field.

ioReqMatchCount

The maximum number of matches to return. This number should be the number of FSSpec structures that will fit in the memory pointed to by the ioMatchPtr field. 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 in the ioSearchInfo1 and ioSearchInfo2 fields that are relevant to the search. See “Catalog Search Bits” for more information.

ioSearchInfo1

A pointer to a CInfoPBRec parameter block that contains the search information. For values that match by mask and value (Finder information, for example), set the bits in the structure passed in the ioSearchInfo2 field, and set the matching values in this structure. For values that match against a range (such as dates), set the lower bounds for the range in this structure.

ioSearchInfo2

A pointer to a second CInfoPBRec parameter block that contains the search information. For values that match by mask and value (Finder information, for example), set the bits in this structure, and set the matching values in the structure passed in the ioSearchInfo1 field. For values that match against a range (such as dates), set the upper bounds for the range in this structure.

ioSearchTime

A time limit on a search, in Time Manager format. Use this field to limit the run time of a single call to PBCatSearchSync or PBCatSearchAsync. 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 PBCatSearchSync or PBCatSearchAsync search into a number of smaller searches. This field is valid whenever PBCatSearchSync or PBCatSearchAsync 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, PBCatSearchSync or PBCatSearchAsync sets that field to the next catalog entry to be searched.

To resume where the previous call stopped, pass the entire CatPositionRec structure 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.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

DirInfo

Defines a structure which holds catalog information about a directory.

struct DirInfo {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   short ioFRefNum;
   SInt8 ioFVersNum;
   SInt8 filler1;
   short ioFDirIndex;
   SInt8 ioFlAttrib;
   SInt8 ioACUser;
   DInfo ioDrUsrWds;
   long ioDrDirID;
   unsigned short ioDrNmFls;
   short filler3[9];
   unsigned long ioDrCrDat;
   unsigned long ioDrMdDat;
   unsigned long ioDrBkDat;
   DXInfo ioDrFndrInfo;
   long ioDrParID;
};
typedef struct DirInfo DirInfo;

Fields

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 function that was called. This field is used internally by the File Manager.

ioCmdAddr

The address of the function that was called. This field is used internally by the File Manager.

ioCompletion

ioResult

ioNamePtr

ioVRefNum

A volume reference number, 0 for the default volume, or a drive number.

ioFRefNum

The file reference number of an open file.

ioFVersNum

A file version number. This field is no longer used. File version numbers are an artifact of the obsolete MFS, and are not supported on HFS volumes. You should always set this field to 0.

filler1

Reserved.

ioFDirIndex

A file and directory index. If this field contains a positive number, PBGetCatInfoSync and PBGetCatInfoAsync return information about the file or directory having that directory index in the directory specified by the ioVRefNum field. (If ioVRefNum contains a volume reference number, the specified directory is that volume’s root directory.)

If this field contains 0, PBGetCatInfoSync and PBGetCatInfoAsync return information about the file or directory whose name is specified in the ioNamePtr field and that is located in the directory specified by the ioVRefNum field. (Once again, if ioVRefNum contains a volume reference number, the specified directory is that volume’s root directory.)

If this field contains a negative number, PBGetCatInfoSync and PBGetCatInfoAsync ignore the ioNamePtr field and returns information about the directory specified in the ioDirID field. If both ioDirID and ioVRefNum are set to 0, PBGetCatInfoSync and PBGetCatInfoAsync return information about the current default directory.

ioFlAttrib

File or directory attributes. See “File Attribute Constants” for the meaning of the bits in this field.

ioACUser

The user’s access rights for the specified directory. See “User Privileges Constants” for the meaning of the bits in this field.

ioDrUsrWds

Information used by the Finder.

ioDrDirID

A directory ID. On input to PBGetCatInfoSync and PBGetCatInfoAsync , this field contains a directory ID, which is used only if the value of the ioFDirIndex field is negative. On output, this field contains the directory ID of the specified directory.

ioDrNmFls

The number of files in the directory.

filler3

Reserved.

ioDrCrDat

The date and time of the directory’s creation, in seconds since midnight, January 1, 1904. However, on OS X, if you set the creation date to a date between January 1, 1904 and January 1, 1970, it will be clipped to January 1, 1970, and that is the value which will be returned if you later try to retrieve the creation date.

Note that file systems other than AFP, HFS and HFS Plus do not generally support creation dates.

ioDrMdDat

The date and time of the last modification to the directory, in seconds since midnight, January 1, 1904. However, on OS X, if you set the modification date to a date between January 1, 1904 and January 1, 1970, it will be clipped to January 1, 1970.

ioDrBkDat

The date and time that the directory was last backed up, in seconds since midnight, January 1, 1904. However, on OS X, if you set the backup date to a date between January 1, 1904 and January 1, 1970, it will be clipped to January 1, 1970.

Note that file systems other than AFP, HFS and HFS Plus do not generally support backup dates.

ioDrFndrInfo

Additional information used by the Finder.

ioDrParID

The directory ID of the specified directory’s parent directory.

refCon

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

DrvQEl

Defines a drive queue element.

struct DrvQEl {
   QElemPtr qLink;
   short qType;
   short dQDrive;
   short dQRefNum;
   short dQFSID;
   unsigned short dQDrvSz;
   unsigned short dQDrvSz2;
};
typedef struct DrvQEl DrvQEl;
   typedef DrvQEl * DrvQElPtr;

Fields

qLink: A pointer to the next entry in the drive queue.
qType: Used to specify the size of the drive. If the value of this field is 0, the number of logical blocks on the drive is contained in the dQDrvSz field alone. If the value of this field is 1, both the dQDrvSz field and the dQDrvSz2 field are used to store the number of blocks; in that case, the dQDrvSz2 field contains the high-order word of this number and dQDrvSz contains the low-order word.
dQDrive: The drive number of the drive.
dQRefNum: The driver reference number of the driver controlling the device on which the volume is mounted.
dQFSID: An identifier for the file system handling the volume in the drive it’s zero for volumes handled by the File Manager and nonzero for volumes handled by other file systems.
dQDrvSz: The number of logical blocks on the drive.
dQDrvSz2: An additional field to handle large drives. This field is only used if the qType field is 1.

Discussion

The File Manager maintains a list of all disk drives connected to the computer. It maintains this list in the drive queue, which is a standard operating system queue. The drive queue is initially created at system startup time. Elements are added to the queue at system startup time or when you call the AddDrive function. The drive queue can support any number of drives, limited only by memory space. Each element in the drive queue contains information about the corresponding drive.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

DTPBRec

Defines the desktop database parameter block used by the desktop database functions.

struct DTPBRec {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   short ioDTRefNum;
   short ioIndex;
   long ioTagInfo;
   Ptr ioDTBuffer;
   long ioDTReqCount;
   long ioDTActCount;
   SInt8 ioFiller1;
   UInt8 ioIconType;
   short ioFiller2;
   long ioDirID;
   OSType ioFileCreator;
   OSType ioFileType;
   long ioFiller3;
   long ioDTLgLen;
   long ioDTPyLen;
   short ioFiller4[14];
   long ioAPPLParID;
};
typedef struct DTPBRec DTPBRec;
   typedef DTPBRec * DTPBPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 file, directory, or volume name. Whenever a function 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 NULL (if you’re not).
ioVRefNum: The volume reference number.
ioDTRefNum: The desktop database reference number.
ioIndex: The index into icon list.
ioTagInfo: The tag information.
ioDTBuffer: The data buffer.
ioDTReqCount: The requested length of data.
ioDTActCount: The actual length of data.
ioFiller1: Unused.
ioIconType: The icon type.
ioFiller2: Unused.
ioDirID: The parent directory ID.
ioFileCreator: The file creator.
ioFileType: The file type.
ioFiller3: Unused.
ioDTLgLen: The logical length of the desktop database.
ioDTPyLen: The physical length of the desktop database.
ioFiller4: Unused.
ioAPPLParID: The parent directory ID of an application.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

FCBPBRec

Defines a file control block (FCB) parameter block used by the functions PBGetFCBInfoSync and PBGetFCBInfoAsync.

struct FCBPBRec {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   short ioRefNum;
   short filler;
   short ioFCBIndx;
   short filler1;
   long ioFCBFlNm;
   short ioFCBFlags;
   unsigned short ioFCBStBlk;
   long ioFCBEOF;
   long ioFCBPLen;
   long ioFCBCrPs;
   short ioFCBVRefNum;
   long ioFCBClpSiz;
   long ioFCBParID;
};
typedef struct FCBPBRec FCBPBRec;
   typedef FCBPBRec * FCBPBPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).
ioVRefNum: A volume reference number, 0 for the default volume, or a drive number.
ioRefNum: The file reference number of an open file.
filler: Reserved.
ioFCBIndx: An index for use with the PBGetFCBInfoSync and PBGetFCBInfoAsync functions.
filler1: Reserved.
ioFCBFlNm: The file ID.
ioFCBFlags: Flags describing the status of the file. See “FCB Flags” for the meanings of the bits in this field.
ioFCBStBlk: The number of the first allocation block of the file.
ioFCBEOF: The logical length (logical end-of-file) of the file.
ioFCBPLen: The physical length (physical end-of-file) of the file.
ioFCBCrPs: The current position of the file mark.
ioFCBVRefNum: The volume reference number.
ioFCBClpSiz: The file clump size.
ioFCBParID: The file’s parent directory ID.

Discussion

The low-level HFS function PBGetFCBInfo uses the file control block parameter block defined by the FCBPBRec data type.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

FIDParam

Defines a parameter block used by low-level HFS file ID functions.

struct FIDParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   long filler14;
   StringPtr ioDestNamePtr;
   long filler15;
   long ioDestDirID;
   long filler16;
   long filler17;
   long ioSrcDirID;
   short filler18;
   long ioFileID;
};
typedef struct FIDParam FIDParam;
   typedef FIDParam * FIDParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).
ioVRefNum: A volume reference number, 0 for the default volume, or a drive number.
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.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

FileParam

Defines a parameter block used by low-level functions for getting and setting file information.

struct FileParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   short ioFRefNum;
   SInt8 ioFVersNum;
   SInt8 filler1;
   short ioFDirIndex;
   SInt8 ioFlAttrib;
   SInt8 ioFlVersNum;
   FInfo ioFlFndrInfo;
   unsigned long ioFlNum;
   unsigned short ioFlStBlk;
   long ioFlLgLen;
   long ioFlPyLen;
   unsigned short ioFlRStBlk;
   long ioFlRLgLen;
   long ioFlRPyLen;
   unsigned long ioFlCrDat;
   unsigned long ioFlMdDat;
};
typedef struct FileParam FileParam;
   typedef FileParam * FileParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).
ioVRefNum: A volume reference number, 0 for the default volume, or a drive number.
ioFRefNum: The file reference number of an open file.
ioFVersNum: A file version number. This field is no longer used. File version numbers are an artifact of the obsolete MFS, and are not supported on HFS volumes. You should always set this field to 0.
filler1: Reserved.
ioFDirIndex: A directory index for use with the PBHGetFInfoSync and PBHGetFInfoAsync functions.
ioFlAttrib: File attributes. See “File Attribute Constants” for the meaning of the bits in this field.
ioFlVersNum: A file version number. This feature is no longer supported, and you must always set this field to 0.
ioFlFndrInfo: Information used by the Finder.
ioFlNum: A file 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 length (logical end-of-file) of the data fork.
ioFlPyLen: The physical length (physical end-of-file) of the data fork.
ioFlRStBlk: The first allocation block of the resource fork. This field contains 0 if the file’s resource fork is empty.
ioFlRLgLen: The logical length (logical end-of-file) of the resource fork.
ioFlRPyLen: The physical length (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.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

FNSubscriptionRef

typedef struct OpaqueFNSubscriptionRef * FNSubscriptionRef;

Availability

Available in OS X v10.1 and later.

Declared In

Files.h

FNSubscriptionUPP

typedef FNSubscriptionProcPtr FNSubscriptionUPP;

Availability

Available in OS X v10.1 and later.

Declared In

Files.h

ForeignPrivParam

Defines a parameter block used by low-level HFS foreign privileges functions.

struct ForeignPrivParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   long ioFiller21;
   long ioFiller22;
   Ptr ioForeignPrivBuffer;
   long ioForeignPrivActCount;
   long ioForeignPrivReqCount;
   long ioFiller23;
   long ioForeignPrivDirID;
   long ioForeignPrivInfo1;
   long ioForeignPrivInfo2;
   long ioForeignPrivInfo3;
   long ioForeignPrivInfo4;
};
typedef struct ForeignPrivParam ForeignPrivParam;
   typedef ForeignPrivParam * ForeignPrivParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).
ioVRefNum: A volume reference number, 0 for the default volume, or a drive number.
ioFiller21: Reserved.
ioFiller22: Reserved.
ioForeignPrivBuffer: A pointer to a buffer containing access-control information about the foreign file system.
ioForeignPrivActCount: The size of the buffer pointed to by the ioForeignPrivBuffer field.
ioForeignPrivReqCount: The amount of the buffer pointed to by the ioForeignPrivBuffer field that was actually used to hold data.
ioFiller23: 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.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

FSCatalogBulkParam

Defines a parameter block used to retrieve catalog information in bulk on HFS Plus volumes.

struct FSCatalogBulkParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   Boolean containerChanged;
   UInt8 reserved;
   FSIteratorFlags iteratorFlags;
   FSIterator iterator;
   const FSRef * container;
   ItemCount maximumItems;
   ItemCount actualItems;
   FSCatalogInfoBitmap whichInfo;
   FSCatalogInfo * catalogInfo;
   FSRef * refs;
   FSSpec * specs;
   HFSUniStr255 * names;
   const FSSearchParams * searchParams;
};
typedef struct FSCatalogBulkParam FSCatalogBulkParam;
   typedef FSCatalogBulkParam * FSCatalogBulkParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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.
containerChanged: A Boolean value indicating whether or not the container has changed since the last call to PBGetCatalogInfoBulkSync or PBGetCatalogInfoBulkAsync.
reserved: Reserved.
iteratorFlags: A set of flags which specifies how the iterator should iterate over the container. See “Iterator Flags” for the meaning of the constants used here.
iterator: A catalog iterator.
container: An FSRef for the directory or volume to iterate over.
maximumItems: The maximum number of items to return information about.
actualItems: The actual number of items returned.
whichInfo: A bitmap indicating which fields of the catalog information structure to return. See “Catalog Information Bitmap Constants” for the bits defined for this field.
catalogInfo: A pointer to an array of catalog information structures. On input, you should pass a pointer to an array of maximumItemsFSCatalogInfo structures. On return, actualItems structures will be filled out with the information requested in the whichInfo field. If you do not wish any catalog information to be returned, pass a NULL pointer in this field and pass the constant kFSCatInfoNone in the whichInfo field.
refs: A pointer to an array of FSRef structures. On input, you should pass a pointer to maximumItemsFSRef structures. On return, actualItems structures will be filled out. If you do not wish any FSRef structures to be returned, pass a NULL pointer in this field.
specs: A pointer to an array of FSSpec structures. On input, you should pass a pointer to maximumItems file system specifications. On return, actualItemsFSSpec structures will be filled in. If you do not wish any FSSpec information to be returned, pass a NULL pointer in this field.
names: A pointer to an array of Unicode names. On input, you should pass a pointer to an array of maximumItemsHFSUniStr255 structures. On return, actualItems structures will contain Unicode names. If you do not wish any file or directory names to be returned, pass a NULL pointer in this field.
searchParams: A pointer to an FSSearchParams structure, specifying the values to match against.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

FSCatalogInfo

Holds basic information about a file or directory.

struct FSCatalogInfo {
   UInt16 nodeFlags;
   FSVolumeRefNum volume;
   UInt32 parentDirID;
   UInt32 nodeID;
   UInt8 sharingFlags;
   UInt8 userPrivileges;
   UInt8 reserved1;
   UInt8 reserved2;
   UTCDateTime createDate;
   UTCDateTime contentModDate;
   UTCDateTime attributeModDate;
   UTCDateTime accessDate;
   UTCDateTime backupDate;
   UInt32 permissions[4];
   UInt8 finderInfo[16];
   UInt8 extFinderInfo[16];
   UInt64 dataLogicalSize;
   UInt64 dataPhysicalSize;
   UInt64 rsrcLogicalSize;
   UInt64 rsrcPhysicalSize;
   UInt32 valence;
   TextEncoding textEncodingHint;
};
typedef struct FSCatalogInfo FSCatalogInfo;
   typedef FSCatalogInfo * FSCatalogInfoPtr;

Fields

nodeFlags

Node flags. This field has two defined bits that indicate whether an object is a file or folder, and whether a file is locked (constants kFSNodeIsDirectoryMask and kFSNodeLockedMask). See “Catalog Information Node Flags” for the values you can use here.

volume

The object's volume reference.

parentDirID

The ID of the directory that contains the given object. The root directory of a volume always has ID fsRtDirID (2); the parent of the root directory is ID fsRtParID (1). Note that there is no object with ID fsRtParID; this is merely used when the File Manager is asked for the parent of the root directory.

nodeID

The file or directory ID.

sharingFlags

The object’s sharing flags. See “Catalog Information Sharing Flags ” for the meaning of the bits defined for this field.

userPrivileges

The user's effective AFP privileges (same as ioACUser in the old HFileInfo and DirInfo structures). See “User Privileges Constants.”

reserved1

Reserved.

reserved2

Reserved.

createDate

The date and time of the creation of the object. Note that file systems other than AFP, HFS and HFS Plus do not generally support creation dates. For file systems which do not support creation dates, FSGetCatalogInfo, PBGetCatalogInfoSync, and PBGetCatalogInfoAsync return 0 in this field.

contentModDate

The date and time that the data or resource fork was last modified.

attributeModDate

The date and time that an attribute of the object (such as a fork other than the data or resource fork) was last modified.

accessDate

The date and time that the object was last accessed. The Mac OS 9 File Manager does not automatically update the accessDate field; it exists primarily for use by other operating systems (notably OS X).

backupDate

The date and time of the object’s last backup. This field is not updated by the File Manager a backup utility may use this field if it wishes. Note that file systems other than AFP, HFS and HFS Plus do not generally support backup dates. For file systems which do not support backup dates, FSGetCatalogInfo, PBGetCatalogInfoSync, and PBGetCatalogInfoAsync return 0 in this field.

permissions

User and group permission information. The Mac OS 8 and 9 File Manager does not use or enforce this permission information. It could be used by a file server program or other operating system (primarily OS X). In OS X, this array contains the file system permissions of the returned item. To use this information, coerce the parameter to a FSPermissionInfo structure.

finderInfo

Basic Finder information for the object. This information is available in the catalog information, instead of in a named fork, for historical reasons. The File Manager does not interpret the contents of these fields. To use this information, coerce the parameter to a FileInfo or FolderInfo structure.

extFinderInfo

Extended Finder information for the object. This information is available in the catalog information, instead of in a named fork, for historical reasons. The File Manager does not interpret the contents of these fields. To use this information, coerce the parameter to an ExtendedFileInfo or ExtendedFolderInfo structure.

dataLogicalSize

The size of the data fork in bytes (the fork’s logical size). The information in this field is only valid for files do not rely upon the value returned in this field for folders.

dataPhysicalSize

The amount of disk space, in bytes, occupied by the data fork (the fork’s physical size). The information in this field is only valid for files do not rely upon the value returned in this field for folders.

rsrcLogicalSize

The size of the resource fork (the fork’s logical size). The information in this field is only valid for files do not rely upon the value returned in this field for folders.

rsrcPhysicalSize

The amount of disk space occupied by the resource fork (the fork’s physical size). The information in this field is only valid for files do not rely upon the value returned in this field for folders.

valence

For folders only, the number of items (files plus directories) contained within the directory. For files, it is set to zero. Many volume formats do not store a field containing a directory’s valence. For those volume formats, this field is very expensive to compute. Think carefully before you ask the File Manager to return this field.

textEncodingHint

The textEncodingHint field is used in conjunction with the Unicode filename of the object. It is an optional hint that can be used by the volume format when converting the Unicode to some other encoding. For example, HFS Plus stores this value and uses it when converting the name to a Mac OS encoding, such as when the name is returned by PBGetCatInfoSync or PBGetCatInfoAsync. As another example, HFS volumes use this value to convert the Unicode name to a Mac OS encoded name stored on disk. If the entire Unicode name can be converted to a single Mac OS encoding, then that encoding should be used as the textEncodingHint; otherwise, a text encoding corresponding to the first characters of the name will probably provide the best user experience.

If a textEncodingHint is not supplied when a file or directory is created or renamed, the volume format will use a default value. This default value may not be the best possible choice for the given filename. Whenever possible, a client should supply a textEncodingHint.

Discussion

The FSCatalogInfoBitmap type is used to indicate which fields of the FSCatalogInfo should be set or retrieved. If the bit corresponding to a particular field is not set, then that field is not changed if the FSCatalogInfo is an output parameter, and that field is ignored if the FSCatalogInfo is an input parameter.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

FSCatalogInfoBitmap

Describes which fields of the FSCatalogInfo structure you wish to retrieve or set.

typedef UInt32 FSCatalogInfoBitmap;

Discussion

If the bit corresponding to a particular field is not set in the bitmap, then that field is not changed in the FSCatalogInfo structure if it is an output parameter, and that field is ignored if the FSCatalogInfo structure is an input parameter. See “Catalog Information Bitmap Constants” for a description of the constants you should use with this data type.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

FSEjectStatus

typedef UInt32 FSEjectStatus;

Availability

Available in OS X v10.2 and later.

Declared In

Files.h

FSFileOperationClientContext

Specifies user-defined data and callbacks associated with an asynchronous file operation.

struct FSFileOperationClientContext {
   CFIndex version;
   void *info;
   CFAllocatorRetainCallBack retain;
   CFAllocatorReleaseCallBack release;
   CFAllocatorCopyDescriptionCallBack copyDescription;
};
typedef struct FSFileOperationClientContext FSFileOperationClientContext;

Fields

version: The version number of the structure; this field should always contain 0.
info: A generic pointer to your user-defined data. This pointer is passed back to your application when you check the status of the file operation. There are two ways you can ask the File Manager for status information about a file operation: by supplying a status callback function when you start the operation, or by calling a file operation status function directly.
retain: An optional callback function that the File Manager can use to retain the user-defined data specified in the info parameter. If your data is a Core Foundation object, you can simply specify the function CFRetain. If no callback is needed, set this field to NULL.
release: An optional callback function that the File Manager can use to release the user-defined data specified in the info parameter. If your data is a Core Foundation object, you can simply specify the function CFRelease. If no callback is needed, set this field to NULL.
copyDescription: An optional callback function that the File Manager can use to create a descriptive string representation of your user-defined data for debugging purposes. If no callback is needed, set this field to NULL.

Discussion

You supply a client context when calling functions such as FSCopyObjectAsync or FSMoveObjectAsync that start an asynchronous copy or move operation.

Availability

Available in OS X v10.4 and later.

Declared In

Files.h

FSFileOperationRef

Defines an opaque type that represents an asynchronous file operation.

typedef struct __FSFileOperation * FSFileOperationRef;

Discussion

You supply a file operation object when calling functions such as FSCopyObjectAsync or FSMoveObjectAsync to start an asynchronous copy or move operation. You can also use a file operation object to check the status of a file operation or to cancel the operation.

To perform an asynchronous file operation:

Create a file operation object using the function FSFileOperationCreate.
Pass the object to the function FSFileOperationScheduleWithRunLoop to schedule the operation.
Pass the object to one of the asynchronous file operation functions to start the operation.

The FSFileOperationRef opaque type is a standard Core Foundation data type. It is derived from CFType and inherits the properties that all Core Foundation types have in common. For more information, see CFType Reference.

Availability

Available in OS X v10.4 and later.

Declared In

Files.h

FSForkCBInfoParam

Defines a parameter block used by low-level HFS Plus fork control block functions.

struct FSForkCBInfoParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   SInt16 desiredRefNum;
   SInt16 volumeRefNum;
   SInt16 iterator;
   SInt16 actualRefNum;
   FSRef * ref;
   FSForkInfo * forkInfo;
   HFSUniStr255 * forkName;
};
typedef struct FSForkCBInfoParam FSForkCBInfoParam;
   typedef FSForkCBInfoParam * FSForkCBInfoParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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.
desiredRefNum: A fork reference number.
volumeRefNum: The volume reference number of the volume to match, or zero to match all volumes.
iterator: An iterator. Set to zero to start iteration.
actualRefNum: On return, the actual fork reference number found.
ref: A pointer to an FSRef for the specified fork.
forkInfo: A pointer to a fork information structure, FSForkInfo.
forkName: A pointer to the fork’s Unicode name.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

FSForkInfo

Contains information about an open fork.

struct FSForkInfo {
   SInt8 flags;
   SInt8 permissions;
   FSVolumeRefNum volume;
   UInt32 reserved2;
   UInt32 nodeID;
   UInt32 forkID;
   UInt64 currentPosition;
   UInt64 logicalEOF;
   UInt64 physicalEOF;
   UInt64 process;
};
typedef struct FSForkInfo FSForkInfo;
   typedef FSForkInfo * FSForkInfoPtr;

Fields

flags: Flags describing the status of the fork. See “FCB Flags” for a description of the bits in this field.
permissions: User and group permission information.
volume: A volume specification. This can be a volume reference number, drive number, or 0 for the default volume.
reserved2: Reserved.
nodeID: The file or directory ID of the file or directory with which the fork is associated.
forkID: The fork ID.
currentPosition: The current position within the fork.
logicalEOF: The logical size of the fork.
physicalEOF: The physical size of the fork.
process: The process which opened the fork.

Discussion

This data type is used in the forkInfo parameter of the FSGetForkCBInfo function, and in the forkInfo field of the FSForkCBInfoParam parameter block passed to the PBGetForkCBInfoSync and PBGetForkCBInfoAsync functions. When these functions return, the FSForkInfo structure contains information about the specified open fork.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

FSForkIOParam

Defines a parameter block used by low-level HFS Plus fork I/O functions.

struct FSForkIOParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   void * reserved1;
   SInt16 reserved2;
   SInt16 forkRefNum;
   UInt8 reserved3;
   SInt8 permissions;
   const FSRef * ref;
   Ptr buffer;
   UInt32 requestCount;
   UInt32 actualCount;
   UInt16 positionMode;
   SInt64 positionOffset;
   FSAllocationFlags allocationFlags;
   UInt64 allocationAmount;
   UniCharCount forkNameLength;
   const UniChar * forkName;
   CatPositionRec forkIterator;
   HFSUniStr255 * outForkName;
};
typedef struct FSForkIOParam FSForkIOParam;
   typedef FSForkIOParam * FSForkIOParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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.
reserved1: Reserved.
reserved2: Reserved.
forkRefNum: A reference number for a fork.
reserved3: Reserved.
permissions: The desired type of access to the specified fork. See “File Access Permission Constants” for a description of the types of access that you can request.
ref: An FSRef for the file or directory to open.
buffer: A pointer to a data buffer.
requestCount: The number of bytes requested for the given operation.
actualCount: The actual number of bytes completed by the call.
positionMode: A constant indicating the base location within the file for the start of the operation. See “Position Mode Constants” for the meaning of the constants you can use in this field.
positionOffset: The offset from the base location specified in the positionMode offset for the start of the operation.
allocationFlags: A set of bit flags used by the FSAllocateFork function to control how space is allocated. See “Allocation Flags” for a description of the defined flags.
allocationAmount: For the FSAllocateFork function, the amount of space, in bytes, to allocate.
forkNameLength: The length of the file or directory name passed in the forkName field, in Unicode characters.
forkName: A pointer to the file or directory’s Unicode name. This field is an input parameter functions which return the file or directory name in the parameter block use the outForkName field.
forkIterator: A fork iterator.
outForkName: A pointer to the file or directory’s Unicode name this is an output parameter. For functions which require the file or directory name as an input argument, you should pass a pointer to that name in the forkName field and pass the length of the name in the forkNameLength field.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

FSIterator

Refers to a position within the catalog, used when iterating over files and folders in a directory.

typedef struct OpaqueFSIterator * FSIterator;

Discussion

This data type is like a file reference number because it maintains state internally to the File Manager and must be explicitly opened and closed.

An FSIterator is returned by FSOpenIterator and is passed as input to FSGetCatalogInfoBulk , FSCatalogSearch and FSCloseIterator.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

FSMountStatus

typedef UInt32 FSMountStatus;

Availability

Available in OS X v10.2 and later.

Declared In

Files.h

FSPermissionInfo

struct FSPermissionInfo {
   UInt32 userID;
   UInt32 groupID;
   UInt8 reserved1;
   UInt8 userAccess;
   UInt16 mode;
   UInt32 reserved2;
};
typedef struct FSPermissionInfo FSPermissionInfo;

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

FSRangeLockParam

Defines a parameter block for use with 64-bit range locking functions.

struct FSRangeLockParam {
   QElemPtr qLink;
   SInt16 qType;
   SInt16 ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   FSIORefNum forkRefNum;
   UInt64 requestCount;
   UInt16 positionMode;
   SInt64 positionOffset;
   UInt64 rangeStart;
};
typedef struct FSRangeLockParam FSRangeLockParam;

Availability

Available in OS X v10.4 and later.

Declared In

Files.h

FSRangeLockParamPtr

Defines a pointer to a range lock parameter block.

typedef FSRangeLockParam *FSRangeLockParamPtr;

Availability

Available in OS X v10.4 and later.

Declared In

Files.h

FSRef

Identifies a directory or file, including a volume’s root directory.

struct FSRef {
   UInt8 hidden[80];
};
typedef struct FSRef FSRef;
   typedef FSRef * FSRefPtr;

Discussion

This data type’s purpose is similar to an FSSpec except that an FSRef is completely opaque. An FSRef contains whatever information is needed to find the given object; the internal structure of an FSRef is likely to vary based on the volume format, and may vary based on the particular object being identified.

The client of the File Manager cannot examine the contents of an FSRef to extract information about the parent directory or the object’s name. Similarly, an FSRef cannot be constructed directly by the client; the FSRef must be constructed and returned via the File Manager. There is no need to call the File Manager to dispose an FSRef.

To determine the volume, parent directory and name associated with an FSRef, or to get an equivalent FSSpec, use the FSGetCatalogInfo call.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

FSRefParam

Defines a parameter block used by low-level HFS Plus functions.

struct FSRefParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   ConstStringPtr ioNamePtr;
   short ioVRefNum;
   SInt16 reserved1;
   UInt8 reserved2;
   UInt8 reserved3;
   const FSRef * ref;
   FSCatalogInfoBitmap whichInfo;
   FSCatalogInfo * catInfo;
   UniCharCount nameLength;
   const UniChar * name;
   long ioDirID;
   FSSpec * spec;
   FSRef * parentRef;
   FSRef * newRef;
   TextEncoding textEncodingHint;
   HFSUniStr255 * outName;
};
typedef struct FSRefParam FSRefParam;
   typedef FSRefParam * FSRefParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function description specifies that ioNamePtr is used—whether for input, output, or both—you should set this field to point to storage for a Str255 value (if you’re using a pathname) or to NULL (if you’re not).
ioVRefNum: A volume reference number, or 0 for the default volume.
reserved1: Reserved.
reserved2: Reserved.
reserved3: Reserved.
ref: The FSRef describing the file or directory which is the target of the call.
whichInfo: An FSCatalogInfoBitmap which describes the fields of the catalog information structure passed in the catInfo field which are to be retrieved or set.
catInfo: A catalog information structure containing information about the specified file or directory.
nameLength: The length of the file or directory’s name, for the PBCreateSync, PBCreateAsync, PBRenameSync, and PBRenameAsync functions.
name: A pointer to the file or directory’s Unicode name, for the PBCreateSync, PBCreateAsync, PBRenameSync, and PBRenameAsync functions.
ioDirID: The directory ID of the specified file or directory’s parent directory.
spec: The target or source FSRef.
parentRef: The secondary or destination FSRef. (Or the ref of the directory to move another file or directory to).
newRef: The output FSRef (ie, a new FSRef ).
textEncodingHint: A text encoding hint for the file or directory’s Unicode name, used by the PBMakeFSRefSync, PBMakeFSRefAsync, PBRenameSync, and PBRenameAsync functions.
outName: On output, a pointer to the Unicode name of the file or directory, used by the PBGetCatalogInfoSync and PBGetCatalogInfoAsync functions.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

FSSearchParams

Describes the search criteria for a catalog information search.

struct FSSearchParams {
   Duration searchTime;
   OptionBits searchBits;
   UniCharCount searchNameLength;
   const UniChar * searchName;
   FSCatalogInfo * searchInfo1;
   FSCatalogInfo * searchInfo2;
};
typedef struct FSSearchParams FSSearchParams;
   typedef FSSearchParams * FSSearchParamsPtr;

Fields

searchTime

A Time Manager duration for the duration of the search. If you specify a non-zero value in this field, the search may terminate after the specified time, even if the maximum number of requested objects has not been returned and the entire catalog has not been scanned.

If this value is negative, the time is interpreted in microseconds; if positive, it is interpreted as milliseconds. If searchTime is zero, there is no time limit on the search.

searchBits

A set of bits specifying which catalog information fields to search on. See “Catalog Search Constants” for the constants which you can use here.

searchNameLength

The length of the Unicode name to search by.

searchName

A pointer to the Unicode name to search by.

searchInfo1

An FSCatalogInfo structure which specifies the values and lower bounds of a search.

searchInfo2

A FSCatalogInfo structure which specifies the masks and upper bounds of a search.

Discussion

Used by FSCatalogSearch , PBCatalogSearchSync , and PBCatalogSearchAsync to specify the criteria for a catalog search.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

FSSpec

Specifies the name and location of a file or directory.

struct FSSpec {
   short vRefNum;
   long parID;
   StrFileName name;
};
typedef struct FSSpec FSSpec;
   typedef FSSpec * FSSpecPtr;

Fields

vRefNum: The volume reference number of the volume containing the specified file or directory.
parID: The parent directory ID of the specified file or directory (the directory ID of the directory containing the given file or directory).
name: The name of the specified file or directory. In Carbon, this name must be a leaf name; the name cannot contain a semicolon.

Discussion

The FSSpec structure can describe only a file or a directory, not a volume. A volume can be identified by its root directory, although the system software never uses an FSSpec structure to describe a volume. The directory ID of the root’s parent directory is fsRtParID. The name of the root directory is the same as the name of the volume.

If you need to convert a file specification into an FSSpec structure, call the function FSMakeFSSpec . Do not fill in the fields of an FSSpec structure yourself.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

FSSpecArrayPtr

Defines a pointer to an array of FSSpec structures.

typedef FSSpecPtr FSSpecArrayPtr;

Discussion

See FSSpec.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

FSUnmountStatus

typedef UInt32 FSUnmountStatus;

Availability

Available in OS X v10.2 and later.

Declared In

Files.h

FSVolumeEjectUPP

typedef FSVolumeEjectProcPtr FSVolumeEjectUPP;

Discussion

For more information, see the description of the FSVolumeEjectProcPtr callback function.

Availability

Available in OS X v10.2 and later.

Declared In

Files.h

FSVolumeInfo

Used when getting or setting information about a volume.

struct FSVolumeInfo {
   UTCDateTime createDate;
   UTCDateTime modifyDate;
   UTCDateTime backupDate;
   UTCDateTime checkedDate;
   UInt32 fileCount;
   UInt32 folderCount;
   UInt64 totalBytes;
   UInt64 freeBytes;
   UInt32 blockSize;
   UInt32 totalBlocks;
   UInt32 freeBlocks;
   UInt32 nextAllocation;
   UInt32 rsrcClumpSize;
   UInt32 dataClumpSize;
   UInt32 nextCatalogID;
   UInt8 finderInfo[32];
   UInt16 flags;
   UInt16 filesystemID;
   UInt16 signature;
   UInt16 driveNumber;
   short driverRefNum;
};
typedef struct FSVolumeInfo FSVolumeInfo;
   typedef FSVolumeInfo * FSVolumeInfoPtr;

Fields

createDate: The date and time the volume was created. A value of 0 means that the volume creation date is unknown.
modifyDate: The last time when the volume was modified in any way. A value of 0 means “never” or “unknown.
backupDate: Indicates when the volume was last backed up. This field is for use by backup utilities. A value of 0 means “never” or “unknown.
checkedDate: The last date and time that the volume was checked for consistency. A value of 0 means “never” or “unknown.
fileCount: The total number of files on the volume, or 0 if unknown.
folderCount: The total number of folders on the volume, or 0 if unknown. Note that no root directory counts.
totalBytes: The size of the volume in bytes.
freeBytes: The number of bytes of free space on the volume.
blockSize: The size of an allocation block, in bytes. This field is only appropriate for volume formats (such as HFS and HFS Plus) that allocate space in fixed-size pieces; other volume formats may not have a similar concept, and may set this field to zero.
totalBlocks: The total number of allocation blocks on the volume. This field is only appropriate for volume formats (such as HFS and HFS Plus) that allocate space in fixed-size pieces; other volume formats may not have a similar concept, and may set this field to zero.
freeBlocks: The number of unused allocation blocks on the volume. This field is only appropriate for volume formats (such as HFS and HFS Plus) that allocate space in fixed-size pieces; other volume formats may not have a similar concept, and may set this field to zero.
nextAllocation: A hint for where to start searching for free space during an allocation. This field is only appropriate for volume formats (such as HFS and HFS Plus) that allocate space in fixed-size pieces; other volume formats may not have a similar concept, and may set this field to zero.
rsrcClumpSize: Default resource fork clump size. When a fork is automatically grown as it is written, the File Manager attempts to allocate space that is a multiple of the clump size. This field is zero for volume formats that don’t support the notion of a clump size.
dataClumpSize: Default data fork clump size. When a fork is automatically grown as it is written, the File Manager attempts to allocate space that is a multiple of the clump size. This field is zero for volume formats that don’t support the notion of a clump size.
nextCatalogID: The next unused catalog node ID. Some volume formats (such as HFS and HFS Plus) use a monotonically increasing number for the catalog node ID (i.e. File ID or Directory ID) of newly created files and directories. For those volume formats, the nextCatalogID is the next file/directory ID that will be assigned. For other volume formats, this field will be zero.
finderInfo: Information used by Finder, such as the Directory ID of the System Folder. Some volume formats do not support Finder information for a volume and will set this field to all zeroes.
flags: This field contains bit flags holding information about the volume. See “Volume Information Flags” for the attribute constants you can use here.
filesystemID: Identifies the filesystem implementation that is handling the volume; this is zero for HFS and HFS Plus volumes.
signature: This field is used to distinguish between volume formats supported by a single filesystem implementation.
driveNumber: The drive number for the drive (drive queue element) associated with the volume. OS X does not support drive numbers; in OS X, the File Manager always returns a value of 1 in this field.
driverRefNum: The driver reference number for the drive (drive queue element) associated with the volume.

Discussion

This structure contains information about a volume as a whole information about a volume’s root directory would use the FSCatalogInfo structure.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

FSVolumeInfoBitmap

Describes which fields of the FSVolumeInfo structure you wish to retrieve or set.

typedef UInt32 FSVolumeInfoBitmap;

Discussion

If the bit corresponding to a particular field is not set in the bitmap, then that field is not changed in the FSVolumeInfo structure if it is an output parameter, and that field is ignored if the FSVolumeInfo structure is an input parameter. See “Volume Information Bitmap Constants” for a description of the constants you should use with this data type.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

FSVolumeInfoParam

Defines a parameter block used by low-level HFS Plus volume manipulation functions.

struct FSVolumeInfoParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   FSVolumeRefNum ioVRefNum;
   UInt32 volumeIndex;
   FSVolumeInfoBitmap whichInfo;
   FSVolumeInfo * volumeInfo;
   HFSUniStr255 * volumeName;
   FSRef * ref;
};
typedef struct FSVolumeInfoParam FSVolumeInfoParam;
   typedef FSVolumeInfoParam * FSVolumeInfoParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 volume name. This field is unused.
ioVRefNum: The volume reference number.
volumeIndex: The volume index. If this field is 0, the value in the ioVRefNum field only is used to identify the target volume.
whichInfo: A bitmap indicating which volume information fields to retrieve or set in the FSVolumeInfo structure passed in the volumeInfo field. See “Volume Information Bitmap Constants” for the meaning of the bits in this field.
volumeInfo: A pointer to a volume information structure containing the requested volume information on return, or the new values of the volume information to set on input. See FSVolumeInfo.
volumeName: On output, a pointer to the volume’s name.
ref: A pointer to an FSRef for the specified volume’s root directory.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

FSVolumeMountUPP

typedef FSVolumeMountProcPtr FSVolumeMountUPP;

Discussion

For more information, see the description of the FSVolumeMountProcPtr callback function.

Availability

Available in OS X v10.2 and later.

Declared In

Files.h

FSVolumeOperation

typedef struct OpaqueFSVolumeOperation * FSVolumeOperation;

Availability

Available in OS X v10.2 and later.

Declared In

Files.h

FSVolumeRefNum

Identifies a particular mounted volume.

typedef SInt16 FSVolumeRefNum;

Discussion

This data type is the same as the 16-bit volume refnum previously passed in the ioVRefNum fields of a parameter block; this is simply a new type name for the old data type.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

FSVolumeUnmountUPP

typedef FSVolumeUnmountProcPtr FSVolumeUnmountUPP;

Discussion

For more information, see the description of the FSVolumeUnmountProcPtr callback function.

Availability

Available in OS X v10.2 and later.

Declared In

Files.h

GetVolParmsInfoBuffer

Defines a volume attributes buffer, used by the PBHGetVolParmsSync and PBHGetVolParmAsync functions to return volume information.

struct GetVolParmsInfoBuffer {
   short vMVersion;
   long vMAttrib;
   Handle vMLocalHand;
   long vMServerAdr;
   long vMVolumeGrade;
   short vMForeignPrivID;
   long vMExtendedAttributes;
   void * vMDeviceID;
   UniCharCount vMMaxNameLength;
};
typedef struct GetVolParmsInfoBuffer GetVolParmsInfoBuffer;

Fields

vMVersion: The version number of the attributes buffer structure. Currently this field returns 1, 2, 3 or 4. Version 3 is introduced to support the HFS Plus APIs.
vMAttrib: A 32-bit quantity that encodes information about the volume attributes. See “Volume Attribute Constants” for the meaning of the bits in this field.
vMLocalHand: A handle to private data for shared volumes. On creation of the VCB (right after mounting), this field is a handle to a 2-byte block of memory. The Finder uses this for its local window list storage, allocating and deallocating memory as needed. It is disposed of when the volume is unmounted. Your application should treat this field as reserved.
vMServerAdr: For AppleTalk server volumes, this field contains the internet address of an AppleTalk server volume. Your application can inspect this field to tell which volumes belong to which server; the value of this field is 0 if the volume does not have a server.
vMVolumeGrade: The relative speed rating of the volume. The scale used to determine these values is currently uncalibrated. In general, lower values indicate faster speeds. A value of 0 indicates that the volume’s speed is unrated. The buffer version returned in the vMVersion field must be greater than 1 for this field to be meaningful.
vMForeignPrivID: An integer representing the privilege model supported by the volume. Currently two values are defined for this field: 0 represents a standard HFS or HFS Plus volume that might or might not support the AFP privilege model; fsUnixPriv represents a volume that supports the A/UX privilege model. The buffer version returned in the vMVersion field must be greater than 1 for this field to be meaningful.
vMExtendedAttributes: Contains bits that describe a volume’s extended attributes. For this field to be meaningful, the vMVersion must be greater than 2. See “Extended Volume Attributes” for the meaning of the bits in this field.
vMDeviceID: A device name identifying the device in /dev that corresponds to the volume. You can use this string to build a POSIX path to the device for use with IOKit APIs.
vMMaxNameLength

Discussion

Volumes that implement the HFS Plus APIs must use version 3 (or newer) of the GetVolParmsInfoBuffer. Volumes that don’t implement the HFS Plus APIs may still implement version 3 of the GetVolParmsInfoBuffer. If the version of the GetVolParmsInfoBuffer is 2 or less, or the bSupportsHFSPlusAPIs bit is clear (zero), then the volume does not implement the HFS Plus APIs, and they are being emulated for that volume by the File Manager itself.

If a volume does not implement the HFS Plus APIs, and supports version 2 or earlier of the GetVolParmsInfoBuffer, it cannot itself describe whether it supports the FSCatalogSearch or FSExchangeObjects calls. The compatibility layer will implement the FSCatalogSearch call if the volume supports the PBCatSearch call (i.e. the bHasCatSearch bit of vMAttrib is set). The compatibility layer will implement the FSExchangeObjects call if the volume supports PBExchangeFiles (i.e. the bHasFileIDs bit of vMAttrib is set).

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

HFileInfo

Defines a structure which holds catalog information about a file.

struct HFileInfo {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   short ioFRefNum;
   SInt8 ioFVersNum;
   SInt8 filler1;
   short ioFDirIndex;
   SInt8 ioFlAttrib;
   SInt8 ioACUser;
   FInfo ioFlFndrInfo;
   long ioDirID;
   unsigned short ioFlStBlk;
   long ioFlLgLen;
   long ioFlPyLen;
   unsigned short ioFlRStBlk;
   long ioFlRLgLen;
   long ioFlRPyLen;
   unsigned long ioFlCrDat;
   unsigned long ioFlMdDat;
   unsigned long ioFlBkDat;
   FXInfo ioFlXFndrInfo;
   long ioFlParID;
   long ioFlClpSiz;
};
typedef struct HFileInfo HFileInfo;

Fields

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 function that was called. This field is used internally by the File Manager.

ioCmdAddr

The address of the function that was called. This field is used internally by the File Manager.

ioCompletion

ioResult

ioNamePtr

ioVRefNum

A volume reference number, 0 for the default volume, or a drive number.

ioFRefNum

The file reference number of an open file.

ioFVersNum

A file version number. This field is no longer used. File version numbers are an artifact of the obsolete MFS, and are not supported on HFS volumes. You should always set this field to 0.

filler1

Reserved.

ioFDirIndex

If this field contains 0, PBGetCatInfoSync or PBGetCatInfoAsync returns information about the file or directory whose name is specified in the ioNamePtr field and that is located in the directory specified by the ioVRefNum field. (Once again, if ioVRefNum contains a volume reference number, the specified directory is that volume’s root directory.)

If this field contains a negative number, PBGetCatInfoSync or PBGetCatInfoAsync ignores the ioNamePtr field and returns information about the directory specified in the ioDirID field. If both ioDirID and ioVRefNum are set to 0, PBGetCatInfoSync or PBGetCatInfoAsync returns information about the current default directory.

ioFlAttrib

File or directory attributes. See “File Attribute Constants” for the meaning of the bits in this field.

ioACUser

The user’s access rights for the specified directory. See “User Privileges Constants” for the meaning of the bits in this field.

ioFlFndrInfo

Finder information.

ioDirID

A directory ID or file ID. On input to PBGetCatInfoSync or PBGetCatInfoAsync , this field contains a directory ID (which is used only if the ioFDirIndex field is negative). On output, this field contains the file ID of the specified file.

ioFlStBlk

The first allocation block of the data fork. This field contains 0 if the file’s data fork is empty.

ioFlLgLen

The logical length (logical end-of-file) of the data fork.

ioFlPyLen

The physical length (physical end-of-file) of the data fork.

ioFlRStBlk

The first allocation block of the resource fork.

ioFlRLgLen

The logical length (logical end-of-file) of the resource fork.

ioFlRPyLen

The physical length (physical end-of-file) of the resource fork.

ioFlCrDat

The date and time of the file’s creation, in seconds since midnight, January 1, 1904. However, on OS X, if you set the creation date to a date between January 1, 1904 and January 1, 1970, it will be clipped to January 1, 1970, and that is the value which will be returned if you later try to retrieve the creation date.

Note that file systems other than AFP, HFS and HFS Plus do not generally support creation dates.

ioFlMdDat

The date and time of the last modification to the file, in seconds since midnight, January 1, 1904. However, on OS X, if you set the modification date to a date between January 1, 1904 and January 1, 1970, it will be clipped to January 1, 1970.

ioFlBkDat

The date and time that the file was last backed up, in seconds since midnight, January 1, 1904. However, on OS X, if you set the backup date to a date between January 1, 1904 and January 1, 1970, it will be clipped to January 1, 1970.

Note that file systems other than AFP, HFS and HFS Plus do not generally support backup dates.

ioFlXFndrInfo

Additional Finder information.

ioFlParID

The directory ID of the file’s parent directory.

ioFlClpSiz

The clump size to be used when writing the file if it’s 0, the volume’s clump size is used when the file is opened.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

HFileParam

Defines a parameter block used by low-level HFS functions for file creation, deletion, and information retrieval.

struct HFileParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   short ioFRefNum;
   SInt8 ioFVersNum;
   SInt8 filler1;
   short ioFDirIndex;
   SInt8 ioFlAttrib;
   SInt8 ioFlVersNum;
   FInfo ioFlFndrInfo;
   long ioDirID;
   unsigned short ioFlStBlk;
   long ioFlLgLen;
   long ioFlPyLen;
   unsigned short ioFlRStBlk;
   long ioFlRLgLen;
   long ioFlRPyLen;
   unsigned long ioFlCrDat;
   unsigned long ioFlMdDat;
};
typedef struct HFileParam HFileParam;
   typedef HFileParam * HFileParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).
ioVRefNum: A volume reference number, 0 for the default volume, or a drive number.
ioFRefNum: The file reference number of an open file.
ioFVersNum: A file version number. This field is no longer used. File version numbers are an artifact of the obsolete MFS, and are not supported on HFS volumes. You should always set this field to 0.
filler1: Reserved.
ioFDirIndex: A directory index for use with the PBHGetFInfoSync and PBHGetFInfoAsync functions.
ioFlAttrib: File attributes. See “File Attribute Constants” for the meaning of the bits in this field.
ioFlVersNum: A file version number. This feature is no longer supported, and you must always set this field 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 length (logical end-of-file) of the data fork.
ioFlPyLen: The physical length (physical end-of-file) of the data fork.
ioFlRStBlk: The first allocation block of the resource fork. This field contains 0 if the file’s resource fork is empty.
ioFlRLgLen: The logical length (logical end-of-file) of the resource fork.
ioFlRPyLen: The physical length (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.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

HFSUniStr255

Used by the File Manager to return Unicode strings.

struct HFSUniStr255 {
   UInt16 length;
   UniChar unicode[255];
};
typedef struct HFSUniStr255 HFSUniStr255;

Fields

length: The number of unicode characters in the string.
unicode: The string, in unicode characters.

Discussion

This data type is a string of up to 255 16-bit Unicode characters, with a preceding 16-bit length (number of characters). Note that only the first length characters have meaningful values; the remaining characters may be set to arbitrary values. A caller should always assume that the entire structure will be modified, even if the actual string length is less than 255.

Availability

Available in OS X v10.0 and later.

Declared In

hfs_format.h

HIOParam

Defines a parameter block used by low-level HFS I/O functions.

struct HIOParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   short ioRefNum;
   SInt8 ioVersNum;
   SInt8 ioPermssn;
   Ptr ioMisc;
   Ptr ioBuffer;
   long ioReqCount;
   long ioActCount;
   short ioPosMode;
   long ioPosOffset;
};
typedef struct HIOParam HIOParam;
   typedef HIOParam * HIOParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.

ioCmdAddr

The address of the function that was called. This field is used internally by the File Manager.

ioCompletion

ioResult

ioNamePtr

ioVRefNum

A volume reference number, 0 for the default volume, or a drive number.

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. See “File Access Permission Constants.”

ioMisc

Depending on the function called, this field contains either a 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 PBReadSync and PBReadAsync calls, and from which data is read by PBWriteSync and PBWriteAsync calls.

ioReqCount

The requested number of bytes to be read, written, or allocated.

ioActCount

The number of bytes actually read, written, or allocated.

ioPosMode

You can also use the constants described in “Cache Constants” to indicate whether or not to cache the data.

ioPosOffset

The offset to be used in conjunction with the base location specified in the ioPosMode field.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

HParamBlockRec

Describes the HFS parameter block.

union HParamBlockRec {
   HIOParam ioParam;
   HFileParam fileParam;
   HVolumeParam volumeParam;
   AccessParam accessParam;
   ObjParam objParam;
   CopyParam copyParam;
   WDParam wdParam;
   FIDParam fidParam;
   CSParam csParam;
   ForeignPrivParam foreignPrivParam;
};
typedef union HParamBlockRec HParamBlockRec;
typedef HParamBlockRec * HParmBlkPtr;

Fields

ioParam: A parameter block used by low-level HFS I/O functions. See HIOParam.
fileParam: A parameter block used by low-level HFS functions for file creation, deletion, and information retrieval. See HFileParam.
volumeParam: A parameter block used by low-level HFS volume manipulation functions. See HVolumeParam.
accessParam: A parameter block used by low-level HFS file and directory access rights manipulation functions. See AccessParam.
objParam: A parameter block used by low-level HFS user and group information functions. See ObjParam.
copyParam: A parameter block used by low-level HFS file copying functions. See CopyParam.
wdParam: A parameter block used by low-level HFS working directory functions. See WDParam.
fidParam: A parameter block used by low-level HFS file ID functions. See FIDParam.
csParam: A parameter block used by low-level HFS catalog search functions. See CSParam.
foreignPrivParam: A parameter block used by low-level HFS foreign privileges functions. See ForeignPrivParam.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

HVolumeParam

Defines a parameter block used by low-level HFS volume manipulation functions.

struct HVolumeParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   long filler2;
   short ioVolIndex;
   unsigned long ioVCrDate;
   unsigned long ioVLsMod;
   short ioVAtrb;
   unsigned short ioVNmFls;
   unsigned short ioVBitMap;
   unsigned short ioAllocPtr;
   unsigned short ioVNmAlBlks;
   unsigned long ioVAlBlkSiz;
   unsigned long ioVClpSiz;
   unsigned short ioAlBlSt;
   unsigned long ioVNxtCNID;
   unsigned short ioVFrBlk;
   unsigned short ioVSigWord;
   short ioVDrvInfo;
   short ioVDRefNum;
   short ioVFSID;
   unsigned long ioVBkUp;
   short ioVSeqNum;
   unsigned long ioVWrCnt;
   unsigned long ioVFilCnt;
   unsigned long ioVDirCnt;
   long ioVFndrInfo[8];
};
typedef struct HVolumeParam HVolumeParam;
   typedef HVolumeParam * HVolumeParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.

ioCmdAddr

The address of the function that was called. This field is used internally by the File Manager.

ioCompletion

ioResult

ioNamePtr

ioVRefNum

A volume reference number, 0 for the default volume, or a drive number.

filler2

Reserved.

ioVolIndex

A volume index for use with the PBHGetVInfoSync and PBHGetVInfoAsync functions.

ioVCrDate

The date and time of the volume’s 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. See “Volume Information Attribute Constants” for the meanings of the bits in this field.

ioVNmFls

The number of files in the root directory of the volume. For performance reasons, the Carbon File Manager does not return the number of files in this field; instead, it sets ioVNmFls to 0.

To determine the number of files in the root directory of a volume in Carbon, call PBGetCatInfoAsync or PBGetCatInfoSync for the root directory. The number of files in the root directory is returned in the ioDrNmFls field.

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 the ioVDrvInfo field.

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; this is 0 if the volume has never been 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.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

IOCompletionUPP

A universal procedure pointer to an application-defined completion function.

typedef IOCompletionProcPtr IOCompletionUPP;

Discussion

See IOCompletionProcPtr.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

IOParam

Defines a parameter block used by low-level I/O functions.

struct IOParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   short ioRefNum;
   SInt8 ioVersNum;
   SInt8 ioPermssn;
   Ptr ioMisc;
   Ptr ioBuffer;
   long ioReqCount;
   long ioActCount;
   short ioPosMode;
   long ioPosOffset;
};
typedef struct IOParam IOParam;
   typedef IOParam * IOParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.

ioCmdAddr

The address of the function that was called. This field is used internally by the File Manager.

ioCompletion

ioResult

ioNamePtr

ioVRefNum

A volume reference number, 0 for the default volume, or a drive number.

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. See “File Access Permission Constants.”

ioMisc

Depending on the function called, this field contains either a new logical end-of-file (for the PBGetEOFSync/ PBGetEOFAsync and PBSetEOFSync/ PBSetEOFAsync functions), a new version number, or a pointer to a new pathname (for the PBHRenameSync/ PBHRenameAsync functions). 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 PBReadSync and PBReadAsync calls; and from which data is read by PBWriteSync and PBWriteAsync 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 (base location) for positioning the file mark. Bits 0 and 1 of this field indicate how to position the mark; you can use the constants described in “Position Mode Constants” to set or test their value.

You can also use the constants described in “Cache Constants” to indicate whether the data should be cached.

ioPosOffset

The offset to be used in conjunction with the base location specified in the ioPosMode field.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

MultiDevParam

Defines a parameter block used by low-level functions in the classic Device Manager to access multiple devices.

struct MultiDevParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   short ioMRefNum;
   SInt8 ioMVersNum;
   SInt8 ioMPermssn;
   Ptr ioMMix;
   short ioMFlags;
   Ptr ioSEBlkPtr;
};
typedef struct MultiDevParam MultiDevParam;
   typedef MultiDevParam * MultiDevParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).
ioVRefNum: A volume reference number, 0 for the default volume, or a drive number.
ioMRefNum: The driver reference number.
ioMVersNum: The slot version number.
ioMPermssn: Permissions.
ioMMix: Reserved.
ioMFlags: Flags specifying the number of additional fields. You should set the fMulti bit (bit 0) of this field and clear all of the other bits.
ioSEBlkPtr: A pointer to an external parameter block that is customized for the devices installed in the slot.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

ObjParam

Defines a parameter block used by low-level HFS user and group information functions.

struct ObjParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   short filler7;
   short ioObjType;
   StringPtr ioObjNamePtr;
   long ioObjID;
};
typedef struct ObjParam ObjParam;
   typedef ObjParam * ObjParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).
ioVRefNum: A volume reference number, 0 for the default volume, or a drive number.
filler7: Reserved.
ioObjType: A function code. The values passed in this field are determined by the function to which you pass this parameter block.
ioObjNamePtr: A pointer to the returned creator/group name.
ioObjID: The creator/group ID.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

ParamBlockRec

Describes the basic File Manager parameter block.

union ParamBlockRec {
   IOParam ioParam;
   FileParam fileParam;
   VolumeParam volumeParam;
   CntrlParam cntrlParam;
   SlotDevParam slotDevParam;
   MultiDevParam multiDevParam;
};
typedef union ParamBlockRec ParamBlockRec;
typedef ParamBlockRec * ParmBlkPtr;

Fields

ioParam
fileParam
volumeParam
cntrlParam
slotDevParam
multiDevParam

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

SlotDevParam

Defines a parameter block used by low-level functions in the classic Device Manager to access a single slot device.

struct SlotDevParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   short ioSRefNum;
   SInt8 ioSVersNum;
   SInt8 ioSPermssn;
   Ptr ioSMix;
   short ioSFlags;
   SInt8 ioSlot;
   SInt8 ioID;
};
typedef struct SlotDevParam SlotDevParam;
   typedef SlotDevParam * SlotDevParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).
ioVRefNum: A volume reference number, 0 for the default volume, or a drive number.
ioSRefNum: The driver reference number.
ioSVersNum: The slot version number.
ioSPermssn: Permissions.
ioSMix: Reserved.
ioSFlags: Flags determining the number of additional fields. You should clear all of the bits in this field.
ioSlot: The slot number.
ioID: The slot resource ID.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

VCB

Defines a volume control block.

struct VCB {
   QElemPtr qLink;
   short qType;
   short vcbFlags;
   unsigned short vcbSigWord;
   unsigned long vcbCrDate;
   unsigned long vcbLsMod;
   short vcbAtrb;
   unsigned short vcbNmFls;
   short vcbVBMSt;
   short vcbAllocPtr;
   unsigned short vcbNmAlBlks;
   long vcbAlBlkSiz;
   long vcbClpSiz;
   short vcbAlBlSt;
   long vcbNxtCNID;
   unsigned short vcbFreeBks;
   Str27 vcbVN;
   short vcbDrvNum;
   short vcbDRefNum;
   short vcbFSID;
   short vcbVRefNum;
   Ptr vcbMAdr;
   Ptr vcbBufAdr;
   short vcbMLen;
   short vcbDirIndex;
   short vcbDirBlk;
   unsigned long vcbVolBkUp;
   unsigned short vcbVSeqNum;
   long vcbWrCnt;
   long vcbXTClpSiz;
   long vcbCTClpSiz;
   unsigned short vcbNmRtDirs;
   long vcbFilCnt;
   long vcbDirCnt;
   long vcbFndrInfo[8];
   unsigned short vcbVCSize;
   unsigned short vcbVBMCSiz;
   unsigned short vcbCtlCSiz;
   unsigned short vcbXTAlBlks;
   unsigned short vcbCTAlBlks;
   short vcbXTRef;
   short vcbCTRef;
   Ptr vcbCtlBuf;
   long vcbDirIDM;
   short vcbOffsM;
};
typedef struct VCB VCB;
   typedef VCB * VCBPtr;

Fields

qLink: A pointer to the next entry in the VCB queue.
qType: The queue type. When the volume is mounted and the VCB is created, this field is cleared. Thereafter, bit 7 of this field is set whenever a file on that volume is opened.
vcbFlags: Volume flags. Bit 15 is set if the volume information has been changed by a File Manager call since the volume was last flushed by a FlushVol call. See “Volume Control Block Flags.”
vcbSigWord: The volume signature.
vcbCrDate: The date and time of the volume’s creation (initialization).
vcbLsMod: The date and time of the volume’s last modification. This is not necessarily when the volume was last flushed.
vcbAtrb: The volume attributes.
vcbNmFls: The number of files in the root directory of the volume.
vcbVBMSt: The first block of the volume bitmap.
vcbAllocPtr: The start block of the next allocation search. This field is used internally.
vcbNmAlBlks: The number of allocation blocks in the volume.
vcbAlBlkSiz: The allocation block size, in bytes. This value must always be a multiple of 512 bytes.
vcbClpSiz: The default clump size.
vcbAlBlSt: The first allocation block in the volume.
vcbNxtCNID: The next unused catalog node ID (directory or file ID).
vcbFreeBks: The number of unused allocation blocks on the volume.
vcbVN: The volume name. Note that a volume name can occupy at most 27 characters; this is an exception to the normal file and directory name limit of 31 characters.
vcbDrvNum: The drive number of the drive on which the volume is located. When a mounted drive is placed offline or ejected, this field is set to 0.
vcbDRefNum: The driver reference number of the driver used to access the volume When a volume is ejected, this field is set to the previous value of the vcbDrvNum field (and hence is a positive number). When a volume is placed offline, this field is set to the negative of the previous value of the vcbDrvNum field (and hence is a negative number).
vcbFSID: An identifier for the file system handling the volume it’s zero for volumes handled by the File Manager and nonzero for volumes handled by other file systems.
vcbVRefNum: The volume reference number of the volume.
vcbMAdr: Used internally.
vcbBufAdr: Used internally.
vcbMLen: Used internally.
vcbDirIndex: Used internally.
vcbDirBlk: Used internally.
vcbVolBkUp: The date and time that the volume was last backed up.
vcbVSeqNum: Used internally.
vcbWrCnt: The volume write count.
vcbXTClpSiz: The clump size of the extents overflow file.
vcbCTClpSiz: The clump size of the catalog file.
vcbNmRtDirs: The number of directories in the root directory.
vcbFilCnt: The total number of files on the volume.
vcbDirCnt: The total number of directories on the volume.
vcbFndrInfo: Finder information.
vcbVCSize: Used internally.
vcbVBMCSiz: Used internally.
vcbCtlCSiz: Used internally.
vcbXTAlBlks: The size, in allocation blocks, of the extents overflow file.
vcbCTAlBlks: The size, in allocation blocks, of the catalog file.
vcbXTRef: The path reference number for the extents overflow file.
vcbCTRef: The path reference number for the catalog file.
vcbCtlBuf: A pointer to the extents and catalog caches.
vcbDirIDM: The directory last searched.
vcbOffsM: The offspring index at the last search.

Discussion

The volume control block queue is a standard operating system queue that’s maintained in the system heap. It contains a volume control block for each mounted volume. A volume control block is a nonrelocatable block that contains volume-specific information.

Each time a volume is mounted, the File Manager reads its volume information from the master directory block and uses the information to build a new volume control block (VCB) in the volume control block queue (unless an ejected or offline volume is being remounted). The File Manager also creates a volume buffer in the system heap. When a volume is placed offline, its buffer is released. When a volume is unmounted, its VCB is removed from the VCB queue as well.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

VolMountInfoHeader

Defines a volume mounting information header structure for remote volumes.

struct VolMountInfoHeader {
   short length;
   VolumeType media;
};
typedef struct VolMountInfoHeader VolMountInfoHeader;
   typedef VolMountInfoHeader * VolMountInfoPtr;

Fields

length

The length of the VolMountInfoHeader structure, which is the total length of the structure header described here, plus the variable-length location data which follows the header.

media

The volume type of the remote volume. The AppleShareMediaType represents an AppleShare volume.

If you are adding support for the programmatic mounting functions to a non-Macintosh file system, you should register a four-character identifier for your volumes with DTS.

Discussion

To mount a remote server, fill out an VolMountInfoHeader structure using the PBGetVolMountInfo function and then pass this structure to the PBVolumeMount function to mount the volume.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

VolumeMountInfoHeader

Defines an extended volume mounting information header structure for remote volumes.

struct VolumeMountInfoHeader {
   short length;
   VolumeType media;
   short flags;
};
typedef struct VolumeMountInfoHeader VolumeMountInfoHeader;
   typedef VolumeMountInfoHeader * VolumeMountInfoHeaderPtr;

Fields

length

The length of the VolumeMountInfoHeader structure, which is the total length of the structure header described here, plus the variable-length location data which follows the header.

media

The volume type of the remote volume. The AppleShareMediaType represents an AppleShare volume.

If you are adding support for the programmatic mounting functions to a non-Macintosh file system, you should register a four-character identifier for your volumes with DTS.

flags

The volume mount flags. See “Volume Mount Flags.”

Discussion

This volume mount info record supersedes the VolMountInfoHeader structure; VolMountInfoHeader is included for compatibility. The VolumeMountInfoHeader record allows access to the volume mount flags by foreign filesystem writers.

To mount a remote server, fill out an VolumeMountInfoHeader structure using the PBGetVolMountInfo function and then pass this structure to the PBVolumeMount function to mount the volume.

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

VolumeParam

Defines a parameter block used by low-level volume manipulation functions.

struct VolumeParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   long filler2;
   short ioVolIndex;
   unsigned long ioVCrDate;
   unsigned long ioVLsBkUp;
   unsigned short ioVAtrb;
   unsigned short ioVNmFls;
   unsigned short ioVDirSt;
   short ioVBlLn;
   unsigned short ioVNmAlBlks;
   unsigned long ioVAlBlkSiz;
   unsigned long ioVClpSiz;
   unsigned short ioAlBlSt;
   unsigned long ioVNxtFNum;
   unsigned short ioVFrBlk;
};
typedef struct VolumeParam VolumeParam;
   typedef VolumeParam * VolumeParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).
ioVRefNum: A volume reference number, 0 for the default volume, or a drive number.
filler2: Reserved.
ioVolIndex: The volume index.
ioVCrDate: The date and time of the volume’s initialization.
ioVLsBkUp: 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. See “Volume Information Attribute Constants” for the meanings of the bits in this field.
ioVNmFls: The number of files in the root directory.
ioVDirSt: The first block of the volume directory.
ioVBlLn: Length of directory in blocks.
ioVNmAlBlks: The number of allocation blocks.
ioVAlBlkSiz: The size of allocation blocks.
ioVClpSiz: The volume clump size.
ioAlBlSt: The first block in the volume map.
ioVNxtFNum: The next unused file number.
ioVFrBlk: The number of unused allocation blocks.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

VolumeType

Defines the “signature” of the file system.

typedef OSType VolumeType;

Availability

Available in OS X v10.0 and later.

Declared In

Files.h

WDParam

Defines a parameter block used by low-level HFS working directory functions.

struct WDParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   short ioWDCreated;
   short ioWDIndex;
   long ioWDProcID;
   short ioWDVRefNum;
   short filler10;
   long filler11;
   long filler12;
   long filler13;
   long ioWDDirID;
};
typedef struct WDParam WDParam;
   typedef WDParam * WDParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).
ioVRefNum: A volume reference number, 0 for the default volume, or a drive number.
ioWDCreated
ioWDIndex: An index to working directories.
ioWDProcID
ioWDVRefNum: The volume reference number for the working directory.
filler10: Reserved.
filler11: Reserved.
filler12: Reserved.
filler13: The working directory’s directory ID.
ioWDDirID: The working directory’s directory ID.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

WDPBRec

Defines a working directory parameter block.

struct WDPBRec {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   short filler1;
   short ioWDIndex;
   long ioWDProcID;
   short ioWDVRefNum;
   short filler2[7];
   long ioWDDirID;
};
typedef struct WDPBRec WDPBRec;
   typedef WDPBRec * WDPBPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).
ioVRefNum: A volume reference number, 0 for the default volume, or a drive number.
filler1: Reserved.
ioWDIndex: An index.
ioWDProcID: An identifier that’s used to distinguish between working directories set up by different users you should set ioWDProcID to your application’s signature.
ioWDVRefNum: The working directory’s volume reference number.
filler2: Reserved.
ioWDDirID: The working directory’s directory ID.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

XCInfoPBRec

Defines an extended catalog information parameter block.

struct XCInfoPBRec {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   ProcPtr ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   long filler1;
   StringPtr ioShortNamePtr;
   short filler2;
   short ioPDType;
   long ioPDAuxType;
   long filler3[2];
   long ioDirID;
};
typedef struct XCInfoPBRec XCInfoPBRec;
   typedef XCInfoPBRec * XCInfoPBPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).
ioVRefNum: A volume reference number, 0 for the default volume, or a drive number.
filler1: Reserved; set this field to 0.
ioShortNamePtr: A pointer to a Pascal string buffer, of a minimum 13 bytes, which holds the file or directory’s short name (MS-DOS format name). This field is required and cannot be NULL.
filler2: Reserved; set this field to 0.
ioPDType: The ProDOS file type of the file or directory.
ioPDAuxType: The ProDOS auxiliary type of the file or directory.
filler3: Reserved; set this field to 0.
ioDirID: A directory ID.

Discussion

The PBGetXCatInfoSync and PBGetXCatInfoAsync functions use this parameter block to return the short name and ProDOS information for files and directories.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

XIOParam

Defines an extended I/O parameter block structure.

struct XIOParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   short ioRefNum;
   SInt8 ioVersNum;
   SInt8 ioPermssn;
   Ptr ioMisc;
   Ptr ioBuffer;
   long ioReqCount;
   long ioActCount;
   short ioPosMode;
   wide ioWPosOffset;
};
typedef struct XIOParam XIOParam;
   typedef XIOParam * XIOParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.

ioCmdAddr

The address of the function that was called. This field is used internally by the File Manager.

ioCompletion

ioResult

ioNamePtr

ioVRefNum

A volume reference number, 0 for the default volume, or a drive number.

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. See “File Access Permission Constants.”

ioMisc

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 or written.

ioActCount

The number of bytes actually read or written.

ioPosMode

The positioning mode (base location) for setting the mark. Bits 0 and 1 of this field indicate how to position the mark; you can use the constants described in “Position Mode Constants” to set or test their value. For the functions which use this parameter block, you must have the kUseWidePositioning bit set. See “Large Volume Constants” for a description of this and other constants.

You can also use the constants described in “Cache Constants” to indicate whether or not to cache the data.

ioWPosOffset

The wide positioning offset to be used in conjunction with the positioning mode specified in the ioPosMode field.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

XVolumeParam

Defines an extended volume information parameter block.

struct XVolumeParam {
   QElemPtr qLink;
   short qType;
   short ioTrap;
   Ptr ioCmdAddr;
   IOCompletionUPP ioCompletion;
   volatile OSErr ioResult;
   StringPtr ioNamePtr;
   short ioVRefNum;
   unsigned long ioXVersion;
   short ioVolIndex;
   unsigned long ioVCrDate;
   unsigned long ioVLsMod;
   short ioVAtrb;
   unsigned short ioVNmFls;
   unsigned short ioVBitMap;
   unsigned short ioAllocPtr;
   unsigned short ioVNmAlBlks;
   unsigned long ioVAlBlkSiz;
   unsigned long ioVClpSiz;
   unsigned short ioAlBlSt;
   unsigned long ioVNxtCNID;
   unsigned short ioVFrBlk;
   unsigned short ioVSigWord;
   short ioVDrvInfo;
   short ioVDRefNum;
   short ioVFSID;
   unsigned long ioVBkUp;
   short ioVSeqNum;
   unsigned long ioVWrCnt;
   unsigned long ioVFilCnt;
   unsigned long ioVDirCnt;
   long ioVFndrInfo[8];
   UInt64 ioVTotalBytes;
   UInt64 ioVFreeBytes;
};
typedef struct XVolumeParam XVolumeParam;
   typedef XVolumeParam * XVolumeParamPtr;

Fields

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 function that was called. This field is used internally by the File Manager.
ioCmdAddr: The address of the function that was called. This field is used internally by the File Manager.
ioCompletion: A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr 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 function 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 NULL (if you’re not).
ioVRefNum: A volume reference number, 0 for the default volume, or a drive number.
ioXVersion: The version of the XVolumeParam parameter block; currently, this is 0.
ioVolIndex: A volume index for use with the PBXGetVolInfoSync and PBXGetVolInfoAsync functions.
ioVCrDate: The date and time that the volume was created (initialized).
ioVLsMod: The date and time that 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. See “Volume Information Attribute Constants” for the meanings of the bits in this field.
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 the 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 the ioVDrvInfo field.
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 that the volume was last backed up; this is 0 if the volume has never been 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.
ioVTotalBytes: The total number of bytes on the volume.
ioVFreeBytes: The number of free bytes on the volume.

Discussion

The functions PBXGetVolInfoSync and PBXGetVolInfoAsync use this parameter block structure to pass arguments and return values.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Files.h

Constants

AFP Tag Length Constants

Specify the length of tagged address information for AppleShare volumes.

enum {
   kAFPTagLengthIP = 0x06,
   kAFPTagLengthIPPort = 0x08,
   kAFPTagLengthDDP = 0x06
};

Constants

kAFPTagLengthIP

The length of a 4 byte IP address.

Available in OS X v10.0 and later.

Declared in Files.h.

kAFPTagLengthIPPort

The length of a 4 byte IP address and a 2 byte port.

Available in OS X v10.0 and later.

Declared in Files.h.

kAFPTagLengthDDP

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

These constants are used in the fLength field of the AFPTagData structure to indicate the length, in bytes, of the tagged address information. This length includes the fLength field itself.

AFP Tag Type Constants

Specify the type of tagged address information for AppleShare clients.

enum {
   kAFPTagTypeIP = 0x01,
   kAFPTagTypeIPPort = 0x02,
   kAFPTagTypeDDP = 0x03,
   kAFPTagTypeDNS = 0x04
};

Constants

kAFPTagTypeIP

A basic 4 byte IP address, most significant byte first.

Available in OS X v10.0 and later.

Declared in Files.h.

kAFPTagTypeIPPort

A 4 byte IP address and a 2 byte port number, most significant byte first.

Available in OS X v10.0 and later.

Declared in Files.h.

kAFPTagTypeDDP

Available in OS X v10.0 and later.

Declared in Files.h.

kAFPTagTypeDNS

The address is a DNS name in address:port format. The total length of the DNS name is variable up to 254 characters.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

These constants are used in the fType field of the tagged address structure, AFPTagData, to specify the type of address represented by the structure.

Allocation Flags

Indicate how new space is to be allocated.

typedef UInt16 FSAllocationFlags;
enum {
   kFSAllocDefaultFlags = 0x0000,
   kFSAllocAllOrNothingMask = 0x0001,
   kFSAllocContiguousMask = 0x0002,
   kFSAllocNoRoundUpMask = 0x0004,
   kFSAllocReservedMask = 0xFFF8
};

Constants

kFSAllocDefaultFlags

Allocate as much as possible, not necessarily contiguous.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSAllocAllOrNothingMask

This bit is set when an allocation must allocate the total requested amount, or else fail with nothing allocated; when this bit is not set, the allocation may complete successfully but allocate less than requested.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSAllocContiguousMask

This bit is set when an allocation should allocate one contiguous range of space on the volume. If this bit is clear, multiple discontiguous extents may be allocated to fulfill the request.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSAllocNoRoundUpMask

This bit is set when an allocation should no round up to the clump size. If this bit is clear, then additional space beyond the amount requested may be allocated; this is done by some volume formats (including HFS and HFS Plus) to avoid many small allocation requests. If the bit is set, no additional allocation is done (except where required by the volume format, such as rounding up to a multiple of the allocation block size).

Available in OS X v10.0 and later.

Declared in Files.h.

kFSAllocReservedMask

Reserved; set to zero.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

If the kFSAllocContiguousMask bit is set, then then any newly allocated space must be in one contiguous extent (preferably contiguous with any space already allocated). If kFSAllocAllOrNothingMask is set, then the entire requestCount bytes must be allocated for the call to succeed; if not set, as many bytes as possible will be allocated (without error). If kFSAllocNoRoundUpMask is set, then no additional space is allocated (such as rounding up to a multiple of a clump size); if clear, the volume format may allocate more space than requested as an attempt to reduce fragmentation.

AppleShare Volume Signature

Defines the volume signature for AppleShare volumes.

enum {
   AppleShareMediaType = 'afpm'
};

Authentication Method Constants

Define the login methods for remote volumes.

enum {
   kNoUserAuthentication = 1,
   kPassword = 2,
   kEncryptPassword = 3,
   kTwoWayEncryptPassword = 6
};

Constants

kNoUserAuthentication

No password.

Available in OS X v10.0 and later.

Declared in Files.h.

kPassword

8-byte password.

Available in OS X v10.0 and later.

Declared in Files.h.

kEncryptPassword

Encrypted 8-byte password.

Available in OS X v10.0 and later.

Declared in Files.h.

kTwoWayEncryptPassword

Two-way random encryption.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

These constants are used in the uamType field of an AFPVolMountInfo structure and in the ioObjType field of the parameter block passed to the PBHGetLogInInfoSync and PBHGetLogInInfoAsync functions to specify the type of user authentication used by a remote volume.

Cache Constants

Indicate whether or not data should be cached.

enum {
   pleaseCacheBit = 4,
   pleaseCacheMask = 0x0010,
   noCacheBit = 5,
   noCacheMask = 0x0020,
   rdVerifyBit = 6,
   rdVerifyMask = 0x0040,
   rdVerify = 64,
   forceReadBit = 6,
   forceReadMask = 0x0040,
   newLineBit = 7,
   newLineMask = 0x0080,
   newLineCharMask = 0xFF00
};

Constants

pleaseCacheBit

Indicates that the data should be cached.

Available in OS X v10.0 and later.

Declared in Files.h.

pleaseCacheMask

Requests that the data be cached, if possible. You should cache reads and writes if you read or write the same portion of a file multiple times.

Available in OS X v10.0 and later.

Declared in Files.h.

noCacheBit

Indicates that data should not be cached.

Available in OS X v10.0 and later.

Declared in Files.h.

noCacheMask

Requests that the data not be cached, if possible. You should not cache reads and writes if you read or write data from a file only once.

Available in OS X v10.0 and later.

Declared in Files.h.

rdVerifyBit

Indicates that all reads should come from the source and be verified against the data in memory.

Available in OS X v10.0 and later.

Declared in Files.h.

rdVerifyMask

Requests that all reads (not writes) come directly from the source and be verified against the data in memory. This flushes the cache and sends all read requests to the data source.

Available in OS X v10.0 and later.

Declared in Files.h.

rdVerify

This is the old name of rdVerifyMask. Both request that all reads come directly from the source of the data and be compared against the data in memory.

Available in OS X v10.0 and later.

Declared in Files.h.

forceReadBit

Indicates that reads should come from the disk.

Available in OS X v10.0 and later.

Declared in Files.h.

forceReadMask

Forces reads from disk, bypassing all caches. Clients can use this to verify that data is stored correctly on the media (for example, to verify after writing) by reading the data into a different buffer while setting the bit, and then comparing the newly read data with the previously written data.

The forceReadMask is the same as the rdVerifyMask used in the older APIs. The actual implementation of the rdVerifyMask in the older APIs actually caused the “force read” behavior, and only compared the data in partial sectors. FSReadFork cleans up this behavior by always letting the client do all of the compares.

Available in OS X v10.0 and later.

Declared in Files.h.

newLineBit

Indicates that newline mode should be used for reads.

Available in OS X v10.0 and later.

Declared in Files.h.

newLineMask

Requests that newline mode be used for reads. In newline mode, the read stops when one of the following conditions is met:

The requested number of bytes have been read.
The end-of-file is reached.
The newline character has been read. If the newline character is found, it will be the last character put into the buffer and the number of bytes read will include it.

Available in OS X v10.0 and later.

Declared in Files.h.

newLineCharMask

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

For the FSReadFork and FSWriteFork functions, and their parameter block equivalents, you may add either of the pleaseCacheMask or noCacheMask constants to one of the “Position Mode Constants” to hint whether the data should be cached or not.

The pleaseCacheBit and the noCacheBit are mutually exclusive and only one should be set at a time. If neither bit is set, the program has indicated that it doesn’t care if the data is cached or not.

Catalog Information Bitmap Constants

Specify what file or fork information to get or set.

enum {
   kFSCatInfoNone = 0x00000000,
   kFSCatInfoTextEncoding = 0x00000001,
   kFSCatInfoNodeFlags = 0x00000002,
   kFSCatInfoVolume = 0x00000004,
   kFSCatInfoParentDirID = 0x00000008,
   kFSCatInfoNodeID = 0x00000010,
   kFSCatInfoCreateDate = 0x00000020,
   kFSCatInfoContentMod = 0x00000040,
   kFSCatInfoAttrMod = 0x00000080,
   kFSCatInfoAccessDate = 0x00000100,
   kFSCatInfoBackupDate = 0x00000200,
   kFSCatInfoPermissions = 0x00000400,
   kFSCatInfoFinderInfo = 0x00000800,
   kFSCatInfoFinderXInfo = 0x00001000,
   kFSCatInfoValence = 0x00002000,
   kFSCatInfoDataSizes = 0x00004000,
   kFSCatInfoRsrcSizes = 0x00008000,
   kFSCatInfoSharingFlags = 0x00010000,
   kFSCatInfoUserPrivs = 0x00020000,
   kFSCatInfoUserAccess = 0x00080000,
   kFSCatInfoSetOwnership = 0x00100000,
   kFSCatInfoAllDates = 0x000003E0,
   kFSCatInfoGettableInfo = 0x0003FFFF,
   kFSCatInfoSettableInfo = 0x00001FE3,
   kFSCatInfoReserved = 0xFFFC0000
};

Constants

kFSCatInfoNone

No catalog information.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoTextEncoding

Retrieve or set the text encoding hint, in the textEncodingHint field.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoNodeFlags

Retrieve or set the catalog node flags. Currently, you can only set bits 0 and 4. See “Catalog Information Node Flags” for more information on these flags.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoVolume

Retrieve the volume reference number of the volume on which the file or directory resides.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoParentDirID

Retrieve the parent directory ID.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoNodeID

Retrieve the file or directory ID.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoCreateDate

Retrieve or set the creation date.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoContentMod

Retrieve or set the date that the resource or data fork was last modified.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoAttrMod

Retrieve or set the date that an attribute or named fork was last modified.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoAccessDate

Retrieve or set the date that the fork or file was last accessed.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoBackupDate

Retrieve or set the date that the fork or file was last backed up.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoPermissions

Retrieve or set the file or fork’s permissions.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoFinderInfo

Retrieve or set the file or fork’s Finder information.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoFinderXInfo

Retrieve or set the file or fork’s extended Finder information.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoValence

For folders only, retrieve the valence of the folder. For files, this is zero.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoDataSizes

Retrieve the logical and physical size of the data fork.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoRsrcSizes

Retrieve the logical and physical size of the resource fork.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoSharingFlags

Retrieve the fork or file’s sharing flags: kioFlAttribMountedBit, kioFlAttribSharePointBit. See “File Attribute Constants” for more information on these bits.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoUserPrivs

Retrieve the file’s user privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoUserAccess

Available in OS X v10.1 and later.

Declared in Files.h.

kFSCatInfoSetOwnership

Attempt to set the file’s user and group (UID and GID). If the File Manager cannot set the the user or group ID, the call fails. (OS X only).

Available in OS X v10.3 and later.

Declared in Files.h.

kFSCatInfoAllDates

Retrieve or set all of the date information for the fork or file: creation date, modification dates, access date, backup date, etc.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoGettableInfo

Retrieve all gettable data.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoSettableInfo

Set all settable data. This includes the flags, dates, permissions, Finder info, and text encoding hint.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSCatInfoReserved

Represents bits that are currently reserved.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

These constants are used in the FSCatalogInfoBitmap type to specify what file or fork information to get or set. If used with the FSGetCatalogInfo or FSGetCatalogInfoBulk functions, these constants tell the File Manager which fields to return information in. If used with the FSSetCatalogInfo function, these constants tell the File Manager which fields you’ve filled out with values that it should use to change the fork or file’s catalog information.

Catalog Information Node Flags

Define the values used in the nodeFlags field of the FSCatalogInfo structure.

enum {
   kFSNodeLockedBit = 0,
   kFSNodeLockedMask = 0x0001,
   kFSNodeResOpenBit = 2,
   kFSNodeResOpenMask = 0x0004,
   kFSNodeDataOpenBit = 3,
   kFSNodeDataOpenMask = 0x0008,
   kFSNodeIsDirectoryBit = 4,
   kFSNodeIsDirectoryMask = 0x0010,
   kFSNodeCopyProtectBit = 6,
   kFSNodeCopyProtectMask = 0x0040,
   kFSNodeForkOpenBit = 7,
   kFSNodeForkOpenMask = 0x0080,
   kFSNodeHardLinkBit = 8,
   kFSNodeHardLinkMask = 0x00000100
};

Constants

kFSNodeLockedBit

Set if the file or directory is locked.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSNodeLockedMask

Indicates that the file or directory is locked.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSNodeResOpenBit

Set if the resource fork is open.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSNodeResOpenMask

Indicates that the resource fork is open.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSNodeDataOpenBit

Set if the data fork is open.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSNodeDataOpenMask

Indicates that the data fork is open.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSNodeIsDirectoryBit

Set if the object is a directory.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSNodeIsDirectoryMask

Indicates that the object is a directory.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSNodeCopyProtectBit

Set of the file or directory is copy protected.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSNodeCopyProtectMask

Indicates that the file or directory is copy protected.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSNodeForkOpenBit

Set if the file or directory has any open fork.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSNodeForkOpenMask

Indicates that the file or directory has an open fork of any type.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSNodeHardLinkBit

Available in OS X v10.2 and later.

Declared in Files.h.

kFSNodeHardLinkMask

Available in OS X v10.2 and later.

Declared in Files.h.

Catalog Information Sharing Flags

Indicate the status of a shared directory.

enum {
   kFSNodeInSharedBit = 2,
   kFSNodeInSharedMask = 0x0004,
   kFSNodeIsMountedBit = 3,
   kFSNodeIsMountedMask = 0x0008,
   kFSNodeIsSharePointBit = 5,
   kFSNodeIsSharePointMask = 0x0020
};

Constants

kFSNodeInSharedBit

Set if a directory is within a share point.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSNodeInSharedMask

Indicates that the directory is within a share point.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSNodeIsMountedBit

Set if a directory is a share point currently mounted by some user.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSNodeIsMountedMask

Indicates that the directory is a share point currently mounted by some user.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSNodeIsSharePointBit

Set if a directory is a share point (an exported volume).

Available in OS X v10.0 and later.

Declared in Files.h.

kFSNodeIsSharePointMask

Indicates that the directory is a share point (an exported volume).

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

The FSCatalogInfo structure uses these constants in its sharingFlags field.

Catalog Search Bits

Indicate the criteria for a catalog search.

enum {
   fsSBPartialNameBit = 0,
   fsSBFullNameBit = 1,
   fsSBFlAttribBit = 2,
   fsSBFlFndrInfoBit = 3,
   fsSBFlLgLenBit = 5,
   fsSBFlPyLenBit = 6,
   fsSBFlRLgLenBit = 7,
   fsSBFlRPyLenBit = 8,
   fsSBFlCrDatBit = 9,
   fsSBFlMdDatBit = 10,
   fsSBFlBkDatBit = 11,
   fsSBFlXFndrInfoBit = 12,
   fsSBFlParIDBit = 13,
   fsSBNegateBit = 14,
   fsSBDrUsrWdsBit = 3,
   fsSBDrNmFlsBit = 4,
   fsSBDrCrDatBit = 9,
   fsSBDrMdDatBit = 10,
   fsSBDrBkDatBit = 11,
   fsSBDrFndrInfoBit = 12,
   fsSBDrParIDBit = 13
};

Constants

fsSBPartialNameBit

Indicates a search by a substring of the name.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFullNameBit

Indicates a search by the full name.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlAttribBit

Indicates a search by the file or directory attributes.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlFndrInfoBit

For files only indicates a search by the file’s Finder info.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlLgLenBit

For files only; indicates a search by the logical length of the data fork.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlPyLenBit

For files only; indicates a search by the physical length of the data fork.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlRLgLenBit

For files only; indicates a search for the logical length of the resource fork.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlRPyLenBit

For files only; indicates a search by the physical length of the resource fork.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlCrDatBit

For files only indicates a search by the file’s creation date.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlMdDatBit

For files only indicates a search by the date of the file’s last modification.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlBkDatBit

For files only indicates a search by the date of the file’s last backup.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlXFndrInfoBit

For files only indicates a search by the file’s extended Finder info.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlParIDBit

For files only indicates a search by the file’s parent ID.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBNegateBit

Indicates a search for all non-matches. That is, if a file or directory matches one of the other specified criteria, it is not returned; if it does not match any of the specified criteria, it is returned.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBDrUsrWdsBit

For directories only indicates a search by the directory’s Finder info.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBDrNmFlsBit

For directories only; indicates a search by the number of files in the directory.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBDrCrDatBit

For directories only indicates a search by the directory’s creation date.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBDrMdDatBit

For directories only indicates a search by the date of the directory’s last modification.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBDrBkDatBit

For directories only indicates a search by the date of the directory’s last backup.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBDrFndrInfoBit

For directories only indicates a search by the directory’s additional Finder info.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBDrParIDBit

For directories only indicates a search by the directory’s parent ID.

Available in OS X v10.0 and later.

Declared in Files.h.

Catalog Search Constants

Specify the which catalog information fields to use as search criteria.

enum {
   fsSBNodeID = 0x00008000,
   fsSBAttributeModDate = 0x00010000,
   fsSBAccessDate = 0x00020000,
   fsSBPermissions = 0x00040000,
   fsSBNodeIDBit = 15,
   fsSBAttributeModDateBit = 16,
   fsSBAccessDateBit = 17,
   fsSBPermissionsBit = 18
};

Constants

fsSBNodeID

Search by a range of catalog node ID.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBAttributeModDate

Search by a range of attribute (fork) modification date.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBAccessDate

Search by a range of access date.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBPermissions

Search by a value or mask of permissions.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBNodeIDBit

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBAttributeModDateBit

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBAccessDateBit

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBPermissionsBit

Available in OS X v10.0 and later.

Declared in Files.h.

Catalog Search Masks

Specify the criteria for a catalog search.

enum {
   fsSBPartialName = 1,
   fsSBFullName = 2,
   fsSBFlAttrib = 4,
   fsSBFlFndrInfo = 8,
   fsSBFlLgLen = 32,
   fsSBFlPyLen = 64,
   fsSBFlRLgLen = 128,
   fsSBFlRPyLen = 256,
   fsSBFlCrDat = 512,
   fsSBFlMdDat = 1024,
   fsSBFlBkDat = 2048,
   fsSBFlXFndrInfo = 4096,
   fsSBFlParID = 8192,
   fsSBNegate = 16384,
   fsSBDrUsrWds = 8,
   fsSBDrNmFls = 16,
   fsSBDrCrDat = 512,
   fsSBDrMdDat = 1024,
   fsSBDrBkDat = 2048,
   fsSBDrFndrInfo = 4096,
   fsSBDrParID = 8192
};

Constants

fsSBPartialName

Search by a substring of the name.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFullName

Search by the full name.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlAttrib

Search by the file or directory attributes. You can use the attributes to specify that you are searching for a directory, or for a file or directory that is locked by software.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlFndrInfo

For files only search by the file’s Finder info.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlLgLen

For files only; search by the logical length of the data fork.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlPyLen

For files only; search by the physical length of the data fork.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlRLgLen

For files only; search for the logical length of the resource fork.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlRPyLen

For files only; search by the physical length of the resource fork.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlCrDat

For files only search by the file’s creation date.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlMdDat

For files only search by the date of the file’s last modification.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlBkDat

For files only search by the date of the file’s last backup.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlXFndrInfo

For files only search by the file’s extended Finder info.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBFlParID

For files only search by the file’s parent ID.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBNegate

Search for all non-matches. That is, if a file or directory matches one of the other specified criteria, it is not returned; if it does not match any of the specified criteria, it is returned.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBDrUsrWds

For directories only search by the directory’s Finder info.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBDrNmFls

For directories only; search by the number of files in the directory.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBDrCrDat

For directories only search by the directory’s creation date.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBDrMdDat

For directories only search by the date of the directory’s last modification.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBDrBkDat

For directories only search by the date of the directory’s last backup.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBDrFndrInfo

For directories only search by the directory’s additional Finder info.

Available in OS X v10.0 and later.

Declared in Files.h.

fsSBDrParID

For directories only search by the directory’s parent ID.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

Use these constants in the ioSearchBits field of the PBCatSearchSync and PBCatSearchAsync functions to specify the criteria for your search.

Extended AFP Volume Mounting Information Flag

Specifies a flag used in the extendedFlags field of the AFPXVolMountInfo structure.

enum {
   kAFPExtendedFlagsAlternateAddressMask = 1
};

Constants

kAFPExtendedFlagsAlternateAddressMask

Indicates that the alternateAddressOffset field in the AFPXVolMountInfo record is used.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

See the AFPXVolMountInfo structure for more information.

Extended Volume Attributes

Describe a volume’s extended attributes.

enum {
   bIsEjectable = 0,
   bSupportsHFSPlusAPIs = 1,
   bSupportsFSCatalogSearch = 2,
   bSupportsFSExchangeObjects = 3,
   bSupports2TBFiles = 4,
   bSupportsLongNames = 5,
   bSupportsMultiScriptNames = 6,
   bSupportsNamedForks = 7,
   bSupportsSubtreeIterators = 8,
   bL2PCanMapFileBlocks = 9,
   bParentModDateChanges = 10,
   bAncestorModDateChanges = 11,
   bSupportsSymbolicLinks = 13,
   bIsAutoMounted = 14,
   bAllowCDiDataHandler = 17,
   bSupportsExclusiveLocks = 18,
   bSupportsJournaling = 19,
   bNoVolumeSizes = 20,
   bIsOnInternalBus = 21,
   bIsCaseSensitive = 22,
   bIsCasePreserving = 23,
   bDoNotDisplay = 24,
   bIsRemovable = 25,
   bNoRootTimes = 26,
   bIsOnExternalBus = 27,
   bSupportsExtendedFileSecurity = 28
};

Constants

bIsEjectable

The volume is in an ejectable disk drive .

Available in OS X v10.0 and later.

Declared in Files.h.

bSupportsHFSPlusAPIs

The volume supports the HFS Plus APIs directly, i.e., the File Manager does not emulate them.

Available in OS X v10.0 and later.

Declared in Files.h.

bSupportsFSCatalogSearch

The volume supports the FSCatalogSearch operation.

Available in OS X v10.0 and later.

Declared in Files.h.

bSupportsFSExchangeObjects

The volume supports the FSExchangeObjects function.

Available in OS X v10.0 and later.

Declared in Files.h.

bSupports2TBFiles

The volume supports 2 terabyte files.

Available in OS X v10.0 and later.

Declared in Files.h.

bSupportsLongNames

The volume supports file, directory, and volume names longer than 31 characters.

Available in OS X v10.0 and later.

Declared in Files.h.

bSupportsMultiScriptNames

The volume supports file, directory, and volume names with characters from multiple script systems.

Available in OS X v10.0 and later.

Declared in Files.h.

bSupportsNamedForks

The volume supports named forks other than the data and resource forks.

Available in OS X v10.0 and later.

Declared in Files.h.

bSupportsSubtreeIterators

The volume supports recursive iterators, not at the volume root.

Available in OS X v10.0 and later.

Declared in Files.h.

bL2PCanMapFileBlocks

The volume supports the Lg2Phys SPI correctly.

Available in OS X v10.0 and later.

Declared in Files.h.

bParentModDateChanges

On this volume, changing a file or folder causes its parent's modification date to change.

Available in OS X v10.0 and later.

Declared in Files.h.

bAncestorModDateChanges

On this volume, changing a file or folder causes all ancestor modification dates to change.

Available in OS X v10.0 and later.

Declared in Files.h.

bSupportsSymbolicLinks

The volume supports the creation and use of symbolic links (OS X only).

Available in OS X v10.0 and later.

Declared in Files.h.

bIsAutoMounted

The volume was mounted automatically (OS X only).

Available in OS X v10.0 and later.

Declared in Files.h.

bAllowCDiDataHandler

QuickTime's CDi data handler is allowed to examine the volume.

Available in OS X v10.1 and later.

Declared in Files.h.

bSupportsExclusiveLocks

The volume supports exclusive access to files opened for writing.

Available in OS X v10.2 and later.

Declared in Files.h.

bSupportsJournaling

The volume supports journaling. This does not indicate whether journaling is currently enabled on the volume.

Available in OS X v10.3 and later.

Declared in Files.h.

bNoVolumeSizes

The volume is unable to report volume size or free space.

Available in OS X v10.3 and later.

Declared in Files.h.

bIsOnInternalBus

The device is on an internal bus. See note below.

Available in OS X v10.4 and later.

Declared in Files.h.

bIsCaseSensitive

The volume is case-sensitive.

Available in OS X v10.3 and later.

Declared in Files.h.

bIsCasePreserving

The volume is preserves case.

Available in OS X v10.3 and later.

Declared in Files.h.

bDoNotDisplay

The volume should not be displayed in the user interface.

Available in OS X v10.3 and later.

Declared in Files.h.

bIsRemovable

The device is removable according to IOKit.

Available in OS X v10.4 and later.

Declared in Files.h.

bNoRootTimes

The volume does not set reliable times for its root directory.

Available in OS X v10.4 and later.

Declared in Files.h.

bIsOnExternalBus

The device is on an external bus. See note below.

Available in OS X v10.4 and later.

Declared in Files.h.

bSupportsExtendedFileSecurity

The volume supports FSFileSecurity objects.

Available in OS X v10.4 and later.

Declared in Files.h.

Discussion

The GetVolParmsInfoBuffer structure uses these constants in its vMExtendedAttributes field.

FCB Flags

Specify flags that describe the state of a file.

enum {
   kioFCBWriteBit = 8,
   kioFCBWriteMask = 0x0100,
   kioFCBResourceBit = 9,
   kioFCBResourceMask = 0x0200,
   kioFCBWriteLockedBit = 10,
   kioFCBWriteLockedMask = 0x0400,
   kioFCBLargeFileBit = 11,
   kioFCBLargeFileMask = 0x0800,
   kioFCBSharedWriteBit = 12,
   kioFCBSharedWriteMask = 0x1000,
   kioFCBFileLockedBit = 13,
   kioFCBFileLockedMask = 0x2000,
   kioFCBOwnClumpBit = 14,
   kioFCBOwnClumpMask = 0x4000,
   kioFCBModifiedBit = 15,
   kioFCBModifiedMask = 0x8000
};

Constants

kioFCBWriteBit

Set if data can be written to this file.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFCBWriteMask

Tests if data can be written to this file.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFCBResourceBit

Set if this FCB describes a resource fork.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFCBResourceMask

Tests if this FCB describes a resource fork.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFCBWriteLockedBit

Set if this file has a locked byte range.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFCBWriteLockedMask

Tests if this file has a locked byte range.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFCBLargeFileBit

Set if this file may grow beyond 2GB and the cache uses file blocks, not bytes.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFCBLargeFileMask

Tests if this file may grow beyond 2GB and the cache uses file blocks, not bytes.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFCBSharedWriteBit

Set if this file has shared write permissions.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFCBSharedWriteMask

Tests if this file has shared write permissions.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFCBFileLockedBit

Set if this file is locked (write-protected).

Available in OS X v10.0 and later.

Declared in Files.h.

kioFCBFileLockedMask

Tests if this file is locked (write-protected).

Available in OS X v10.0 and later.

Declared in Files.h.

kioFCBOwnClumpBit

Set if this file’s clump size is specified in the FCB.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFCBOwnClumpMask

Tests if this file’s clump size is specified in the FCB.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFCBModifiedBit

Set if this file has changed since it was last flushed.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFCBModifiedMask

Tests if this file has changed since it was last flushed.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

These constants are used in the ioFCBFlags field of the FCBPBRec returned by the functions PBGetFCBInfoSync and PBGetFCBInfoAsync .

File Access Permission Constants

Specify the type of read and write access to a file or fork.

enum {
   fsCurPerm = 0x00,
   fsRdPerm = 0x01,
   fsWrPerm = 0x02,
   fsRdWrPerm = 0x03,
   fsRdWrShPerm = 0x04,
   fsRdDenyPerm = 0x10,
   fsWrDenyPerm = 0x20
};

Constants

fsCurPerm

Requests whatever permissions are currently allowed. If write access in unavailable (because the file is locked or the file is already open with write permission), then read permission is granted. Otherwise read/write permission is granted.

Available in OS X v10.0 and later.

Declared in Files.h.

fsRdPerm

Requests permission to read the file.

Available in OS X v10.0 and later.

Declared in Files.h.

fsWrPerm

Requests permission to write to the file. If write permission is granted, no other access paths are granted write permission. Note, however, that the File Manager does not support write-only access to a file. Thus, fsWrPerm is synonymous with fsRdWrPerm.

Available in OS X v10.0 and later.

Declared in Files.h.

fsRdWrPerm

Requests exclusive read and write permission. If exclusive read/ write permission is granted, no other users are granted permission to write to the file. Other users may, however, be granted permission to read the file.

Available in OS X v10.0 and later.

Declared in Files.h.

fsRdWrShPerm

Requests shared read and write permission. Shared read and write permission allows multiple access paths for reading and writing. This is safe only if there is some way of locking portions of the file before writing to them. On volumes that support range locking, you can use the functions PBLockRangeSync and PBUnlockRangeSync to lock and unlock ranges of bytes within a file. Applications running in OS X version 10.4 or later should use the functions FSLockRange and FSUnlockRange for this purpose.

Available in OS X v10.0 and later.

Declared in Files.h.

fsRdDenyPerm

Requests that any other paths be prevented from having read access. A path cannot be opened if you request read permission (with the fsRdPerm constant) but some other path has requested deny-read access. Similarly, the path cannot be opened if you request deny-read permission, but some other path already has read access. This constant is only supported on volumes which return the bHasOpenDeny attribute when you call FSGetVolumeParms.

Available in OS X v10.0 and later.

Declared in Files.h.

fsWrDenyPerm

Requests that any other paths be prevented from having write access. A path cannot be opened if you request write permission (with the fsWrPerm constant) but some other path has requested deny-write access. Similarly, the path cannot be opened if you request deny-write permission, but some other path already has write access. This constant is only supported on volumes which return the bHasOpenDeny attribute when you call FSGetVolumeParms.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

Use these constants to request a type of access to a file or fork, or to deny a type of access to a file or fork to other paths that may request access.

Note that it is possible, in Mac OS 8 and 9, to open a file residing on read-only media with write access. In OS X, however, you cannot open a file with write access on read-only media; the attempt to open the file fails with a wrPermErr error.

File and Folder Access Privilege Constants

Specify access privileges for files and directories in the ioACAccess field of the AccessParam data type.

enum {
   kioACAccessOwnerBit = 31,
   kioACAccessOwnerMask = 0x80000000,
   kioACAccessBlankAccessBit = 28,
   kioACAccessBlankAccessMask = 0x10000000,
   kioACAccessUserWriteBit = 26,
   kioACAccessUserWriteMask = 0x04000000,
   kioACAccessUserReadBit = 25,
   kioACAccessUserReadMask = 0x02000000,
   kioACAccessUserSearchBit = 24,
   kioACAccessUserSearchMask = 0x01000000,
   kioACAccessEveryoneWriteBit = 18,
   kioACAccessEveryoneWriteMask = 0x00040000,
   kioACAccessEveryoneReadBit = 17,
   kioACAccessEveryoneReadMask = 0x00020000,
   kioACAccessEveryoneSearchBit = 16,
   kioACAccessEveryoneSearchMask = 0x00010000,
   kioACAccessGroupWriteBit = 10,
   kioACAccessGroupWriteMask = 0x00000400,
   kioACAccessGroupReadBit = 9,
   kioACAccessGroupReadMask = 0x00000200,
   kioACAccessGroupSearchBit = 8,
   kioACAccessGroupSearchMask = 0x00000100,
   kioACAccessOwnerWriteBit = 2,
   kioACAccessOwnerWriteMask = 0x00000004,
   kioACAccessOwnerReadBit = 1,
   kioACAccessOwnerReadMask = 0x00000002,
   kioACAccessOwnerSearchBit = 0,
   kioACAccessOwnerSearchMask = 0x00000001,
   kfullPrivileges = 0x00070007,
   kownerPrivileges = 0x00000007
};

Constants

kioACAccessOwnerBit

Indicates that the user is the owner of the directory.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessOwnerMask

The user is the owner of the directory.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessBlankAccessBit

Indicates that the directory has blank access privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessBlankAccessMask

The directory has blank access privileges. A directory with blank access privileges set ignores the other access privilege bits and uses the access privilege bits of its parent directory.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessUserWriteBit

Indicates that the user has write privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessUserWriteMask

The user has write privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessUserReadBit

Indicates that the user has read privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessUserReadMask

The user has read privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessUserSearchBit

Indicates that the user has search privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessUserSearchMask

The user has search privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessEveryoneWriteBit

Indicates that everyone has write privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessEveryoneWriteMask

Everyone has write privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessEveryoneReadBit

Indicates that everyone has read privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessEveryoneReadMask

Everyone has read privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessEveryoneSearchBit

Indicates that everyone has search privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessEveryoneSearchMask

Everyone has search privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessGroupWriteBit

Indicates that the group has write privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessGroupWriteMask

The group has write privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessGroupReadBit

Indicates that the group has read privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessGroupReadMask

The group has read privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessGroupSearchBit

Indicates that the group has search privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessGroupSearchMask

The group has search privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessOwnerWriteBit

Indicates that the owner has write privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessOwnerWriteMask

The owner has write privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessOwnerReadBit

Indicates that the owner has read privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessOwnerReadMask

The owner has read privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessOwnerSearchBit

Indicates that the owner has search privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACAccessOwnerSearchMask

The owner has search privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kfullPrivileges

Indicates that everyone, including the owner, have all privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kownerPrivileges

Indicates that only the owner has all privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

See AccessParam.

File Attribute Constants

Define file and directory attributes returned by the PBGetCatInfoSync and PBGetCatInfoAsync functions.

enum {
   kioFlAttribLockedBit = 0,
   kioFlAttribLockedMask = 0x01,
   kioFlAttribResOpenBit = 2,
   kioFlAttribResOpenMask = 0x04,
   kioFlAttribDataOpenBit = 3,
   kioFlAttribDataOpenMask = 0x08,
   kioFlAttribDirBit = 4,
   kioFlAttribDirMask = 0x10,
   ioDirFlg = 4,
   ioDirMask = 0x10,
   kioFlAttribCopyProtBit = 6,
   kioFlAttribCopyProtMask = 0x40,
   kioFlAttribFileOpenBit = 7,
   kioFlAttribFileOpenMask = 0x80,
   kioFlAttribInSharedBit = 2,
   kioFlAttribInSharedMask = 0x04,
   kioFlAttribMountedBit = 3,
   kioFlAttribMountedMask = 0x08,
   kioFlAttribSharePointBit = 5,
   kioFlAttribSharePointMask = 0x20
};

Constants

kioFlAttribLockedBit

Indicates that the file or directory is locked. Use the functions PBHSetFLockSync and PBHSetFLockAsync to lock a file or directory. Use the functions PBHRstFLockSync and PBHRstFLockAsync to unlock a file or directory.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFlAttribLockedMask

Tests if the file or directory is locked.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFlAttribResOpenBit

Indicates that the resource fork is open. On OS X, this bit is not set if the resource fork of the file has been opened by a process other than the process making the call to PBHGetCatInfo or PBHGetFInfo.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFlAttribResOpenMask

Tests if the resource fork is open.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFlAttribDataOpenBit

Indicates that the data fork is open. On OS X, this bit is not set if the data fork of the file has been opened by a process other than the process making the call to PBHGetCatInfo or PBHGetFInfo.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFlAttribDataOpenMask

Tests if the data fork is open.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFlAttribDirBit

Indicates that this is a directory, not a file. This bit is always clear for files, and is always set for directories.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFlAttribDirMask

Tests if this is a directory.

Available in OS X v10.0 and later.

Declared in Files.h.

ioDirFlg

Indicates that this is a directory; this is the old name of the kioFlAttribDirBit.

Available in OS X v10.0 and later.

Declared in Files.h.

ioDirMask

Tests if this is a directory; this is the old name of the kioFlAttribDirMask.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFlAttribCopyProtBit

Indicates that the file is “copy-protected” by the AppleShare server.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFlAttribCopyProtMask

Tests if the file is “copy-protected” by the AppleShare server.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFlAttribFileOpenBit

Indicates that the file is open. This bit is set if either the data or the resource fork are open. On OS X, this bit is not set if the file has been opened by a process other than the process making the call to PBHGetCatInfo or PBHGetFInfo.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFlAttribFileOpenMask

Tests if the file is open. The file is open if either the data or the resource fork are open.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFlAttribInSharedBit

Indicates that the directory is within a shared area of the directory hierarchy.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFlAttribInSharedMask

Tests if the directory is within a shared area of the directory hierarchy.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFlAttribMountedBit

Indicates that the directory is a share point that is mounted by a user.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFlAttribMountedMask

Tests if the directory is a share point that is mounted by a user.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFlAttribSharePointBit

Indicates that the directory is a share point.

Available in OS X v10.0 and later.

Declared in Files.h.

kioFlAttribSharePointMask

Tests if the directory is a share point.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

These constants are used in the ioFlAttrib fields of the HFileInfo and DirInfo structures returned by the functions PBGetCatInfoSync and PBGetCatInfoAsync .

File Operation Options

Flags you can use to specify how to perform a file operation.

enum {
   kFSFileOperationDefaultOptions = 0,
   kFSFileOperationOverwrite = 0x01,
   kFSFileOperationSkipSourcePermissionErrors = 0x02,
   kFSFileOperationDoNotMoveAcrossVolumes = 0x04,
   kFSFileOperationSkipPreflight = 0x08
};

Constants

kFSFileOperationDefaultOptions

Use the following default options:

If the destination directory contains an object with the same name as a source object, abort the operation.
If a source object cannot be read, abort the operation.
If asked to move an object across volume boundaries, perform the operation.

Available in OS X v10.4 and later.

Declared in Files.h.

kFSFileOperationOverwrite

If the destination directory contains an object with the same name as a source object, overwrite the destination object.

Available in OS X v10.4 and later.

Declared in Files.h.

kFSFileOperationSkipSourcePermissionErrors

If a source object cannot be read, skip the object and continue the operation.

Available in OS X v10.4 and later.

Declared in Files.h.

kFSFileOperationDoNotMoveAcrossVolumes

If asked to move an object across volume boundaries, abort the operation.

Available in OS X v10.4 and later.

Declared in Files.h.

kFSFileOperationSkipPreflight

Skip the preflight stage for a directory move or copy operation. This option limits the status information that can be returned during the operation.

Available in OS X v10.4 and later.

Declared in Files.h.

Discussion

These flags may be passed to any of the functions that initiate a file operation. For more information, see “Copying and Moving Objects Using Asynchronous High-Level File Operations.”

File Operation Stages

Constants used by the File Manager to indicate the current stage of an asynchronous file operation.

typedef UInt32 FSFileOperationStage;
enum {
   kFSOperationStageUndefined = 0,
   kFSOperationStagePreflighting = 1,
   kFSOperationStageRunning = 2,
   kFSOperationStageComplete = 3
};

Constants

kFSOperationStageUndefined

The File Manager has not started the file operation.

Available in OS X v10.4 and later.

Declared in Files.h.

kFSOperationStagePreflighting

The File Manager is performing tasks such as calculating the sizes and number of objects in the operation, and checking to make sure there is enough space on the destination volume to complete the operation.

Available in OS X v10.4 and later.

Declared in Files.h.

kFSOperationStageRunning

The File Manager is copying or moving the file or directory.

Available in OS X v10.4 and later.

Declared in Files.h.

kFSOperationStageComplete

The file operation is complete.

Available in OS X v10.4 and later.

Declared in Files.h.

Discussion

These constants are passed back to your file operation status callback function. For more information, see “File Operation Callbacks.” You can also get the current stage of a file operation by calling a status accessor function such as FSFileOperationCopyStatus.

File Operation Status Dictionary Keys

Keys used to determine the status of a file operation as reported in a status dictionary.

const CFStringRef kFSOperationTotalBytesKey;
const CFStringRef kFSOperationBytesCompleteKey;
const CFStringRef kFSOperationBytesRemainingKey;
const CFStringRef kFSOperationTotalObjectsKey;
const CFStringRef kFSOperationObjectsCompleteKey;
const CFStringRef kFSOperationObjectsRemainingKey;
const CFStringRef kFSOperationTotalUserVisibleObjectsKey;
const CFStringRef kFSOperationUserVisibleObjectsCompleteKey;
const CFStringRef kFSOperationUserVisibleObjectsRemainingKey;
const CFStringRef kFSOperationThroughputKey;

Constants

kFSOperationTotalBytesKey

The value for this key is a CFNumber that represents the total number of bytes that will be moved or copied by this file operation. This value is not available for a directory operation if the kFSFileOperationSkipPreflight option flag is specified.

Available in OS X v10.4 and later.

Deprecated in OS X v10.8.

Declared in Files.h.

kFSOperationBytesCompleteKey

The value for this key is a CFNumber that represents the total number of bytes that have already been moved or copied by this file operation.

Available in OS X v10.4 and later.

Deprecated in OS X v10.8.

Declared in Files.h.

kFSOperationBytesRemainingKey

The value for this key is a CFNumber that represents the total number of bytes that remain to be moved or copied by this file operation.

Available in OS X v10.4 and later.

Deprecated in OS X v10.8.

Declared in Files.h.

kFSOperationTotalObjectsKey

The value for this key is a CFNumber that represents the total number of objects that will be moved or copied by this file operation.

Available in OS X v10.4 and later.

Deprecated in OS X v10.8.

Declared in Files.h.

kFSOperationObjectsCompleteKey

The value for this key is a CFNumber that represents the total number of objects that have already been moved or copied by this file operation.

Available in OS X v10.4 and later.

Deprecated in OS X v10.8.

Declared in Files.h.

kFSOperationObjectsRemainingKey

The value for this key is a CFNumber that represents the total number of objects that remain to be moved or copied by this file operation.

Available in OS X v10.4 and later.

Deprecated in OS X v10.8.

Declared in Files.h.

kFSOperationTotalUserVisibleObjectsKey

The value for this key is a CFNumber that represents the total number of user-visible objects that will be moved or copied by this file operation. In general, an object is user-visible if it is displayed in a Finder window. For example, a package is counted as a single user-visible object even though it typically contains many other objects.

Available in OS X v10.4 and later.

Deprecated in OS X v10.8.

Declared in Files.h.

kFSOperationUserVisibleObjectsCompleteKey

The value for this key is a CFNumber that represents the total number of user-visible objects that have already been moved or copied by this file operation.

Available in OS X v10.4 and later.

Deprecated in OS X v10.8.

Declared in Files.h.

kFSOperationUserVisibleObjectsRemainingKey

The value for this key is a CFNumber that represents the total number of user-visible objects that remain to be moved or copied by this file operation.

Available in OS X v10.4 and later.

Deprecated in OS X v10.8.

Declared in Files.h.

kFSOperationThroughputKey

The value for this key is a CFNumber that represents the current throughput of this file operation in bytes per second.

Available in OS X v10.4 and later.

Deprecated in OS X v10.8.

Declared in Files.h.

Discussion

The status dictionary for a file operation is passed back to your status callback function. For more information, see “File Operation Callbacks.” You can also get the status dictionary for a file operation by calling a status accessor function such as FSFileOperationCopyStatus.

FNMessage

typedef UInt32 FNMessage;
enum {
   kFNDirectoryModifiedMessage = 1
};

Constants

kFNDirectoryModifiedMessage

Available in OS X v10.0 and later.

Declared in Files.h.

Foreign Privilege Model Constant

Identifies the A/UX privilege model.

enum {
   fsUnixPriv = 1
};

Constants

fsUnixPriv

Represents a volume that supports the A/UX privilege model.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

Used in the vMForeignPrivID field of the GetVolParmsInfoBuffer.

Group ID Constant

enum {
   knoGroup = 0
};

Constants

knoGroup

Available in OS X v10.0 and later.

Declared in Files.h.

Icon Size Constants

Specify the sizes of the desktop database icon types.

enum {
   kLargeIconSize = 256,
   kLarge4BitIconSize = 512,
   kLarge8BitIconSize = 1024,
   kSmallIconSize = 64,
   kSmall4BitIconSize = 128,
   kSmall8BitIconSize = 256
};

Constants

kLargeIconSize

Large black-and-white icon with mask. Corresponding resource type: 'ICN#'.

Available in OS X v10.0 and later.

Declared in Files.h.

kLarge4BitIconSize

Large 4-bit color icon. Corresponding resource type: 'icl4’.

Available in OS X v10.0 and later.

Declared in Files.h.

kLarge8BitIconSize

Large 8-bit color icon. Corresponding resource type: 'icl8'.

Available in OS X v10.0 and later.

Declared in Files.h.

kSmallIconSize

Small black-and-white icon with mask. Corresponding resource type: 'ics#'.

Available in OS X v10.0 and later.

Declared in Files.h.

kSmall4BitIconSize

Small 4-bit color icon. Corresponding resource type: 'ics4'.

Available in OS X v10.0 and later.

Declared in Files.h.

kSmall8BitIconSize

Small 8-bit color icon. Corresponding resource type: 'ics8'.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

These constants indicate the amount of storage you should allocate for the icon data for each of the icon types specified by the “Icon Type Constants.” The desktop database functions which set or retrieve icon data–namely, PBDTAddIconSync , PBDTAddIconAsync , PBDTGetIconSync , PBDTGetIconAsync , PBDTGetIconInfoSync , and PBDTGetIconInfoAsync –expect a pointer to the the storage in the ioDTBuffer field of the DTPBRec parameter block and the appropriate constant in the ioDTReqCount field.

Icon Type Constants

Specify the icon types for the desktop database.

enum {
   kLargeIcon = 1,
   kLarge4BitIcon = 2,
   kLarge8BitIcon = 3,
   kSmallIcon = 4,
   kSmall4BitIcon = 5,
   kSmall8BitIcon = 6,
   kicnsIconFamily = 239
};

Constants

kLargeIcon

Large black-and-white icon with mask. Corresponding resource type: 'ICN#'.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Files.h.

kLarge4BitIcon

Large 4-bit color icon. Corresponding resource type: 'icl4’.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Files.h.

kLarge8BitIcon

Large 8-bit color icon. Corresponding resource type: 'icl8'.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Files.h.

kSmallIcon

Small black-and-white icon with mask. Corresponding resource type: 'ics#'.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Files.h.

kSmall4BitIcon

Small 4-bit color icon. Corresponding resource type: 'ics4'.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Files.h.

kSmall8BitIcon

Small 8-bit color icon. Corresponding resource type: 'ics8'.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Files.h.

kicnsIconFamily

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Files.h.

Discussion

These constants are used in the ioIconType field of the DTPBRec parameter block.

Invalid Volume Reference Constant

Represents an invalid volume reference number.

enum {
   kFSInvalidVolumeRefNum = 0
};

Constants

kFSInvalidVolumeRefNum

Invalid volume reference number.

Available in OS X v10.0 and later.

Declared in Files.h.

Iterator Flags

Indicate whether an iterator iterates over subtrees or just the immediate children of the container.

enum {
   kFSIterateFlat = 0,
   kFSIterateSubtree = 1,
   kFSIterateDelete = 2,
   kFSIterateReserved = 0xFFFFFFFC
};
typedef OptionBits FSIteratorFlags;

Constants

kFSIterateFlat

Iterate over the immediate children of the container only.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSIterateSubtree

Iterate over the entire subtree rooted at the container.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSIterateDelete

Available in OS X v10.0 and later.

Declared in Files.h.

kFSIterateReserved

Available in OS X v10.0 and later.

Declared in Files.h.

kAsyncMountInProgress

enum {
   kAsyncMountInProgress = 1,
   kAsyncMountComplete = 2,
   kAsyncUnmountInProgress = 3,
   kAsyncUnmountComplete = 4,
   kAsyncEjectInProgress = 5,
   kAsyncEjectComplete = 6
};

Constants

kAsyncMountInProgress

Available in OS X v10.2 and later.

Declared in Files.h.

kAsyncMountComplete

Available in OS X v10.2 and later.

Declared in Files.h.

kAsyncUnmountInProgress

Available in OS X v10.2 and later.

Declared in Files.h.

kAsyncUnmountComplete

Available in OS X v10.2 and later.

Declared in Files.h.

kAsyncEjectInProgress

Available in OS X v10.2 and later.

Declared in Files.h.

kAsyncEjectComplete

Available in OS X v10.2 and later.

Declared in Files.h.

Notification Subscription Options

Options that can be specified at subscription time.

enum {
   kFNNoImplicitAllSubscription = (1 << 0),
   kFNNotifyInBackground = (1 << 1)
};

Constants

kFNNoImplicitAllSubscription

Specify this option if you do not want to receive notifications on this subscription when FNNotifyAll is called. By default, any subscription is also implicitly a subscription to wildcard notifications.

Available in OS X v10.1 and later.

Declared in Files.h.

kFNNotifyInBackground

Specify this option if you want to receive notifications on this subscription when your application is in background. By default, notifications will be coalesced and and delivered when your application becomes foreground.

Available in OS X v10.3 and later.

Declared in Files.h.

kHFSCatalogNodeIDsReusedBit

enum {
   kHFSCatalogNodeIDsReusedBit = 12,
   kHFSCatalogNodeIDsReusedMask = 1 << kHFSCatalogNodeIDsReusedBit
};

Constants

kHFSCatalogNodeIDsReusedBit

Available in OS X v10.0 and later.

Declared in hfs_format.h.

kHFSCatalogNodeIDsReusedMask

Available in OS X v10.0 and later.

Declared in hfs_format.h.

Large Volume Constants

enum {
   kWidePosOffsetBit = 8,
   kUseWidePositioning = (1 << kWidePosOffsetBit),
   kMaximumBlocksIn4GB = 0x007FFFFF
};

Constants

kWidePosOffsetBit

Available in OS X v10.0 and later.

Declared in Files.h.

kUseWidePositioning

Available in OS X v10.0 and later.

Declared in Files.h.

kMaximumBlocksIn4GB

Available in OS X v10.0 and later.

Declared in Files.h.

Mapping Code Constants

Specify the type of object to map or return.

enum {
   kOwnerID2Name = 1,
   kGroupID2Name = 2,
   kOwnerName2ID = 3,
   kGroupName2ID = 4,
   kReturnNextUser = 1,
   kReturnNextGroup = 2,
   kReturnNextUG = 3
};

Constants

kOwnerID2Name

Map a user ID to the user name. Used with the PBHMapIDSync or PBHMapIDAsync functions.

Available in OS X v10.0 and later.

Declared in Files.h.

kGroupID2Name

Map a group ID to the group name. Used with the PBHMapIDSync or PBHMapIDAsync functions.

Available in OS X v10.0 and later.

Declared in Files.h.

kOwnerName2ID

Map a user name to the user ID. Used with the PBHMapNameSync or PBHMapNameAsync functions.

Available in OS X v10.0 and later.

Declared in Files.h.

kGroupName2ID

Map a group name to the group ID. Used with the PBHMapNameSync or PBHMapNameAsync functions.

Available in OS X v10.0 and later.

Declared in Files.h.

kReturnNextUser

Return the next user entry.

Available in OS X v10.0 and later.

Declared in Files.h.

kReturnNextGroup

Return the next group entry.

Available in OS X v10.0 and later.

Declared in Files.h.

kReturnNextUG

Return the next user or group entry.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

These constants are used in the ioObjType field of the ObjParam parameter block. The first four constants are passed to the PBHMapIDSync , PBHMapIDAsync , PBHMapNameSync , and PBHMapNameAsync functions to specify the mapping to be performed. The last three constants are passed to the PBGetUGEntrySync or PBGetUGEntryAsync functions to specify the type of object to be returned.

Path Conversion Options

Specify how a pathname is converted to an FSRef structure by the function FSPathMakeRefWithOptions.

enum {
   kFSPathMakeRefDefaultOptions = 0,
   kFSPathMakeRefDoNotFollowLeafSymlink = 0x01
};

Constants

kFSPathMakeRefDefaultOptions

Use the default options.

Available in OS X v10.4 and later.

Declared in Files.h.

kFSPathMakeRefDoNotFollowLeafSymlink

When converting a path that refers to a symbolic link, do not follow the link. The new FSRef should refer to the link itself.

Available in OS X v10.4 and later.

Declared in Files.h.

Position Mode Constants

Together with an offset, specify a position within a fork.

enum {
   fsAtMark = 0,
   fsFromStart = 1,
   fsFromLEOF = 2,
   fsFromMark = 3
};

Constants

fsAtMark

The starting point is the access path’s current position. The offset is ignored.

Available in OS X v10.0 and later.

Declared in Files.h.

fsFromStart

The starting point is offset bytes from the start of the fork. The offset must be non-negative.

Available in OS X v10.0 and later.

Declared in Files.h.

fsFromLEOF

The starting point is offset bytes from the logical end of the fork. The offset must not be positive.

Available in OS X v10.0 and later.

Declared in Files.h.

fsFromMark

The starting point is offset bytes from the access path’s current position. The offset may be positive or negative.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

These constants are used in the ioPosMode and positionMode fields and parameters of the HFS and HFS Plus file access functions. These functions include those for reading from and writing to files or forks, changing the current position within a file or fork, changing the size of a file or fork, and allocating space to a file or fork.

For the FSReadFork and FSWriteFork calls, you may also add either of the pleaseCacheMask or noCacheMask constants to hint whether the data should be cached or not. See “Cache Constants.”

Root Directory Constants

Specify the directory IDs of the root directory of a volume and its parent.

enum {
   fsRtParID = 1,
   fsRtDirID = 2
};

Constants

fsRtParID

Represents the directory ID of the root directory’s parent directory. The root directory has no parent this constant is used when specifying the root directory to functions which require the parent directory ID to identify directories.

Available in OS X v10.0 and later.

Declared in Files.h.

fsRtDirID

Represents the directory ID of the volume’s root directory.

Available in OS X v10.0 and later.

Declared in Files.h.

User ID Constants

Specify basic user IDs for shared directories.

enum {
   knoUser = 0,
   kadministratorUser = 1
};

Constants

knoUser

Available in OS X v10.0 and later.

Declared in Files.h.

kadministratorUser

Available in OS X v10.0 and later.

Declared in Files.h.

User Privileges Constants

Specify the user privileges for a directory on a remote volume.

enum {
   kioACUserNoSeeFolderBit = 0,
   kioACUserNoSeeFolderMask = 0x01,
   kioACUserNoSeeFilesBit = 1,
   kioACUserNoSeeFilesMask = 0x02,
   kioACUserNoMakeChangesBit = 2,
   kioACUserNoMakeChangesMask = 0x04,
   kioACUserNotOwnerBit = 7,
   kioACUserNotOwnerMask = 0x80
};

Constants

kioACUserNoSeeFolderBit

Set if the user does not have “See Folders” privileges. Without “See Folders” privileges, the user cannot see other directories in the specified directory.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACUserNoSeeFolderMask

Tests if the user has “See Folders” privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACUserNoSeeFilesBit

Set if the user does not have “See Files” privileges. Without “See Files” privileges, the user cannot open documents or applications in the specified directory.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACUserNoSeeFilesMask

Tests if the user has “See Files” privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACUserNoMakeChangesBit

Set if the user does not have “Make Changes” privileges. Without “Make Changes” privileges, the user cannot create, modify, rename, or delete any file or directory within the specified directory.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACUserNoMakeChangesMask

Tests if the user has “Make Changes” privileges.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACUserNotOwnerBit

Set if the user is not the owner of the directory.

Available in OS X v10.0 and later.

Declared in Files.h.

kioACUserNotOwnerMask

Tests whether the user is the owner of the directory.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

These constants are used in the ioACUser field of the HFileInfo and DirInfo structures returned by the PBGetCatInfoSync and PBGetCatInfoAsync functions.

Volume Attribute Constants

Bit position constants that specify volume attributes.

enum {
   bLimitFCBs = 31,
   bLocalWList = 30,
   bNoMiniFndr = 29,
   bNoVNEdit = 28,
   bNoLclSync = 27,
   bTrshOffLine = 26,
   bNoSwitchTo = 25,
   bNoDeskItems = 20,
   bNoBootBlks = 19,
   bAccessCntl = 18,
   bNoSysDir = 17,
   bHasExtFSVol = 16,
   bHasOpenDeny = 15,
   bHasCopyFile = 14,
   bHasMoveRename = 13,
   bHasDesktopMgr = 12,
   bHasShortName = 11,
   bHasFolderLock = 10,
   bHasPersonalAccessPrivileges = 9,
   bHasUserGroupList = 8,
   bHasCatSearch = 7,
   bHasFileIDs = 6,
   bHasBTreeMgr = 5,
   bHasBlankAccessPrivileges = 4,
   bSupportsAsyncRequests = 3,
   bSupportsTrashVolumeCache = 2
};
enum {
   bHasDirectIO = 1
};

Constants

bLimitFCBs

The Finder limits the number of file control blocks used during copying to 8 instead of 16.

Available in OS X v10.0 and later.

Declared in Files.h.

bLocalWList

The Finder uses the returned shared volume handle for its local window list.

Available in OS X v10.0 and later.

Declared in Files.h.

bNoMiniFndr

Reserved; always set to 1.

Available in OS X v10.0 and later.

Declared in Files.h.

bNoVNEdit

This volume’s name cannot be edited.

Available in OS X v10.0 and later.

Declared in Files.h.

bNoLclSync

Don’t let the Finder change the modification date.

Available in OS X v10.0 and later.

Declared in Files.h.

bTrshOffLine

Any time this volume goes offline, it is zoomed to the Trash and unmounted.

Available in OS X v10.0 and later.

Declared in Files.h.

bNoSwitchTo

The Finder will not switch launch to any application on this volume.

Available in OS X v10.0 and later.

Declared in Files.h.

bNoDeskItems

Don’t place objects in this volume on the Finder desktop.

Available in OS X v10.0 and later.

Declared in Files.h.

bNoBootBlks

This volume is not a startup volume. The Startup menu item is disabled. Boot blocks are not copied during copy operations.

Available in OS X v10.0 and later.

Declared in Files.h.

bAccessCntl

This volume supports AppleTalk AFP access-control interfaces. The following functions are supported:

PBHGetLogInInfoSync
PBHGetLogInInfoAsync
PBHGetDirAccessSync
PBHGetDirAccessAsync
PBHSetDirAccessSync
PBHSetDirAccessAsync
PBHMapIDSync
PBHMapIDAsync
PBHMapNameSync
PBHMapNameAsync

Special folder icons are used. The Access Privileges menu command is enabled for disk and folder items. The ioFlAttrib field of the parameter block passed to the PBGetCatInfoSync and PBGetCatInfoSync functions is assumed to be valid.

Available in OS X v10.0 and later.

Declared in Files.h.

bNoSysDir

This volume doesn’t support a system directory. Do not switch launch to this volume.

Available in OS X v10.0 and later.

Declared in Files.h.

bHasExtFSVol

This volume is an external file system volume.

Available in OS X v10.0 and later.

Declared in Files.h.

bHasOpenDeny

This volume supports the PBHOpenDenySync , PBHOpenDenyAsync, PBHOpenRFDenySync and PBHOpenRFDenyAsync functions.

Available in OS X v10.0 and later.

Declared in Files.h.

bHasCopyFile

This volume supports the PBHCopyFileSync and PBHCopyFileAsync functions, which is used in copy and duplicate operations if both source and destination volumes have the same server address.

Available in OS X v10.0 and later.

Declared in Files.h.

bHasMoveRename

This volume supports the PBHMoveRenameSync and PBHMoveRenameAsync functions.

Available in OS X v10.0 and later.

Declared in Files.h.

bHasDesktopMgr

This volume supports all of the desktop functions.

Available in OS X v10.0 and later.

Declared in Files.h.

bHasShortName

This volume supports AFP short names.

Available in OS X v10.0 and later.

Declared in Files.h.

bHasFolderLock

Folders on the volume can be locked, and so they cannot be deleted or renamed.

Available in OS X v10.0 and later.

Declared in Files.h.

bHasPersonalAccessPrivileges

This volume has local file sharing enabled.

Available in OS X v10.0 and later.

Declared in Files.h.

bHasUserGroupList

This volume supports the Users and Groups file and thus the AFP privilege functions.

Available in OS X v10.0 and later.

Declared in Files.h.

bHasCatSearch

This volume supports the PBCatSearchSync and PBCatSearchAsync functions.

Available in OS X v10.0 and later.

Declared in Files.h.

bHasFileIDs

This volume supports the file ID functions, including the PBExchangeFilesSync and PBExchangeFilesAsync functions.

Available in OS X v10.0 and later.

Declared in Files.h.

bHasBTreeMgr

Reserved for internal use.

Available in OS X v10.0 and later.

Declared in Files.h.

bHasBlankAccessPrivileges

This volume supports inherited access privileges for folders (blank access privileges).

Available in OS X v10.0 and later.

Declared in Files.h.

bSupportsAsyncRequests

This volume correctly handles asynchronous requests at any time.

Available in OS X v10.0 and later.

Declared in Files.h.

bSupportsTrashVolumeCache

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

These constants correspond to bit positions in the vMAttrib field of the GetVolParmsInfoBuffer structure returned by the PBHGetVolParmsSync and PBHGetVolParmsAsync functions.

Volume Control Block Flags

Used in the vcbFlags field of a volume control block to specify information about a volume.

enum {
   kVCBFlagsIdleFlushBit = 3,
   kVCBFlagsIdleFlushMask = 0x0008,
   kVCBFlagsHFSPlusAPIsBit = 4,
   kVCBFlagsHFSPlusAPIsMask = 0x0010,
   kVCBFlagsHardwareGoneBit = 5,
   kVCBFlagsHardwareGoneMask = 0x0020,
   kVCBFlagsVolumeDirtyBit = 15,
   kVCBFlagsVolumeDirtyMask = 0x8000
};

Constants

kVCBFlagsIdleFlushBit

Indicates that the volume should be flushed at idle time.

Available in OS X v10.0 and later.

Declared in Files.h.

kVCBFlagsIdleFlushMask

Flushes the volume at idle time.

Available in OS X v10.0 and later.

Declared in Files.h.

kVCBFlagsHFSPlusAPIsBit

Indicates that the volume directly implements the HFS Plus APIs (rather than emulating them).

Available in OS X v10.0 and later.

Declared in Files.h.

kVCBFlagsHFSPlusAPIsMask

The volume directly implements the HFS Plus APIs.

Available in OS X v10.0 and later.

Declared in Files.h.

kVCBFlagsHardwareGoneBit

Indicates that the disk driver returned a hardwareGoneErr in response to a read or write call.

Available in OS X v10.0 and later.

Declared in Files.h.

kVCBFlagsHardwareGoneMask

Tests if the disk driver returned a hardwareGoneErr in response to a read or write call.

Available in OS X v10.0 and later.

Declared in Files.h.

kVCBFlagsVolumeDirtyBit

Indicates that the volume information has changed since the last time the volume was flushed.

Available in OS X v10.0 and later.

Declared in Files.h.

kVCBFlagsVolumeDirtyMask

The volume has changed since the last time the volume was flushed.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

See VCB for a description of the volume control block.

Volume Information Attribute Constants

Define volume attributes returned by the functions PBHGetVInfoSync, PBHGetVInfoAsync, PBXGetVolInfoSync, and PBXGetVolInfoAsync.

enum {
   kioVAtrbDefaultVolumeBit = 5,
   kioVAtrbDefaultVolumeMask = 0x0020,
   kioVAtrbFilesOpenBit = 6,
   kioVAtrbFilesOpenMask = 0x0040,
   kioVAtrbHardwareLockedBit = 7,
   kioVAtrbHardwareLockedMask = 0x0080,
   kioVAtrbSoftwareLockedBit = 15,
   kioVAtrbSoftwareLockedMask = 0x8000
};

Constants

kioVAtrbDefaultVolumeBit

Indicates that the volume is the default volume.

Available in OS X v10.0 and later.

Declared in Files.h.

kioVAtrbDefaultVolumeMask

Tests if the volume is the default volume.

Available in OS X v10.0 and later.

Declared in Files.h.

kioVAtrbFilesOpenBit

Indicates that there are open files or iterators.

Available in OS X v10.0 and later.

Declared in Files.h.

kioVAtrbFilesOpenMask

Tests if there are open files or iterators.

Available in OS X v10.0 and later.

Declared in Files.h.

kioVAtrbHardwareLockedBit

Indicates that the volume is locked by a hardware setting. On OS X, the File Manager only sets the software locked bit for CDs and other read-only media; it does not set the hardware locked bit.

Available in OS X v10.0 and later.

Declared in Files.h.

kioVAtrbHardwareLockedMask

Tests if the volume is locked by a hardware setting.

Available in OS X v10.0 and later.

Declared in Files.h.

kioVAtrbSoftwareLockedBit

Indicates that the volume is locked by software.

Available in OS X v10.0 and later.

Declared in Files.h.

kioVAtrbSoftwareLockedMask

Tests if the volume is locked by software.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

These constants are used in the ioVAtrb field of the HVolumeParam parameter block returned by the PBHGetVInfoSync and PBHGetVInfoAsync functions, and in the ioVAtrb field of the XVolumeParam parameter block returned by the PBXGetVolInfoSync and PBXGetVolInfoAsync functions.

Volume Information Bitmap Constants

Indicate what volume information to set or retrieve.

enum {
   kFSVolInfoNone = 0x0000,
   kFSVolInfoCreateDate = 0x0001,
   kFSVolInfoModDate = 0x0002,
   kFSVolInfoBackupDate = 0x0004,
   kFSVolInfoCheckedDate = 0x0008,
   kFSVolInfoFileCount = 0x0010,
   kFSVolInfoDirCount = 0x0020,
   kFSVolInfoSizes = 0x0040,
   kFSVolInfoBlocks = 0x0080,
   kFSVolInfoNextAlloc = 0x0100,
   kFSVolInfoRsrcClump = 0x0200,
   kFSVolInfoDataClump = 0x0400,
   kFSVolInfoNextID = 0x0800,
   kFSVolInfoFinderInfo = 0x1000,
   kFSVolInfoFlags = 0x2000,
   kFSVolInfoFSInfo = 0x4000,
   kFSVolInfoDriveInfo = 0x8000,
   kFSVolInfoGettableInfo = 0xFFFF,
   kFSVolInfoSettableInfo = 0x3004
};

Constants

kFSVolInfoNone

No volume information.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoCreateDate

Retrieve the creation date of the volume.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoModDate

Retrieve the date of the volume’s last modification.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoBackupDate

Retrieve or set the date of the volume’s last backup.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoCheckedDate

Retrieve the date that the volume was last checked for consistency.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoFileCount

Retrieve the number of files on the volume.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoDirCount

Retrieve the number of directories on the volume.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoSizes

Retrieve the total number of bytes on the volume and the number of unused bytes on the volume (in the totalBytes and freeBytes fields).

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoBlocks

Retrieve the block information: the block size, the number of total blocks on the volume, and the number of free blocks on the volume.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoNextAlloc

Retrieve the address at which to start the next allocation.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoRsrcClump

Retrieve the resource fork clump size.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoDataClump

Retrieve the data fork clump size.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoNextID

Retrieve the next available catalog node ID.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoFinderInfo

Retrieve or set the volume’s Finder information.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoFlags

Retrieve or set the volume’s flags. See “Volume Information Flags” for more information on the volume’s flags.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoFSInfo

Retrieve the filesystem ID and signature.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoDriveInfo

Retrieve the drive information: the drive number and driver reference number.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoGettableInfo

Retrieve all of the gettable information.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolInfoSettableInfo

Set all of the settable information. Currently, this is the backup date, Finder information, and flags.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

These constants are used with the FSVolumeInfoBitmap data type to indicate what volume information to set or retrieve with the functions FSSetVolumeInfo and FSGetVolumeInfo , and their corresponding parameter block calls.

Volume Information Flags

Used by the FSVolumeInfo structure to specify characteristics of a volume.

enum {
   kFSVolFlagDefaultVolumeBit = 5,
   kFSVolFlagDefaultVolumeMask = 0x0020,
   kFSVolFlagFilesOpenBit = 6,
   kFSVolFlagFilesOpenMask = 0x0040,
   kFSVolFlagHardwareLockedBit = 7,
   kFSVolFlagHardwareLockedMask = 0x0080,
   kFSVolFlagSoftwareLockedBit = 15,
   kFSVolFlagSoftwareLockedMask = 0x8000
};

Constants

kFSVolFlagDefaultVolumeBit

Set if the volume is the default volume.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolFlagDefaultVolumeMask

Indicates that the volume is the default volume.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolFlagFilesOpenBit

Set if there are open files or iterators.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolFlagFilesOpenMask

Indicates that there are open files or iterators.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolFlagHardwareLockedBit

Set if the volume is locked by a hardware setting. On OS X, the File Manager only sets the software locked bit for CDs and other read-only media; it does not set the hardware locked bit.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolFlagHardwareLockedMask

Indicates that the volume is locked by a hardware setting.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolFlagSoftwareLockedBit

Set if the volume is locked by software.

Available in OS X v10.0 and later.

Declared in Files.h.

kFSVolFlagSoftwareLockedMask

Indicates that the volume is locked by software.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

See the flags field of the FSVolumeInfo structure.

Volume Mount Flags

Define flags used by the volume mounting information structures.

enum {
   volMountNoLoginMsgFlagBit = 0,
   volMountNoLoginMsgFlagMask = 0x0001,
   volMountExtendedFlagsBit = 7,
   volMountExtendedFlagsMask = 0x0080,
   volMountInteractBit = 15,
   volMountInteractMask = 0x8000,
   volMountChangedBit = 14,
   volMountChangedMask = 0x4000,
   volMountFSReservedMask = 0x00FF,
   volMountSysReservedMask = 0xFF00
};

Constants

volMountNoLoginMsgFlagBit

Indicates that any log-in message or greeting dialog will be suppressed.

Available in OS X v10.0 and later.

Declared in Files.h.

volMountNoLoginMsgFlagMask

Tells the file system to suppress any log-in message or greeting dialog.

Available in OS X v10.0 and later.

Declared in Files.h.

volMountExtendedFlagsBit

Indicates that the mounting information is a AFPXVolMountInfo record for AppleShare Client version 3.7 and later.

Available in OS X v10.0 and later.

Declared in Files.h.

volMountExtendedFlagsMask

Tells the file system that the mounting information is an AFPXVolMountInfo record for AppleShare Client version 3.7 and later.

Available in OS X v10.0 and later.

Declared in Files.h.

volMountInteractBit

Indicates that it's safe for the file system to perform user interaction to mount the volume.

Available in OS X v10.0 and later.

Declared in Files.h.

volMountInteractMask

Tells the file system that it’s safe to perform user interaction to mount the volume.

Available in OS X v10.0 and later.

Declared in Files.h.

volMountChangedBit

Indicates that the volume was mounted, but the volume mounting information record needs to be updated.

Available in OS X v10.0 and later.

Declared in Files.h.

volMountChangedMask

Tests if the volume mounting information record needs to be updated.

Available in OS X v10.0 and later.

Declared in Files.h.

volMountFSReservedMask

Reserved.

Available in OS X v10.0 and later.

Declared in Files.h.

volMountSysReservedMask

Reserved.

Available in OS X v10.0 and later.

Declared in Files.h.

Discussion

Bits 0-7 are defined by each file system for its own use; bits 8-15 are reserved for Apple system use. These constants are used in the flags fields of the AFPVolMountInfo, AFPXVolMountInfo , and VolumeMountInfoHeader structures.

Result Codes

The most common result codes returned by File Manager functions are listed below.

Result Code	Value	Description
`dirFulErr`	-33	File directory full. Available in OS X v10.0 and later.
`dskFulErr`	-34	Disk or volume full. Available in OS X v10.0 and later.
`nsvErr`	-35	Volume not found. Available in OS X v10.0 and later.
`ioErr`	-36	I/O error. Available in OS X v10.0 and later.
`bdNamErr`	-37	Bad filename or volume name. Available in OS X v10.0 and later.
`fnOpnErr`	-38	File not open. Available in OS X v10.0 and later.
`eofErr`	-39	Logical end-of-file reached. Available in OS X v10.0 and later.
`posErr`	-40	Attempt to position mark before the start of the file. Available in OS X v10.0 and later.
`mFulErr`	-41	Memory full (open) or file won't fit (load) Available in OS X v10.0 and later.
`tmfoErr`	-42	Too many files open. Available in OS X v10.0 and later.
`fnfErr`	-43	File or directory not found; incomplete pathname. Available in OS X v10.0 and later.
`wPrErr`	-44	Volume is locked through hardware. Available in OS X v10.0 and later.
`fLckdErr`	-45	File is locked. Available in OS X v10.0 and later.
`vLckdErr`	-46	Volume is locked through software. Available in OS X v10.0 and later.
`fBsyErr`	-47	One or more files are open File is busy Directory is not empty. Available in OS X v10.0 and later.
`dupFNErr`	-48	Duplicate filename and version Destination file already exists File found instead of folder Available in OS X v10.0 and later.
`opWrErr`	-49	File already open for writing. Available in OS X v10.0 and later.
`paramErr`	-50	Invalid value passed in a parameter. Your application passed an invalid parameter for dialog options. Available in OS X v10.0 and later.
`rfNumErr`	-51	Invalid reference number. Available in OS X v10.0 and later.
`gfpErr`	-52	Error during `GetFPos`, `PBGetFPosSync` or `PBGetFPosAsync`. Available in OS X v10.0 and later.
`volOffLinErr`	-53	Volume is offline. Available in OS X v10.0 and later.
`permErr`	-54	Attempt to open locked file for writing Permissions error Available in OS X v10.0 and later.
`volOnLinErr`	-55	Volume already online. Available in OS X v10.0 and later.
`nsDrvErr`	-56	No such drive. Available in OS X v10.0 and later.
`noMacDskErr`	-57	Not a Macintosh disk. Available in OS X v10.0 and later.
`extFSErr`	-58	Volume belongs to an external file system. Available in OS X v10.0 and later.
`fsRnErr`	-59	Problem during rename. Available in OS X v10.0 and later.
`badMDBErr`	-60	Bad master directory block. Available in OS X v10.0 and later.
`wrPermErr`	-61	Read/ write permission doesn’t allow writing. Available in OS X v10.0 and later.
`lastDskErr`	-64	Available in OS X v10.0 and later.
`noDriveErr`	-64	Drive not installed. Available in OS X v10.0 and later.
`firstDskErr`	-84	Available in OS X v10.0 and later.
`dirNFErr`	-120	Directory not found or incomplete pathname. Available in OS X v10.0 and later.
`tmwdoErr`	-121	Too many working directories open. Available in OS X v10.0 and later.
`badMovErr`	-122	Attempt to move. Available in OS X v10.0 and later.
`wrgVolTypErr`	-123	Volume does not support Desktop Manager Not an HFS volume Available in OS X v10.0 and later.
`volGoneErr`	-124	Server volume has been disconnected. Available in OS X v10.0 and later.
`fsDSIntErr`	-127	non-hardware internal file system error. Available in OS X v10.0 and later.
`fsmFFSNotFoundErr`	-431	Foreign file system does not exist. Available in OS X v10.0 and later.
`fsmBusyFFSErr`	-432	File system is busy, cannot be removed. Available in OS X v10.0 and later.
`fsmBadFFSNameErr`	-433	Name length not 1 <= length <= 31 Available in OS X v10.0 and later.
`fsmBadFSDLenErr`	-434	FSD size incompatible with current FSM vers Available in OS X v10.0 and later.
`fsmDuplicateFSIDErr`	-435	FSID already exists. Available in OS X v10.0 and later.
`fsmBadFSDVersionErr`	-436	FSM version incompatible with FSD Available in OS X v10.0 and later.
`fsmNoAlternateStackErr`	-437	no alternate stack for HFS CI Available in OS X v10.0 and later.
`fsmUnknownFSMMessageErr`	-438	unknown message passed to FSM Available in OS X v10.0 and later.
`driverHardwareGoneErr`	-503	disk driver's hardware was disconnected Available in OS X v10.0 and later.
`fidNotFound`	-1300	File ID not found Available in OS X v10.0 and later.
`fidExists`	-1301	File ID already exists Available in OS X v10.0 and later.
`notAFileErr`	-1302	Specified file is a directory Available in OS X v10.0 and later.
`diffVolErr`	-1303	Files on different volumes Available in OS X v10.0 and later.
`catChangedErr`	-1304	Catalog has changed and catalog position record may be invalid Available in OS X v10.0 and later.
`sameFileErr`	-1306	Can’t exchange a file with itself Available in OS X v10.0 and later.
`badFidErr`	-1307	File ID is dangling or doesn’t match with the file number Available in OS X v10.0 and later.
`notARemountErr`	-1308	_Mount allows only remounts and doesn’t get one Available in OS X v10.0 and later.
`fileBoundsErr`	-1309	File’s EOF, offset, mark or size is too big Available in OS X v10.0 and later.
`fsDataTooBigErr`	-1310	File or volume is too big for system Available in OS X v10.0 and later.
`volVMBusyErr`	-1311	Can’t eject because volume is in use by VM Available in OS X v10.0 and later.
`badFCBErr`	-1327	FCBRecPtr is not valid Available in OS X v10.0 and later.
`errFSUnknownCall`	-1400	Selector is not recognized by this file system Available in OS X v10.0 and later.
`errFSBadFSRef`	-1401	An `FSRef` parameter was invalid. There are several possible causes: The parameter was not optional, but the pointer was NULL. The volume reference number contained within the `FSRef` does not match a currently mounted volume. This can happen if the volume was unmounted after the `FSRef` was created. Some other private field inside the `FSRef` contains a value that could never be valid. If the field value could be valid, but doesn’t happen to match the existing volume or in-memory structures, a “not found” error would be returned instead. Available in OS X v10.0 and later.
`errFSBadForkName`	-1402	A supplied fork name was invalid (i.e., was syntactically illegal for the given volume). For example, the fork name might contain characters that cannot be stored on the given volume (such as a colon on HFS volumes). Some volume formats do not store fork names in Unicode. These volume formats will attempt to convert the Unicode name to the kind of encoding used by the volume format. If the name could not be converted, `errFSBadForkName` is returned. Some volume formats only support a limited set of forks, such as the data and resource forks on HFS volumes. For those volumes, if any other fork name is passed, this error is returned. Available in OS X v10.0 and later.
`errFSBadBuffer`	-1403	A non-optional buffer pointer was `NULL` , or its size was invalid for the type of data it was expected to contain. In a protected memory system, this could also mean the buffer space is not part of the address space for the calling process. Available in OS X v10.0 and later.
`errFSBadForkRef`	-1404	A file reference number does not correspond to a fork opened with the `FSOpenFork`, `PBOpenForkSync` , or `PBOpenForkAsync` functions. This could be because that fork has already been closed. Or, you may have passed a reference number created with older APIs (e.g., by the `PBHOpenDF` functions). A value of zero is never a valid file reference number. Available in OS X v10.0 and later.
`errFSBadInfoBitmap`	-1405	A `FSCatalogInfoBitmap` or `FSVolumeInfoBitmap` has one or more reserved or undefined bits set. This error code can also be returned if a defined bit is set, but the corresponding `FSCatalogInfo` or `FSVolumeInfo` field cannot be operated on with that call (for example, trying to use `FSSetCatalogInfo` to set the valence of a directory). Available in OS X v10.0 and later.
`errFSMissingCatInfo`	-1406	A `FSCatalogInfo` pointer is `NULL` , but is not optional. Or, the `FSCatalogInfo` is optional and `NULL`, but the corresponding `FSCatalogInfoBitmap` is not zero (that is,the bitmap says that one or more of the `FSCatalogInfo` fields is being passed, but the supplied pointer was `NULL`). Available in OS X v10.0 and later.
`errFSNotAFolder`	-1407	A parameter was expected to identify a folder, but it identified some other kind of object (e.g., a file) instead. This implies that the specified object exists, but is of the wrong type. For example, one of the parameters to `FSCreateFileUnicode` is an `FSRef` of the directory where the file will be created; if the `FSRef` actually refers to a file, this error is returned. Available in OS X v10.0 and later.
`errFSForkNotFound`	-1409	An attempt to specify a fork of a given file or directory, but that particular fork does not exist. Available in OS X v10.0 and later.
`errFSNameTooLong`	-1410	A file or fork name was too long. This means that the given name could never exist; this is different from a “file not found” or `errFSForkNotFound` error. Available in OS X v10.0 and later.
`errFSMissingName`	-1411	A required file or fork name parameter was a `NULL` pointer, or the length of a filename was zero. Available in OS X v10.0 and later.
`errFSBadPosMode`	-1412	Reserved or invalid bits in a `positionMode` field were set. For example, the `FSReadFork` call does not support newline mode, so setting the newline bit or a newline character in the `positionMode` parameter would cause this error. Available in OS X v10.0 and later.
`errFSBadAllocFlags`	-1413	Reserved or invalid bits were set in an `FSAllocationFlags` parameter. Available in OS X v10.0 and later.
`errFSNoMoreItems`	-1417	There are no more items to return when enumerating a directory or searching a volume. Note that `FSCatalogSearch` returns this error, whereas the `PBCatSearch` functions would return `eofErr`. Available in OS X v10.0 and later.
`errFSBadItemCount`	-1418	The maximumObjects parameter to `FSGetCatalogInfoBulk` or `FSCatalogSearch` was zero. Available in OS X v10.0 and later.
`errFSBadSearchParams`	-1419	The search criteria to `FSCatalogSearch` are invalid or inconsistent. Available in OS X v10.0 and later.
`errFSRefsDifferent`	-1420	The two `FSRef` structures passed to `FSCompareFSRefs` are for different files or directories. Note that a volume format may be able to compare the `FSRef` structures without searching for the files or directories, so this error may be returned even if one or both of the `FSRef` structures refers to non-existent objects. Available in OS X v10.0 and later.
`errFSForkExists`	-1421	An attempt to create a fork, but that fork already exists. Available in OS X v10.0 and later.
`errFSBadIteratorFlags`	-1422	The flags passed to `FSOpenIterator` are invalid. Available in OS X v10.0 and later.
`errFSIteratorNotFound`	-1423	The value of an `FSIterator` parameter does not correspond to any currently open iterator. Available in OS X v10.0 and later.
`errFSIteratorNotSupported`	-1424	The iterator flags or container of an FSIterator are not supported by that call. For example, in the initial release, the FSCatalogSearch call only supports an iterator whose container is in the volume’s root directory and whose flags are kFSIterateSubtree (i.e., an iterator for the entire volume’s contents). Similarly, in the initial release, FSGetCatalogInfoBulk only supports an iterator whose flags are kFSIterateFlat. Available in OS X v10.0 and later.
`errFSQuotaExceeded`	-1425	The user’s quota of disk blocks has been exhausted. Available in OS X v10.2 and later.
`afpAccessDenied`	-5000	User does not have the correct access to the file Directory cannot be shared Available in OS X v10.0 and later.
`afpAuthContinue`	-5001	Further information required to complete AFPLogin call. Available in OS X v10.0 and later.
`afpBadUAM`	-5002	User authentication method is unknown. Available in OS X v10.0 and later.
`afpBadVersNum`	-5003	Workstation is using an AFP version that the server doesn’t recognize. Available in OS X v10.0 and later.
`afpBitmapErr`	-5004	Bitmap contained bits undefined for call. Available in OS X v10.0 and later.
`afpCantMove`	-5005	Move destination is offspring of source or root was specified. Available in OS X v10.0 and later.
`afpDenyConflict`	-5006	Requested user permission not possible. Available in OS X v10.0 and later.
`afpDirNotEmpty`	-5007	Cannot delete non-empty directory. Available in OS X v10.0 and later.
`afpDiskFull`	-5008	Insufficient free space on volume for operation. Available in OS X v10.0 and later.
`afpEofError`	-5009	Read beyond logical end-of-file. Available in OS X v10.0 and later.
`afpFileBusy`	-5010	Cannot delete an open file. Available in OS X v10.0 and later.
`afpFlatVol`	-5011	Cannot create directory on specified volume. Available in OS X v10.0 and later.
`afpItemNotFound`	-5012	Unknown user name/ user ID or missing comment / APPL entry. Available in OS X v10.0 and later.
`afpLockErr`	-5013	Some or all of requested range is locked by another user. Available in OS X v10.0 and later.
`afpMiscErr`	-5014	Unexpected error encountered during execution. Available in OS X v10.0 and later.
`afpNoMoreLocks`	-5015	No more ranges can be locked. Available in OS X v10.0 and later.
`afpNoServer`	-5016	Server is not responding. Available in OS X v10.0 and later.
`afpObjectExists`	-5017	Specified destination file or directory already exists. Available in OS X v10.0 and later.
`afpObjectNotFound`	-5018	Specified file or directory does not exist. Available in OS X v10.0 and later.
`afpParmErr`	-5019	A specified parameter was out of allowable range. Available in OS X v10.0 and later.
`afpRangeNotLocked`	-5020	Specified range was not locked. Available in OS X v10.0 and later.
`afpRangeOverlap`	-5021	Part of range is already locked. Available in OS X v10.0 and later.
`afpSessClosed`	-5022	Session closed. Available in OS X v10.0 and later.
`afpUserNotAuth`	-5023	User authentication failed (usually, password is not correct). Available in OS X v10.0 and later.
`afpCallNotSupported`	-5024	Unsupported AFP call was made. Available in OS X v10.0 and later.
`afpObjectTypeErr`	-5025	A directory exists with that name Directory not found Folder locking not supported by volume Object was a file, not a directory Available in OS X v10.0 and later.
`afpTooManyFilesOpen`	-5026	Maximum open file count reached. Available in OS X v10.0 and later.
`afpServerGoingDown`	-5027	Server is shutting down. Available in OS X v10.0 and later.
`afpCantRename`	-5028	AFPRename cannot rename volume. Available in OS X v10.0 and later.
`afpDirNotFound`	-5029	Unknown directory specified. Available in OS X v10.0 and later.
`afpIconTypeError`	-5030	Icon size specified is different from existing icon size. Available in OS X v10.0 and later.
`afpVolLocked`	-5031	Volume is read-only. Available in OS X v10.0 and later.
`afpObjectLocked`	-5032	Object is M/R/D/W inhibited. Available in OS X v10.0 and later.
`afpContainsSharedErr`	-5033	The directory contains a share point. Available in OS X v10.0 and later.
`afpIDNotFound`	-5034	File ID not found. Available in OS X v10.0 and later.
`afpIDExists`	-5035	File ID already exists. Available in OS X v10.0 and later.
`afpDiffVolErr`	-5036	Available in OS X v10.0 and later.
`afpCatalogChanged`	-5037	Catalog has changed and search cannot be resumed. Available in OS X v10.0 and later.
`afpSameObjectErr`	-5038	Source and destination files are the same. Available in OS X v10.0 and later.
`afpBadIDErr`	-5039	File ID not found. Available in OS X v10.0 and later.
`afpPwdSameErr`	-5040	Someone tried to change their password to the same password on a mandatory password change. Available in OS X v10.0 and later.
`afpPwdTooShortErr`	-5041	The password being set is too short: there is a minimum length that must be met or exceeded. Available in OS X v10.0 and later.
`afpPwdExpiredErr`	-5042	Password has expired on server. Available in OS X v10.0 and later.
`afpInsideSharedErr`	-5043	The directory is inside a shared directory. Available in OS X v10.0 and later.
`afpInsideTrashErr`	-5044	The folder being shared is inside the trash folder OR the shared folder is being moved into the trash folder. Available in OS X v10.0 and later.
`afpPwdNeedsChangeErr`	-5045	The password needs to be changed. Available in OS X v10.0 and later.
`afpPwdPolicyErr`	-5046	Password does not conform to server’s password policy. Available in OS X v10.0 and later.
`afpAlreadyLoggedInErr`	-5047	User has been authenticated but is already logged in from another machine (and that's not allowed on this server). Available in OS X v10.0 and later.
`afpCallNotAllowed`	-5048	Available in OS X v10.0 and later.
`afpBadDirIDType`	-5060	Not a fixed directory ID volume. Available in OS X v10.0 and later.
`afpCantMountMoreSrvre`	-5061	Maximum number of volumes has been mounted. Available in OS X v10.0 and later.
`afpAlreadyMounted`	-5062	Volume already mounted. Available in OS X v10.0 and later.
`afpSameNodeErr`	-5063	Attempt to log on to a server running on the same machine. Available in OS X v10.0 and later.

Did this document help you?

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