Next Page >

Hide TOC

File Manager Reference

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

Overview

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

The File Manager API provides a large number of functions for performing various operations on files, directories, and volumes. The requirements of your application will dictate which of these functions you need to use. Many applications simply need to open files, read and write the data in those files, and then close the files. Other applications might provide more capabilities, such as the ability to copy or move a file to another directory. A few programs, such as the Mac OS X Finder, perform more extensive file operations and hence need to use some of the advanced functions provided by the File Manager.

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 Mac 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

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 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 and Renaming Files or Directories

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

Obtaining File Control Block 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.

Functions

DisposeFNSubscriptionUPP

Deletes a universal procedure pointer (UPP) to your directory change callback function.

void DisposeFNSubscriptionUPP (
   FNSubscriptionUPP userUPP
);

Parameters

userUPP: The UPP to delete.

Discussion

You should use this function to delete the UPP after the File Manager is finished calling your directory change callback function.

Availability

Available in Mac OS X v10.1 and later.

Declared In

Files.h

DisposeFSVolumeEjectUPP

Deletes a universal procedure pointer (UPP) to your volume ejection callback function.

void DisposeFSVolumeEjectUPP (
   FSVolumeEjectUPP userUPP
);

Parameters

userUPP: The UPP to delete.

Discussion

You should use this function to delete the UPP after the File Manager is finished calling your volume ejection callback function.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

DisposeFSVolumeMountUPP

Deletes a universal procedure pointer (UPP) to your volume mount callback function.

void DisposeFSVolumeMountUPP (
   FSVolumeMountUPP userUPP
);

Parameters

userUPP: The UPP to delete.

Discussion

You should use this function to delete the UPP after the File Manager is finished calling your volume mount callback function.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

DisposeFSVolumeUnmountUPP

Deletes a universal procedure pointer (UPP) to your volume unmount callback function.

void DisposeFSVolumeUnmountUPP (
   FSVolumeUnmountUPP userUPP
);

Parameters

userUPP: The UPP to delete.

Discussion

You should use this function to delete the UPP after the File Manager is finished calling your volume unmount callback function.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

DisposeIOCompletionUPP

Deletes a universal procedure pointer (UPP) to your I/O completion callback function.

void DisposeIOCompletionUPP (
   IOCompletionUPP userUPP
);

Parameters

userUPP: The UPP to delete.

Discussion

You should use this function to delete the UPP after the File Manager is finished calling your I/O completion callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FNGetDirectoryForSubscription

Fetches the directory for which this subscription was originally entered.

OSStatus FNGetDirectoryForSubscription (
   FNSubscriptionRef subscription,
   FSRef *ref
);

Parameters

subscription: The subscription previously returned from the functions FNSubscribe or FNSubscribeByPath.
ref: On return, a file system reference to the directory for which this subscription was created.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

There is no path variant because paths are fragile, and the path may have changed. If the caller does not care about this subtlety, she can call FSRefMakePath to get a path from the returned reference.

Availability

Available in Mac OS X v10.1 and later.

Declared In

Files.h

FNNotify

Broadcasts notification of changes to the specified directory.

OSStatus FNNotify (
   const FSRef *ref,
   FNMessage message,
   OptionBits flags
);

Parameters

ref: A file system reference describing the directory for which to broadcast the notification.
message: An indication of what happened to the target directory.
flags: Options regarding the delivery of the notification. Specify kNilOptions for the default behavior.

Return Value

A result code. See “File Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FNNotifyAll

Broadcasts notification of changes to the filesystem.

OSStatus FNNotifyAll (
   FNMessage message,
   OptionBits flags
);

Parameters

message: An indication of what happened.
flags: Options regarding the delivery of the notification. Specify kNilOptions for the default behavior.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

This function should only be used by installers or programs which make lots of changes and only send one broadcast.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FNNotifyByPath

Broadcasts notification of changes to the specified directory.

OSStatus FNNotifyByPath (
   const UInt8 *path,
   FNMessage message,
   OptionBits flags
);

Parameters

path: The path to the directory for which to broadcast the notification.
message: An indication of what happened to the target directory.
flags: Options regarding the delivery of the notification. Specify kNilOptions for the default behavior.

Return Value

A result code. See “File Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FNSubscribe

Subscribes to change notifications for the specified directory.

OSStatus FNSubscribe (
   const FSRef *directoryRef,
   FNSubscriptionUPP callback,
   void *refcon,
   OptionBits flags,
   FNSubscriptionRef *subscription
);

Parameters

directoryRef: A file system reference describing the directory for which the caller wants notifications.
callback: A pointer to the function to call when a notification arrives.
refcon: A pointer to user state carried with the subscription.
flags: Specify kNilOptions, or one of the options described in “Notification Subscription Options.”
subscription: A subscription token for subsequent query or unsubscription.

Return Value

A result code. See “File Manager Result Codes.”

Availability

Available in Mac OS X v10.1 and later.

Declared In

Files.h

FNSubscribeByPath

Subscribes to change notifications for the specified directory.

OSStatus FNSubscribeByPath (
   const UInt8 *directoryPath,
   FNSubscriptionUPP callback,
   void *refcon,
   OptionBits flags,
   FNSubscriptionRef *subscription
);

Parameters

directoryPath: A path to the directory for which the caller wants notifications.
callback: The function to call when a notification arrives.
refcon: A pointer to the user state carried with the subscription.
flags: Specify kNilOptions, or one of the options described in “Notification Subscription Options.”
subscription: A subscription token for subsequent query or unsubscription.

Return Value

A result code. See “File Manager Result Codes.”

Availability

Available in Mac OS X v10.1 and later.

Declared In

Files.h

FNUnsubscribe

Releases a subscription which is no longer needed.

OSStatus FNUnsubscribe (
   FNSubscriptionRef subscription
);

Parameters

subscription: A subscription previously returned from the FNSubscribe orFNSubscribeByPath functions.

Return Value

A result code. See “File Manager Result Codes.”

Availability

Available in Mac OS X v10.1 and later.

Declared In

Files.h

FSAllocateFork

Allocates space on a volume to an open fork.

OSErr FSAllocateFork (
   FSIORefNum forkRefNum,
   FSAllocationFlags flags,
   UInt16 positionMode,
   SInt64 positionOffset,
   UInt64 requestCount,
   UInt64 *actualCount
);

Parameters

forkRefNum

The reference number of the open fork. You can obtain a fork reference number with the FSOpenFork function, or with one of the corresponding parameter block calls, PBOpenForkSync and PBOpenForkAsync.

flags

A constant indicating how the new space should be allocated. See “Allocation Flags” for a description of the constants which you can use in this parameter.

positionMode

A constant specifying the base location for the start of the allocation. See “Position Mode Constants” for more information on the constants which you can use to specify the base location.

positionOffset

The offset from the base location of the start of the allocation.

requestCount

The number of bytes to allocate.

actualCount

On return, a pointer to the number of bytes actually allocated to the file. The value returned in here may be smaller than the number specified in the requestCount parameter if some of the space was already allocated. The value pointed to by the actualCount parameter does not reflect any additional bytes that may have been allocated because space is allocated in terms of fixed units such as allocation blocks, or the use of a clump size to reduce fragmentation.

The actualCount output is optional if you don’t want the number of allocated bytes returned, set actualCount to NULL.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

The FSAllocateFork function attempts to allocate requestCount bytes of physical storage starting at the offset specified by the positionMode and positionOffset parameters. For volume formats that support preallocated space, you can later write to this range of bytes (including extending the size of the fork) without requiring an implicit allocation.

Any extra space allocated but not used will be deallocated when the fork is closed, using FSCloseFork , PBCloseForkSync , or PBCloseForkAsync ; or when the fork is flushed, using FSFlushFork , PBFlushForkSync , or PBFlushForkAsync.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSCancelVolumeOperation

Cancels an outstanding asynchronous volume mounting operation.

OSStatus FSCancelVolumeOperation (
   FSVolumeOperation volumeOp
);

Parameters

volumeOp: The asynchronous volume operation to cancel.

Return Value

A result code. See “File Manager Result Codes.”

Special Considerations

This function currently is only supported for server mounts.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

FSCatalogSearch

Searches for objects traversed by a catalog iterator that match a given set of criteria.

OSErr FSCatalogSearch (
   FSIterator iterator,
   const FSSearchParams *searchCriteria,
   ItemCount maximumObjects,
   ItemCount *actualObjects,
   Boolean *containerChanged,
   FSCatalogInfoBitmap whichInfo,
   FSCatalogInfo *catalogInfos,
   FSRef *refs,
   FSSpecPtr specs,
   HFSUniStr255 *names
);

Parameters

iterator

The iterator to use. Objects traversed by this iterator are matched against the criteria specified by the searchCriteria parameter. You can obtain a catalog iterator with the function FSOpenIterator, or with one of the related parameter block calls, PBOpenIteratorSync and PBOpenIteratorAsync. Currently, this iterator must be created with the kFSIterateSubtree option and the container must be the root directory of a volume. See FSIterator for more information on the FSIterator data type.

searchCriteria

A pointer to a structure containing the search criteria.

You can match against the object’s name in Unicode and by the fields in an FSCatalogInfo structure. You may use the same search bits as passed in the ioSearchBits field to the PBCatSearchSync and PBCatSearchAsync functions; they control the corresponding FSCatalogInfo fields. See “Catalog Search Masks” for a description of the search bits.

There are a few new search criteria supported by FSCatalogSearch but not by PBCatSearchSync and PBCatSearchAsync. These new search criteria are indicated by the constants described in “Catalog Search Constants.”

If the searchTime field of this structure is non-zero, it is interpreted as a Time Manager duration; the search may terminate after this duration even if maximumObjects objects have not been returned and the entire catalog has not been scanned. If searchTime is zero, there is no time limit for the search.

If you are searching by any criteria other than name, you must set the searchInfo1 and searchInfo2 fields of the structure in this parameter to point to FSCatalogInfo structures containing the values to match against.

See FSSearchParams for a description of the FSSearchParams data type.

maximumObjects

The maximum number of items to return for this call.

actualObjects

On return, a pointer to the actual number of items found for this call.

containerChanged

On return, a pointer to a Boolean value indicating whether the container’s contents have changed. If true, the container’s contents changed since the previous FSCatalogSearch call. Objects may still be returned even though the container changed. Note that if the container has changed, then the total set of items returned may be incorrect; some items may be returned multiple times, and some items may not be returned at all.

This parameter is optional if you don’t want this information, pass a NULL pointer.

whichInfo

A bitmap specifying the catalog information fields to return for each item. If you don’t wish any catalog information returned, pass the constant kFSCatInfoNone in this parameter. See “Catalog Information Bitmap Constants” for a description of the bits in this parameter.

catalogInfos

A pointer to an array of catalog information structures; one for each found item. On input, the catalogInfos parameter should point to an array of maximumObjects catalog information structures.

This parameter is optional; if you do not wish any catalog information returned, pass NULL here.

See FSCatalogInfo for a description of the FSCatalogInfo data type.

refs

A pointer to an array of FSRef structures; one for each returned item. If you want an FSRef for each item found, set this parameter to point to an array of maximumObjectsFSRef structures. Otherwise, set it to NULL. See FSRef for a description of the FSRef data type.

specs

names

A pointer to an array of filenames; one for each returned item. If you want the Unicode filename for each item found, set this parameter to point to an array of maximumObjectsHFSUniStr255 structures. Otherwise, set it to NULL. See HFSUniStr255 for a description of the HFSUniStr255 data type.

Return Value

A result code. See “File Manager Result Codes.” When the entire volume has been searched, errFSNoMoreItems is returned.

Discussion

A single search may span more than one call to FSCatalogSearch. The call may complete with no error before scanning the entire volume. This typically happens because the time limit ( searchTime) has been reached or maximumObjects items have been returned. If the search is not completed, you can continue the search by making another call to FSCatalogSearch and passing the updated iterator returned by the previous call in the iterator parameter.

Before calling this function, you should determine that it is present, by calling the Gestalt function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSCloseFork

Closes an open fork.

OSErr FSCloseFork (
   FSIORefNum forkRefNum
);

Parameters

forkRefNum: The reference number of the fork to close. After the call to this function, the reference number in this parameter is invalid.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

The FSCloseFork function causes all data written to the fork to be written to disk, in the same manner as the FSFlushFork function, before it closes the fork.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSCloseIterator

Closes a catalog iterator.

OSErr FSCloseIterator (
   FSIterator iterator
);

Parameters

iterator: The catalog iterator to be closed. FSCloseIterator releases memory and other system resources used by the iterator, making the iterator invalid. See FSIterator for a description of the FSIterator data type.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

This function releases memory and other system resources used by the iterator. The iterator becomes invalid.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

QTCarbonShell

Declared In

Files.h

FSCompareFSRefs

Determines whether two FSRef structures refer to the same file or directory.

OSErr FSCompareFSRefs (
   const FSRef *ref1,
   const FSRef *ref2
);

Parameters

ref1: A pointer to the first FSRef to compare. For a description of the FSRef data type, see FSRef.
ref2: A pointer to the second FSRef to compare.

Return Value

A result code. See “File Manager Result Codes.” If the two FSRef structures refer to the same file or directory, then noErr is returned. If they refer to objects on different volumes, then diffVolErr is returned. If they refer to different files or directories on the same volume, then errFSRefsDifferent is returned. This function may return other errors, including nsvErr, fnfErr, dirNFErr, and volOffLinErr.

Discussion

You must use FSCompareFSRefs, or one of the corresponding parameter block functions, PBCompareFSRefsSync and PBCompareFSRefsAsync , to compare FSRef structures. It is not possible to compare the FSRef structures directly since some bytes may be uninitialized, case-insensitive text, or contain hint information.

Some volume formats may be able to tell that two FSRef structures would refer to two different files or directories, without having to actually find those objects. In this case, the volume format may return errFSRefsDifferent even if one or both objects no longer exist. Similarly, if the FSRef structures are for objects on different volumes, the File Manager will return diffVolErr even if one or both volumes are no longer mounted.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSCopyDiskIDForVolume

Returns a copy of the disk ID for a volume.

OSStatus FSCopyDiskIDForVolume (
   FSVolumeRefNum vRefNum,
   CFStringRef *diskID
);

Parameters

vRefNum: The volume reference number of the target volume.
diskID: A pointer to a Core Foundation string. On return, the string contains the disk ID associated with the target volume. The caller is responsible for releasing the string.

Return Value

A result code. See “File Manager Result Codes.”

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

FSCopyObjectAsync

Starts an asynchronous file operation to copy a source object to a destination directory.

OSStatus FSCopyObjectAsync (
   FSFileOperationRef fileOp,
   const FSRef *source,
   const FSRef *destDir,
   CFStringRef destName,
   OptionBits flags,
   FSFileOperationStatusProcPtr callback,
   CFTimeInterval statusChangeInterval,
   FSFileOperationClientContext *clientContext
);

Parameters

fileOp: The file operation object you created for this copy operation.
source: A pointer to the source object to copy. The object can be a file or a directory.
destDir: A pointer to the destination directory.
destName: The name for the new object in the destination directory. Pass NULL to use the name of the source object.
flags: One or more file operation option flags. See “File Operation Options.”
callback: A callback function to receive status updates as the file operation proceeds. For more information, see “File Operation Callbacks.” This parameter is optional; pass NULL if you don’t need to supply a status callback.
statusChangeInterval: The minimum time in seconds between callbacks within a single stage of an operation.
clientContext: User-defined data to associate with this operation. For more information, see FSFileOperationClientContext. This parameter is optional; pass NULL if you don’t need to supply a client context.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

If you specify a status callback function, status callbacks will occur in one of the run loop and mode combinations with which you scheduled the file operation.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSCopyObjectSync

Copies a source object to a destination directory.

OSStatus FSCopyObjectSync (
   const FSRef *source,
   const FSRef *destDir,
   CFStringRef destName,
   FSRef *target,
   OptionBits options
);

Parameters

source: A pointer to the source object to copy. The object can be a file or a directory.
destDir: A pointer to the destination directory.
destName: The name for the new object in the destination directory. Pass NULL to use the name of the source object.
target: A pointer to an FSRef variable that, on output, refers to the new object in the destination directory. This parameter is optional; pass NULL if you don’t need to refer to the new object.
options: One or more file operation option flags. See “File Operation Options.”

Return Value

A result code. See “File Manager Result Codes.”

Discussion

This function could take a significant amount of time to execute. To avoid blocking your user interface, you should either call this function in a thread other than the main thread or use FSCopyObjectAsync instead.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSCopyURLForVolume

Returns a copy of the URL for a volume.

OSStatus FSCopyURLForVolume (
   FSVolumeRefNum vRefNum,
   CFURLRef *url
);

Parameters

vRefNum: The volume reference number of the target volume.
url: A pointer to a CFURLRef variable allocated by the caller. On return, a Core Foundation URL that specifies the location of the target volume. The caller is responsible for releasing the URL.

Return Value

A result code. See “File Manager Result Codes.”

Availability

Available in Mac OS X v10.3 and later.

Declared In

Files.h

FSCreateDirectoryUnicode

Creates a new directory (folder) with a Unicode name.

OSErr FSCreateDirectoryUnicode (
   const FSRef *parentRef,
   UniCharCount nameLength,
   const UniChar *name,
   FSCatalogInfoBitmap whichInfo,
   const FSCatalogInfo *catalogInfo,
   FSRef *newRef,
   FSSpecPtr newSpec,
   UInt32 *newDirID
);

Parameters

parentRef

A pointer to an FSRef specifying the parent directory where the new directory is to be created. See FSRef for a description of the FSRef data type.

nameLength

The length of the new directory's Unicode name.

name

A pointer to the Unicode name of the new directory.

whichInfo

A bitmap specifying which catalog information fields to set for the new directory. Specify the values for these fields in the catalogInfo parameter.

If you do not wish to set catalog information for the new directory, specify the constant kFSCatInfoNone. See “Catalog Information Bitmap Constants” for a description of the bits defined for this parameter.

catalogInfo

A pointer to the FSCatalogInfo structure which specifies the values for the catalog information fields for the new directory. Specify which fields to set in the whichInfo parameter.

This parameter is optional; specify NULL if you do not wish to set catalog information for the new directory.

See FSCatalogInfo for a description of the FSCatalogInfo data type.

newRef

On return, a pointer to the FSRef for the new directory. This parameter is optional; specify NULL if you do not want the FSRef returned.

newSpec

On return, a pointer to the FSSpec for the new directory. This parameter is optional; specify NULL if you do not want the FSSpec returned. See FSSpec for a description of the FSSpec data type.

newDirID

On return, a pointer to the directory ID of the directory. This parameter is optional; specify NULL if you do not want the directory ID returned.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

You may optionally set catalog information for the new directory using the whichInfo and catalogInfo parameters; this is equivalent to calling FSSetCatalogInfo , or one of the corresponding parameter block functions, PBSetCatalogInfoSync and PBSetCatalogInfoAsync , after creating the directory.

If possible, you should set the textEncodingHint field of the catalog information structure specified in the catalogInfo parameter. This will be used by the volume format when converting the Unicode filename to other encodings.

Special Considerations

If the FSCreateDirectoryUnicode function is present, but is not implemented by a particular volume, the File Manager will emulate this function by making the appropriate call to PBDirCreateSync. However, if the function is not directly supported by the volume, you will not be able to use the long Unicode directory names, or other features added with HFS Plus.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

BSDLLCTest

Declared In

Files.h

FSCreateFileUnicode

Creates a new file with a Unicode name.

OSErr FSCreateFileUnicode (
   const FSRef *parentRef,
   UniCharCount nameLength,
   const UniChar *name,
   FSCatalogInfoBitmap whichInfo,
   const FSCatalogInfo *catalogInfo,
   FSRef *newRef,
   FSSpecPtr newSpec
);

Parameters

parentRef

A pointer to an FSRef for the directory where the file is to be created. See FSRef for a description of the FSRef data type.

nameLength

The length of the file's name.

name

A pointer to the Unicode name for the new file.

whichInfo

A bitmap specifying which catalog information fields to set for the new file. You specify the values for these fields in the catalogInfo parameter. If you do not wish to set catalog information for the new file, pass the constant kFSCatInfoNone. See “Catalog Information Bitmap Constants” for a description of the bits defined for this parameter.

catalogInfo

A pointer to the FSCatalogInfo structure which specifies the values of the new file’s catalog information. Specify which fields to set in the whichInfo parameter.

This parameter is optional; specify NULL if you do not wish to set catalog information for the new file.

newRef

On return, a pointer to the FSRef for the new file. If you do not want the FSRef returned, specify NULL.

newSpec

On return, a pointer to the FSSpec for the new file. If you do not want the FSSpec returned, specify NULL. See FSSpec for a description of the FSSpec data type.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

You may optionally set catalog information for the new file using the whichInfo and catalogInfo parameters; this is equivalent to calling FSSetCatalogInfo , or one of the corresponding parameter block functions, PBSetCatalogInfoSync and PBSetCatalogInfoAsync , after creating the file.

Special Considerations

If the FSCreateFileUnicode function is present, but is not implemented by a particular volume, the File Manager will emulate this function by making the appropriate call to PBHCreateSync. However, if the function is not directly supported by the volume, you will not be able to use the long Unicode filenames, or other features added with HFS Plus.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

Files.h

FSCreateFork

Creates a named fork for a file or directory.

OSErr FSCreateFork (
   const FSRef *ref,
   UniCharCount forkNameLength,
   const UniChar *forkName
);

Parameters

ref: A pointer to an FSRef specifying the file or directory. See FSRef for a description of the FSRef data type.
forkNameLength: The length of the name of the new fork.
forkName: A pointer to the Unicode name of the fork.

Return Value

A result code. See “File Manager Result Codes.” If the named fork already exists, the function returns errFSForkExists. If the fork name is syntactically invalid or otherwise unsupported for the given volume, FSCreateFork returns errFSBadForkName or errFSNameTooLong.

Discussion

A newly created fork has zero length (that is, its logical end-of-file is zero). The data and resource forks of a file are automatically created and deleted as needed. This is done for compatibility with older APIs, and because data and resource forks are often handled specially. If a given fork always exists for a given volume format (such as data and resource forks for HFS and HFS Plus, or data forks for most other volume formats), an attempt to create that fork when a zero-length fork already exists should return noErr; if a non-empty fork already exists then errFSForkExists should be returned.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSCreateVolumeOperation

Returns an FSVolumeOperation which can be used for an asynchronous volume operation.

OSStatus FSCreateVolumeOperation (
   FSVolumeOperation *volumeOp
);

Parameters

volumeOp: The new FSVolumeOperation.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

When the operation is completed the FSVolumeOperation should be disposed of to free the memory associated with the operation using FSDisposeVolumeOperation.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

FSDeleteFork

Deletes a named fork from a file or directory.

OSErr FSDeleteFork (
   const FSRef *ref,
   UniCharCount forkNameLength,
   const UniChar *forkName
);

Parameters

ref: A pointer to an FSRef for the file or directory from which to delete the fork. See FSRef for a description of the FSRef data type.
forkNameLength: The length of the Unicode name of the fork name.
forkName: A pointer to the Unicode name of the fork to delete.

Return Value

A result code. See “File Manager Result Codes.” If the named fork does not exist, the function returns errFSForkNotFound.

Discussion

Any storage allocated to the fork is released. If a given fork always exists for a given volume format (such as data and resource forks for HFS and HFS Plus, or data forks for most other volume formats), this is equivalent to setting the logical size of the fork to zero.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSDeleteObject

Deletes a file or an empty directory.

OSErr FSDeleteObject (
   const FSRef *ref
);

Parameters

ref: A pointer to an FSRef specifying the file or directory to be deleted. If the object to be deleted is a directory, it must be empty (it must contain no files or folders). See FSRef for a description of the FSRef data type.

Return Value

A result code. See “File Manager Result Codes.” If you attempt to delete a folder for which there is an open catalog iterator, this function succeeds and returns noErr. Iteration, however, will continue to work until the iterator is closed.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

Files.h

FSDisposeVolumeOperation

Releases the memory associated with a volume operation.

OSStatus FSDisposeVolumeOperation (
   FSVolumeOperation volumeOp
);

Parameters

volumeOp: The FSVolumeOperation to release.

Return Value

A result code. See “File Manager Result Codes.” This function will return paramErr if the FSVolumeOperation is in use.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

FSEjectVolumeAsync

Asynchronously ejects a volume.

OSStatus FSEjectVolumeAsync (
   FSVolumeRefNum vRefNum,
   OptionBits flags,
   FSVolumeOperation volumeOp,
   void *clientData,
   FSVolumeEjectUPP callback,
   CFRunLoopRef runloop,
   CFStringRef runloopMode
);

Parameters

vRefNum: The volume reference number of the volume to eject.
flags: Options for future use.
volumeOp: An FSVolumeOperation returned by FSCreateVolumeOperation.
clientData: A pointer to client data associated with the operation. This parameter can be NULL.
callback: The function to call when eject is complete.
runloop: The runloop to run on.
runloopMode: The mode for the runloop.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

This function starts the process of ejecting the volume specified by the vRefNum parameter. If a callback function is provided, that function will be called when the eject operation is complete. Once this function returns noErr the status of the operation can be found using FSGetAsyncEjectStatus.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

FSEjectVolumeSync

Ejects a volume.

OSStatus FSEjectVolumeSync (
   FSVolumeRefNum vRefNum,
   OptionBits flags,
   pid_t *dissenter
);

Parameters

vRefNum: The volume reference number of the volume to eject.
flags: Options for future use.
dissenter: On return, a pointer to the pid of the process which denied the unmount if the eject is denied.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

This function ejects the volume specified by the vRefNum parameter. If the volume cannot be ejected the pid of the process which denied the unmount will be returned in the dissenter parameter. This function returns after the eject is complete. Ejecting a volume will result in the unmounting of other volumes on the same device.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

FSExchangeObjects

Swaps the contents of two files.

OSErr FSExchangeObjects (
   const FSRef *ref,
   const FSRef *destRef
);

Parameters

ref: A pointer to an FSRef for the first file. See FSRef for a description of the FSRef data type.
destRef: A pointer to an FSRef for the second file.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

The FSExchangeObjects function allows programs to implement a “safe save” operation by creating and writing a complete new file and swapping the contents. An alias, FSSpec, or FSRef that refers to the old file will now access the new data. The corresponding information in in-memory data structures are also exchanged.

Either or both files may have open access paths. After the exchange, the access path will refer to the opposite file’s data (that is, to the same data it originally referred, which is now part of the other file).

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSFileOperationCancel

Cancels an asynchronous file operation.

OSStatus FSFileOperationCancel (
   FSFileOperationRef fileOp
);

Parameters

fileOp: The file operation to cancel.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

This function makes the specified file operation ineligible to run on any run loop. You may call this function at any time during the operation. Typically, you would use this function if the user cancels the operation. Note that to release your file operation object, you still need to call CFRelease.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSFileOperationCopyStatus

Gets a copy of the current status information for an asynchronous file operation.

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

Parameters

fileOp: The file operation to access.
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: A pointer to a file operation stage variable. On output, the variable contains the current stage of the file operation.
error: A pointer to an error status variable. On output, the variable contains the current error status of the file operation.
statusDictionary: A pointer to a dictionary variable. On output, the variable contains a dictionary with more detailed status information. For information about the contents of the dictionary, see “File Operation Status Dictionary Keys”. You should release the dictionary when you are finished using it.
info: A pointer to a generic pointer. On output, the generic pointer refers to user-defined data associated with this file operation.

Return Value

A result code. See “File Manager Result Codes.”

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSFileOperationCreate

Creates an object that represents an asynchronous file operation.

FSFileOperationRef FSFileOperationCreate (
   CFAllocatorRef alloc
);

Parameters

alloc: The allocator to use. Pass NULL for the default allocator.

Return Value

A new FSFileOperation object, or NULL if the object could not be created. When you no longer need the object, you should release it by calling CFRelease.

Discussion

Before passing a file operation object to a function that starts an asynchronous copy or move operation, you should schedule the file operation using the function FSFileOperationScheduleWithRunLoop.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSFileOperationGetTypeID

Returns the Core Foundation type identifier for the FSFileOperation opaque type.

CFTypeID FSFileOperationGetTypeID (
   void
);

Return Value

The type identifier for the FSFileOperation opaque type. For information about this type, see FSFileOperationRef.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSFileOperationScheduleWithRunLoop

Schedules an asynchronous file operation with the specified run loop and mode.

OSStatus FSFileOperationScheduleWithRunLoop (
   FSFileOperationRef fileOp,
   CFRunLoopRef runLoop,
   CFStringRef runLoopMode
);

Parameters

fileOp: The file operation to schedule.
runLoop: The run loop in which to schedule the operation. For information about Core Foundation run loops, see Run Loops.
runLoopMode: The run loop mode in which to schedule the operation. In most cases, you may specify kCFRunLoopCommonModes.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

To run, a file operation must be scheduled with at least one run loop. A file operation can be scheduled with multiple run loop and mode combinations.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSFileOperationUnscheduleFromRunLoop

Unschedules an asynchronous file operation from the specified run loop and mode.

OSStatus FSFileOperationUnscheduleFromRunLoop (
   FSFileOperationRef fileOp,
   CFRunLoopRef runLoop,
   CFStringRef runLoopMode
);

Parameters

fileOp: The file operation to unschedule.
runLoop: The run loop on which to unschedule the operation.
runLoopMode: The run loop mode in which to unschedule the operation.

Return Value

A result code. See “File Manager Result Codes.”

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSFlushFork

Causes all data written to an open fork to be written to disk.

OSErr FSFlushFork (
   FSIORefNum forkRefNum
);

Parameters

forkRefNum: The reference number of the fork to flush.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

The FSFlushFork function causes the actual fork contents to be written to disk, as well as any other volume structures needed to access the fork. On HFS and HFS Plus, this includes the catalog, extents, and attribute B-trees; the volume bitmap; and the volume header and alternate volume header (the MDB and alternate MDB on HFS volumes), as needed.

On volumes that do not support FSFlushFork directly, the entire volume is flushed to be sure all volume structures associated with the fork are written to disk.

You do not, need to use FSFlushFork to flush a file fork before it is closed; the file is automatically flushed when it is closed and all cache blocks associated with it are removed from the cache.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSFlushVolume

For the specified volume, writes all open and modified files in the current process to permanent storage.

OSStatus FSFlushVolume (
   FSVolumeRefNum vRefNum
);

Parameters

vRefNum: The volume reference number of the volume to flush.

Return Value

A result code. See “File Manager Result Codes.”

Availability

Available in Mac OS X v10.5 and later.

Declared In

Files.h

FSGetAsyncEjectStatus

Returns the current status of an asynchronous eject operation.

OSStatus FSGetAsyncEjectStatus (
   FSVolumeOperation volumeOp,
   FSEjectStatus *status,
   OSStatus *volumeOpStatus,
   FSVolumeRefNum *volumeRefNum,
   pid_t *dissenter,
   void **clientData
);

Parameters

volumeOp: The asynchronous volume operation to get status about.
status: On return, a pointer to the status of the operation.
volumeOpStatus: If the status parameter is kAsyncEjectComplete then this contains the result code (OSStatus) for the operation on return.
volumeRefNum: On return, the volume reference number of the volume being ejected.
dissenter: On return, a pointer to the pid of the process which denied the unmount if the eject is denied.
clientData: On return, a pointer to client data associated with the original FSMountServerVolumeAsync operation.

Return Value

A result code. See “File Manager Result Codes.” A return value of noErr signifies that the status parameter has been filled with valid information.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

FSGetAsyncMountStatus

Returns the current status of an asynchronous mount operation.

OSStatus FSGetAsyncMountStatus (
   FSVolumeOperation volumeOp,
   FSMountStatus *status,
   OSStatus *volumeOpStatus,
   FSVolumeRefNum *mountedVolumeRefNum,
   void **clientData
);

Parameters

volumeOp: The asynchronous volume operation to get status about.
status: On return, a pointer to the status of the operation.
volumeOpStatus: If the status is kAsyncMountComplete then this parameter contains the result code for the operation on return.
mountedVolumeRefNum: If the status is kAsyncMountComplete and the volumeOpStatus parameter is noErr then this is the volume reference number for the newly mounted volume, on return.
clientData: On return, a pointer to client data associated with the original FSMountServerVolumeAsync operation.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

A return value of noErr signifies that the status parameter has been filled with valid information. If the status is kAsyncMountComplete then the rest of data returned is valid. If the status is anything else then the volumeOpStatus and mountedVolumeRefNum parameters are invalid, but the clientData parameter is valid.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

FSGetAsyncUnmountStatus

Returns the current status of an asynchronous unmount operation.

OSStatus FSGetAsyncUnmountStatus (
   FSVolumeOperation volumeOp,
   FSUnmountStatus *status,
   OSStatus *volumeOpStatus,
   FSVolumeRefNum *volumeRefNum,
   pid_t *dissenter,
   void **clientData
);

Parameters

volumeOp: The asynchronous volume operation to get status about.
status: On return, a pointer to the status of the operation.
volumeOpStatus: If the status is kAsyncUnmountComplete then this parameter contains a pointer to the result code (OSStatus) for the operation on return.
volumeRefNum: On return, a pointer to the volume reference number of the volume being unmounted.
dissenter: On return, a pointer to the pid of the process which denied the unmount if the unmount is denied.
clientData: On return, a pointer to client data associated with the original FSMountServerVolumeAsync operation.

Return Value

A result code. See “File Manager Result Codes.” A return value of noErr signifies that the status parameter has been filled with valid information.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

FSGetCatalogInfo

Returns catalog information about a file or directory. You can use this function to map an FSRef to an FSSpec.

OSErr FSGetCatalogInfo (
   const FSRef *ref,
   FSCatalogInfoBitmap whichInfo,
   FSCatalogInfo *catalogInfo,
   HFSUniStr255 *outName,
   FSSpecPtr fsSpec,
   FSRef *parentRef
);

Parameters

ref

A pointer to an FSRef specifying the file or directory for which to retrieve information. See FSRef for a description of the FSRef data type.

whichInfo

A bitmap specifying the catalog information fields to return. If you don’t want any catalog information, set whichInfo to the constant kFSCatInfoNone. See “Catalog Information Bitmap Constants” for a description of the bits in this parameter.

catalogInfo

On return, a pointer to a catalog information structure containing the information about the file or directory. Only the information specified in the whichInfo parameter is returned. If you don’t want any catalog information, pass NULL here. See FSCatalogInfo for a description of the FSCatalogInfo data type.

outName

On return, a pointer to the Unicode name of the file or directory is returned here. This parameter is optional; if you do not wish the name returned, pass NULL here. See HFSUniStr255 for a description of the HFSUniStr255 data type.

fsSpec

On return, a pointer to the FSSpec for the file or directory. This parameter is optional; if you do not wish the FSSpec returned, pass NULL here. See FSSpec for a description of the FSSpec data type.

parentRef

On return, a pointer to the FSRef for the object's parent directory. This parameter is optional; if you do not wish the parent directory returned, pass NULL here.

If the object specified in the ref parameter is a volume’s root directory, then the FSRef returned here will not be a valid FSRef, since the root directory has no parent object.

Return Value

A result code. See “File Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

Files.h

FSGetCatalogInfoBulk

Returns information about one or more objects from a catalog iterator. This function can return information about multiple objects in a single call.

OSErr FSGetCatalogInfoBulk (
   FSIterator iterator,
   ItemCount maximumObjects,
   ItemCount *actualObjects,
   Boolean *containerChanged,
   FSCatalogInfoBitmap whichInfo,
   FSCatalogInfo *catalogInfos,
   FSRef *refs,
   FSSpecPtr specs,
   HFSUniStr255 *names
);

Parameters

iterator

The iterator to use. You can obtain a catalog iterator with the function FSOpenIterator, or with one of the related parameter block calls, PBOpenIteratorSync and PBOpenIteratorAsync. Currently, the iterator must be created with the kFSIterateFlat option. See FSIterator for a description of the FSIterator data type.

maximumObjects

The maximum number of items to return for this call.

actualObjects

On return, a pointer to the actual number of items found for this call.

containerChanged

On return, a pointer to a value indicating whether or not the container’s contents have changed since the previous FSGetCatalogInfoBulk call. If true, the contents have changed. Objects may still be returned, even though the container has changed. If so, note that if the container has changed, then the total set of items returned may be incorrect: some items may be returned multiple times, and some items may not be returned at all.

This parameter is optional if you don’t want this information returned, pass a NULL pointer.

In Mac OS X version 10.2 and later, this parameter is always set to false. To find out whether the container has changed since the last call to FSGetCatalogInfoBulk, check the modification date of the container.

whichInfo

A bitmap specifying the catalog information fields to return for each item. If you don’t wish any catalog information returned, pass the constant kFSCatInfoNone in this parameter. For a description of the bits in this parameter, see “Catalog Information Bitmap Constants.”

catalogInfos

A pointer to an array of catalog information structures; one for each returned item. On input, the catalogInfos parameter should point to an array of maximumObjects catalog information structures.

This parameter is optional; if you do not wish any catalog information returned, pass NULL here.

refs

A pointer to an array of FSRef structures; one for each returned item. On input, this parameter should to point to an array of maximumObjectsFSRef structures.

This parameter is optional; if you do not wish any FSRef structures returned, pass NULL here.

specs

A pointer to an array of FSSpec structures; one for each returned item. On input, this parameter should to point to an array of maximumObjectsFSSpec structures.

This parameter is optional; if you do not wish any FSSpec structures returned, pass NULL here.

names

A pointer to an array of names; one for each returned item. If you want the Unicode name for each item found, set this parameter to point to an array of maximumObjectsHFSUniStr255 structures. Otherwise, set it to NULL.

Return Value

A result code. See “File Manager Result Codes.” When all of the iterator’s objects have been returned, the call will return errFSNoMoreItems.

Discussion

The FSGetCatalogInfoBulk call may complete and return noErr with fewer than maximumObjects items returned. This may be due to various reasons related to the internal implementation. In this case, you may continue to make FSGetCatalogInfoBulk calls using the same iterator.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

QTCarbonShell

Declared In

Files.h

FSGetDataForkName

Returns a Unicode string constant for the name of the data fork.

OSErr FSGetDataForkName (
   HFSUniStr255 *dataForkName
);

Parameters

dataForkName: On input, a pointer to an HFSUniStr255 structure. On return, this structure contains the Unicode name of the data fork. Currently, this is the empty string. See HFSUniStr255 for a description of the HFSUniStr255 data type.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

There is no parameter block-based form of this call since it is not dispatched to individual volume formats, and does not require any I/O.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSGetForkCBInfo

Returns information about a specified open fork, or about all open forks.

OSErr FSGetForkCBInfo (
   FSIORefNum desiredRefNum,
   FSVolumeRefNum volume,
   short *iterator,
   FSIORefNum *actualRefNum,
   FSForkInfo *forkInfo,
   FSRef *ref,
   HFSUniStr255 *outForkName
);

Parameters

desiredRefNum

If you want information on a specific fork, set this parameter to that fork’s reference number, and pass NULL in the iterator parameter. If you pass a non-zero value in this parameter, the function attempts to get information on the fork specified by that reference number.

Pass zero in this parameter to iterate over all open forks. You can limit this iteration to a specific volume with the volume parameter.

volume

The volume to search, when iterating over multiple forks. To iterate over all open forks on a single volume, specify the volume reference number in this parameter. To iterate over all open forks on all volumes, set this parameter to the constant kFSInvalidVolumeRefNum.

This parameter is ignored if you specify a fork reference number in the desiredRefNum parameter. Set desiredRefNum to zero if you wish to iterate over multiple forks.

See FSVolumeRefNum for a description of the FSVolumeRefNum data type.

iterator

A pointer to an iterator. If the desiredRefNum parameter is 0, the iterator maintains state between calls to FSGetForkCBInfo. Set the iterator parameter to 0 before you begin iterating, on the first call to FSGetForkCBInfo. On return, the iterator will be updated; pass this updated iterator in the iterator parameter of the next call to FSIterateForks to continue iterating.

actualRefNum

On return, a pointer to the reference number of the open fork. This parameter is optional if you do not wish to retrieve the fork’s reference number, pass NULL.

forkInfo

On return, a pointer to an FSForkInfo structure containing information about the open fork. This parameter is optional; if you do not wish this information returned, set forkInfo to NULL. See FSForkInfo for a description of the FSForkInfo data type.

On OS X, the value returned by FSGetForkCBInfo in the physicalEOF field of the FSForkInfo structure may differ from the physical file length reported by FSGetCatalogInfo, PBGetCatInfo, and related functions. When a write causes a file to grow in size, the physical length reported by FSGetCatalogInfo and similar calls increases by the clump size, which is a multiple of the allocation block size. However, the physical length returned by FSGetForkCBInfo changes according to the allocation block size and the file lengths returned by the respective functions get out of sync.

ref

On return, a pointer to the FSRef for the file or directory that contains the fork. This parameter is optional; if you do not wish to retrieve the FSRef, set ref to NULL. See FSRef for a description of the FSRef data type.

outForkName

On return, a pointer to the name of the fork. This parameter is optional; if you do not wish the name returned, set outForkName to NULL. See HFSUniStr255 for a description of the HFSUniStr255 data type.

Return Value

A result code. See “File Manager Result Codes.” If you are iterating over multiple forks, the function returns errFSNoMoreItems if there are no more open forks to return.

Discussion

Carbon applications are no longer guaranteed access to the FCB table. Instead, applications should use FSGetForkCBInfo, or one of the related parameter block functions, PBGetForkCBInfoSync and PBGetForkCBInfoAsync , to access information about a fork control block.

Special Considerations

Returning the fork information in the forkInfo parameter generally does not require a disk access; returning the information in the ref or forkName parameters may cause disk access for some volume formats.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSGetForkPosition

Returns the current position of an open fork.

OSErr FSGetForkPosition (
   FSIORefNum forkRefNum,
   SInt64 *position
);

Parameters

forkRefNum: The reference number of a fork previously opened by the FSOpenFork function or one of its corresponding parameter block calls, PBOpenForkSync and PBOpenForkAsync.
position: On return, a pointer to the current position of the fork. The returned fork position is relative to the start of the fork (that is, it is an absolute offset in bytes).

Return Value

A result code. See “File Manager Result Codes.”

Special Considerations

Before calling the FSGetForkPosition function, call the Gestalt function with the gestaltFSAttr selector to determine if FSGetForkPosition is available. If the function is available, but is not directly supported by a volume, the File Manager will automatically call PBGetFPosSync; however, you will not be able to determine the fork position of a named fork other than the data or resource fork, or of a fork larger than 2 GB.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSGetForkSize

Returns the size of an open fork.

OSErr FSGetForkSize (
   FSIORefNum forkRefNum,
   SInt64 *forkSize
);

Parameters

forkRefNum: The reference number of the open fork. You can obtain this fork reference number with the FSOpenFork function, or one of the corresponding parameter block calls, PBOpenForkSync and PBOpenForkAsync.
forkSize: On return, a pointer to the logical size (the logical end-of-file) of the fork, in bytes. The size returned is the total number of bytes that can be read from the fork; the amount of space actually allocated on the volume (the physical size) will probably be larger.

Return Value

A result code. See “File Manager Result Codes.”

Special Considerations

To determine whether the FSGetForkSize function is present, call the Gestalt function. If FSGetForkSize is present, but is not directly supported by a volume, the File Manager will call PBGetEOFSync; however, you will not be able to determine the size of a fork other than the data or resource fork, or of a fork larger than 2 GB.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSGetResourceForkName

Returns a Unicode string constant for the name of the resource fork.

OSErr FSGetResourceForkName (
   HFSUniStr255 *resourceForkName
);

Parameters

resourceForkName: On input, a pointer to an HFSUniStr255 structure. On return, this structure contains the Unicode name of the resource fork. Currently, this is “RESOURCE_FORK”. See HFSUniStr255 for a description of the HFSUniStr255 data type.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

There is no parameter block-based form of this call since it is not dispatched to individual volume formats, and does not require any I/O.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSGetVolumeInfo

Returns information about a volume.

OSErr FSGetVolumeInfo (
   FSVolumeRefNum volume,
   ItemCount volumeIndex,
   FSVolumeRefNum *actualVolume,
   FSVolumeInfoBitmap whichInfo,
   FSVolumeInfo *info,
   HFSUniStr255 *volumeName,
   FSRef *rootDirectory
);

Parameters

volume: If you wish to obtain information on a particular volume, pass that volume’s reference number here. If you wish to index through the list of mounted volumes, pass the constant kFSInvalidVolumeRefNum in this parameter. See FSVolumeRefNum for a description of the FSVolumeRefNum data type.
volumeIndex: The index of the desired volume, or 0 to use the volume reference number in the volume parameter.
actualVolume: On return, a pointer to the volume reference number of the volume. This is useful when indexing over all mounted volumes. If you don’t want this information (if, for instance, you supplied a particular volume reference number in the volume) parameter, set actualVolume to NULL.
whichInfo: A bitmap specifying which volume information fields to get and return in the info parameter. If you don’t want information about the volume returned in the info parameter, set whichInfo to kFSVolInfoNone. See “Volume Information Bitmap Constants” for a description of the bits in this parameter.
info: On return, a pointer to the volume information. If you don’t want this output, set this parameter to NULL. See FSVolumeInfo for a description of the FSVolumeInfo data type.
volumeName: On return, a pointer to the Unicode name of the volume. If you do not wish the name returned, pass NULL. See HFSUniStr255 for a description of the HFSUniStr255 data type.
rootDirectory: On return, a pointer to the FSRef for the volume’s root directory. If you do not wish the root directory returned, pass NULL. See FSRef for a description of the FSRef data type.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

You can specify a particular volume or index through the list of mounted volumes. To get information on a particular volume, pass the volume reference number of the desired volume in the volume parameter and set the volumeIndex parameter to zero. To index through the list of mounted volumes, pass kFSInvalidVolumeRefNum in the volume parameter and set volumeIndex to the index, starting at 1 with the first call to FSGetVolumeInfo.

When indexing through the list of mounted volumes, you may encounter an error with a particular volume. The terminating error code for full traversal of this list is nsvErr. In order to completely traverse the entire list, you may have to bump the index count when encountering other errors (for example, ioErr).

To get information about the root directory of a volume, use the FSGetCatalogInfo function, or one of the corresponding parameter block calls, PBGetCatalogInfoSync and PBGetCatalogInfoAsync.

Special Considerations

After an operation that changes the amount of free space on the volume—such as deleting a file—there may be a delay before a call to FSGetVolumeInfo returns the updated amount. This is because the File Manager caches and periodically updates file system information, to reduce the number of calls made to retrieve the information from the file system. Currently, the File Manager updates its information every 15 seconds. This primarily affects NFS volumes. DOS, SMB, UFS and WebDAV volumes were also affected by this in previous versions of Mac OS X, but behave correctly in Mac OS X version 10.3 and later.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSGetVolumeMountInfo

Retrieves the mounting information associated with the specified volume.

OSStatus FSGetVolumeMountInfo (
   FSVolumeRefNum volume,
   BytePtr buffer,
   ByteCount bufferSize,
   ByteCount *actualSize
);

Availability

Available in Mac OS X v10.5 and later.

Declared In

Files.h

FSGetVolumeMountInfoSize

Determines the size of the mounting information associated with the specified volume.

OSStatus FSGetVolumeMountInfoSize (
   FSVolumeRefNum volume,
   ByteCount *size
);

Availability

Available in Mac OS X v10.5 and later.

Declared In

Files.h

FSGetVolumeParms

Retrieves information about the characteristics of a volume.

OSStatus FSGetVolumeParms (
   FSVolumeRefNum volume,
   GetVolParmsInfoBuffer *buffer,
   ByteCount bufferSize
);

Availability

Available in Mac OS X v10.5 and later.

Declared In

Files.h

FSIterateForks

Determines the name and size of every named fork belonging to a file or directory.

OSErr FSIterateForks (
   const FSRef *ref,
   CatPositionRec *forkIterator,
   HFSUniStr255 *forkName,
   SInt64 *forkSize,
   UInt64 *forkPhysicalSize
);

Parameters

ref: A pointer to an FSRef specifying the file or directory to iterate. See FSRef for a description of the FSRef data type.
forkIterator: A pointer to a structure which maintains state between calls to FSIterateForks. Before the first call, set the initialize field of the structure to 0. The fork iterator will be updated after the call completes; the updated iterator should be passed into the next call. See CatPositionRec for a description of the CatPositionRec data type.
forkName: On return, a pointer to the Unicode name of the fork. This parameter is optional; if you do not wish the name returned, pass a NULL pointer. See HFSUniStr255 for a description of the HFSUniStr255 data type.
forkSize: On return, a pointer to the logical size of the fork, in bytes. This parameter is optional; if you do not wish to retrieve the logical fork size, pass a NULL pointer.
forkPhysicalSize: On return, a pointer to the physical size of the fork (that is, to the amount of space allocated on disk), in bytes. This parameter is optional; if you do not wish to retrieve the physical fork size, pass a NULL pointer.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

Since information is returned about one fork at a time, several calls may be required to iterate through all the forks. There is no guarantee about the order in which forks are returned; the order may vary between iterations.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSLockRange

Locks a range of bytes of the specified fork.

OSStatus FSLockRange (
   FSIORefNum forkRefNum,
   UInt16 positionMode,
   SInt64 positionOffset,
   UInt64 requestCount,
   UInt64 *rangeStart
);

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSMakeFSRefUnicode

Constructs an FSRef for a file or directory, given a parent directory and a Unicode name.

OSErr FSMakeFSRefUnicode (
   const FSRef *parentRef,
   UniCharCount nameLength,
   const UniChar *name,
   TextEncoding textEncodingHint,
   FSRef *newRef
);

Parameters

parentRef: A pointer to the FSRef of the parent directory of the file or directory for which to create a new FSRef. See FSRef for a description of the FSRef data type.
nameLength: The length of the file or directory name.
name: A pointer to the Unicode name for the file or directory. The name must be a leaf name; partial or full pathnames are not allowed. If you have a partial or full pathname in Unicode, you will have to parse it yourself and make multiple calls to FSMakeFSRefUnicode.
textEncodingHint: The suggested text encoding to use when converting the Unicode name of the file or directory to some other encoding. If you pass the constant kTextEncodingUnknown, the File Manager will use a default value.
newRef: On return, if the function returns a result of noErr, a pointer to the new FSRef.

Return Value

A result code. See “File Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

Files.h

FSMountLocalVolumeAsync

Mounts a volume asynchronously.

OSStatus FSMountLocalVolumeAsync (
   CFStringRef diskID,
   CFURLRef mountDir,
   FSVolumeOperation volumeOp,
   void *clientData,
   OptionBits flags,
   FSVolumeMountUPP callback,
   CFRunLoopRef runloop,
   CFStringRef runloopMode
);

Parameters

diskID: The disk to mount.
mountDir: Pass in NULL ; currently only NULL is supported.
volumeOp: An FSVolumeOperation returned by FSCreateVolumeOperation
clientData: A pointer to client data associated with the operation. This parameter can be NULL.
flags: Options for future use.
callback: The function to call when mount is complete. This parameter can be NULL.
runloop: The runloop to run on.
runloopMode: The mode for the runloop.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

This function starts the process to mount the disk specified by the diskID parameter at the location specified by the mountDir parameter. If mountDir is NULL, the default location is used. If a callback function is provided, that function will be called when the mount operation is complete. Once this function returns noErr the status of the operation can be found using the FSGetAsyncMountStatus function.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

FSMountLocalVolumeSync

Mounts a volume.

OSStatus FSMountLocalVolumeSync (
   CFStringRef diskID,
   CFURLRef mountDir,
   FSVolumeRefNum *mountedVolumeRefNum,
   OptionBits flags
);

Parameters

diskID: The disk to mount.
mountDir: Pass in NULL; currently only NULL is supported.
mountedVolumeRefNum: On return, a pointer to the volume reference number of the newly mounted volume.
flags: Options for future use.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

This function mounts the disk specified by the diskID parameter at the location specified by the mountDir parameter. If mountDir is NULL, the default location is used. This function returns after the mount is complete.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

FSMountServerVolumeAsync

Mounts a server volume asynchronously.

OSStatus FSMountServerVolumeAsync (
   CFURLRef url,
   CFURLRef mountDir,
   CFStringRef user,
   CFStringRef password,
   FSVolumeOperation volumeOp,
   void *clientData,
   OptionBits flags,
   FSVolumeMountUPP callback,
   CFRunLoopRef runloop,
   CFStringRef runloopMode
);

Parameters

url: The server to mount.
mountDir: The directory to mount the server to. If this parameter is NULL, the default location is used.
user: A string to pass as the user for authentication. This parameter can be NULL.
password: A string to pass as the password for authenticated log in. This parameter can be NULL.
volumeOp: An FSVolumeOperation returned by the FSCreateVolumeOperation function.
clientData: A pointer to client data associated with the operation. This parameter can be NULL.
flags: Options for future use.
callback: A function to call when the mount is complete. This parameter can be NULL.
runloop: The runloop to run on.
runloopMode: The mode for the runloop.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

This function will start the process to mount the server specified by the url parameter at the location specified by the mountDir parameter. If mountDir is NULL, the default location is used. An optional user and password can be passed in for authentication. If no user or password is provided then the underlying file system will handle authentication if required. If a callback function is provided, that function will be called when the mount operation is complete. Once this function returns noErr the status of the operation can be found using the FSGetAsyncMountStatus function.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

FSMountServerVolumeSync

Mounts a server volume.

OSStatus FSMountServerVolumeSync (
   CFURLRef url,
   CFURLRef mountDir,
   CFStringRef user,
   CFStringRef password,
   FSVolumeRefNum *mountedVolumeRefNum,
   OptionBits flags
);

Parameters

url: The server to mount.
mountDir: The directory to mount the server to. If this parameter is NULL, the default location is used.
user: A string to pass as the user for authentication.
password: A string to pass as the password for authenticated log in.
mountedVolumeRefNum: On return, a pointer to the volume reference number of the newly mounted volume.
flags: Options for future use.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

This function will mount the server specified by the url parameter at the location specified by the mountDir parameter. If mountDir is NULL, the default location is used. An optional user and password can be passed in for authentication. If no user or password is provided then the underlying file system will handle authentication if required. This function returns after the mount is complete.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

FSMoveObject

Moves a file or directory into a different directory.

OSErr FSMoveObject (
   const FSRef *ref,
   const FSRef *destDirectory,
   FSRef *newRef
);

Parameters

ref: A pointer to an FSRef specifying the file or directory to move. See FSRef for a description of the FSRef data type.
destDirectory: A pointer to an FSRef specifying the directory into which the file or directory indicated by the ref parameter will be moved.
newRef: On return, a pointer to the new FSRef for the file or directory in its new location. This parameter is optional; if you do not wish the FSRef returned, pass NULL.

Return Value

A result code. See “File Manager Result Codes.” If the destDirectory parameter specifies a non-existent object, dirNFErr is returned; if it refers to a file, errFSNotAFolder is returned. If the directory specified in the destDirectory parameter is on a different volume than the file or directory indicated in the ref parameter, diffVolErr is returned.

Discussion

Moving an object may change its FSRef. If you want to continue to refer to the object, you should pass a non- NULL pointer in the newRef parameter and use the FSRef returned there to refer to the object after the move. The original FSRef passed in the ref parameter may or may not be usable after the move. The newRef parameter may point to the same storage as the destDirectory or ref parameters.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSMoveObjectAsync

Starts an asynchronous file operation to move a source object to a destination directory.

OSStatus FSMoveObjectAsync (
   FSFileOperationRef fileOp,
   const FSRef *source,
   const FSRef *destDir,
   CFStringRef destName,
   OptionBits flags,
   FSFileOperationStatusProcPtr callback,
   CFTimeInterval statusChangeInterval,
   FSFileOperationClientContext *clientContext
);

Parameters

fileOp: The file operation object you created for this move operation.
source: A pointer to the source object to move. The object can be a file or a directory.
destDir: A pointer to the destination directory. If the destination directory is not on the same volume as the source object, the source object is copied and then deleted.
destName: The name for the new object in the destination directory. Pass NULL to use the name of the source object.
flags: One or more file operation option flags. See “File Operation Options.” If you specify the kFSFileOperationDoNotMoveAcrossVolumes flag and the destination directory is not on the same volume as the source object, this function does nothing and returns an error.
callback: A callback function to receive status updates as the file operation proceeds. For more information, see “File Operation Callbacks.” This parameter is optional; pass NULL if you don’t need to supply a status callback.
statusChangeInterval: The minimum time in seconds between callbacks within a single stage of an operation.
clientContext: User-defined data to associate with this operation. For more information, see FSFileOperationClientContext. This parameter is optional; pass NULL if you don’t need to supply a client context.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

If you specify a status callback function, status callbacks will occur in one of the run loop and mode combinations with which you scheduled the file operation.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSMoveObjectSync

Moves a source object to a destination directory.

OSStatus FSMoveObjectSync (
   const FSRef *source,
   const FSRef *destDir,
   CFStringRef destName,
   FSRef *target,
   OptionBits options
);

Parameters

source: A pointer to the source object to move. The object can be a file or a directory. On output, the source object is no longer valid; if you want to refer to the moved object, you should use the FSRef variable passed back in the target parameter.
destDir: A pointer to the destination directory. If the destination directory is not on the same volume as the source object, the source object is copied and then deleted.
destName: The name for the new object in the destination directory. Pass NULL to use the name of the source object.
target: A pointer to an FSRef variable that, on output, refers to the new object in the destination directory. This parameter is optional; pass NULL if you don’t need to refer to the new object.
options: One or more file operation option flags. See “File Operation Options.” If you specify the kFSFileOperationDoNotMoveAcrossVolumes flag and the destination directory is not on the same volume as the source object, this function does nothing and returns an error.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

If the destination directory is on the same volume as the source object, this is a fast operation. If the move is across volumes, this function could take a significant amount of time to execute; you should either call it in a thread other than the main thread or use FSMoveObjectAsync instead.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSMoveObjectToTrashAsync

Starts an asynchronous file operation to move a source object to the Trash.

OSStatus FSMoveObjectToTrashAsync (
   FSFileOperationRef fileOp,
   const FSRef *source,
   OptionBits flags,
   FSFileOperationStatusProcPtr callback,
   CFTimeInterval statusChangeInterval,
   FSFileOperationClientContext *clientContext
);

Parameters

fileOp: The file operation object you created for this move operation. For more information, see the function FSFileOperationCreate.
source: A pointer to the source object to move. The object can be a file or a directory.
flags: One or more file operation option flags. See “File Operation Options.”
callback: A callback function to receive status updates as the file operation proceeds. For more information, see “File Operation Callbacks.” This parameter is optional; pass NULL if you don’t need to supply a status callback.
statusChangeInterval: The minimum time in seconds between callbacks within a single stage of an operation.
clientContext: User-defined data to associate with this operation. This data is passed to the function you specify in the callback parameter. For more information, see FSFileOperationClientContext. This parameter is optional; pass NULL if you don’t need to supply a client context.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

This function starts an asynchronous file operation to move the object specified by the source parameter to the Trash. If the source volume does not support a trash folder, the operation will fail and return an error to the status callback specified in the callback parameter. (This is the same circumstance that triggers the delete immediately behavior in the Finder.)

Status callbacks occur on one of the runloop and mode combinations on which the operation was scheduled. Upon successful completion of the operation, the last currentItem parameter (passed to the last status callback or retrieved by calling FSFileOperationCopyStatus) is the object in the Trash.

Availability

Available in Mac OS X v10.5 and later.

Declared In

Files.h

FSMoveObjectToTrashSync

Moves a source object to the Trash.

OSStatus FSMoveObjectToTrashSync (
   const FSRef *source,
   FSRef *target,
   OptionBits options
);

Parameters

source: A pointer to the source object to move. The object can be a file or a directory. On output, the source object is no longer valid; if you want to refer to the moved object, you should use the value passed back in the target parameter.
target: A pointer to the target object that, on output, resides in a trash folder. This parameter is optional; pass NULL if you don’t need to refer to this object.
options: One or more file operation option flags. See “File Operation Options.”

Return Value

A result code. See “File Manager Result Codes.”

Discussion

This function moves a file or directory to the Trash, adjusting the object’s name if necessary. The appropriate trash folder is chosen based on the source volume and the current user. If the source volume does not support a trash folder, this function does nothing and returns an error. (This is the same circumstance that triggers the delete immediately behavior in the Finder.)

Availability

Available in Mac OS X v10.5 and later.

Declared In

Files.h

FSOpenFork

Opens any fork of a file or directory for streaming access.

OSErr FSOpenFork (
   const FSRef *ref,
   UniCharCount forkNameLength,
   const UniChar *forkName,
   SInt8 permissions,
   FSIORefNum *forkRefNum
);

Parameters

ref: A pointer to an FSRef specifying the file or directory owning the fork to open. See FSRef for a description of the FSRef data type.
forkNameLength: The length of the fork name in Unicode characters.
forkName: A pointer to the Unicode name of the fork to open. You can obtain the string constants for the data fork and resource fork names using the FSGetDataForkName and FSGetResourceForkName functions. All volume formats should support data and resource forks; other named forks may be supported by some volume formats.
permissions: A constant indicating the type of access which you wish to have to the fork via the returned fork reference. This parameter is the same as the permission parameter passed to the FSpOpenDF and FSpOpenRF functions. For a description of the types of access which you can request, see “File Access Permission Constants.”
forkRefNum: On return, a pointer to the fork reference number for accessing the open fork.

Return Value

A result code. See “File Manager Result Codes.” On some file systems, FSOpenFork will return the error eofErr if you try to open the resource fork of a file for which no resource fork exists with read-only access.

Discussion

When you use this function to open a file on a local volume and pass in a permissions value of fsCurPerm, fsWrPerm, or fsRdWrPerm , Mac OS X does not guarantee exclusive file access. Before making any assumptions about the underlying file access, you should always check to see whether the Supports Exclusive Locks feature is available. If this feature is not available, your application cannot know whether another application has access to the same file. For more information, see ADC Technical Note TN2037.

To access named forks or forks larger than 2GB, you must use the FSOpenFork function or one of the corresponding parameter block calls: PBOpenForkSync and PBOpenForkAsync. To determine if the FSOpenFork function is present, call the Gestalt function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSOpenIterator

Creates a catalog iterator that can be used to iterate over the contents of a directory or volume.

OSErr FSOpenIterator (
   const FSRef *container,
   FSIteratorFlags iteratorFlags,
   FSIterator *iterator
);

Parameters

container

A pointer to an FSRef for the directory to iterate. The set of items to iterate over can either be the objects directly contained in the directory, or all items directly or indirectly contained in the directory (in which case, the specified directory is the root of the subtree to iterate). See FSRef for a description of the FSRef data type.

iteratorFlags

A set of flags which controls whether the iterator iterates over subtrees or just the immediate children of the container. See “Iterator Flags” for a description of the flags defined for this parameter.

Iteration over subtrees which do not originate at the root directory of a volume are not currently supported, and passing the kFSIterateSubtree flag in this parameter returns errFSBadIteratorFlags. To determine whether subtree iterators are supported, check that the bSupportsSubtreeIterators bit returned by PBHGetVolParmsSync or PBHGetVolParmsAsync is set.

iterator

On return, a pointer to the new FSIterator. You can pass this iterator to the FSGetCatalogInfoBulk or FSCatalogSearch functions and their parameter block-based counterparts.

The iterator is automatically initialized so that the next use of the iterator returns the first item. The order that items are returned in is volume format dependent and may be different for two different iterators created with the same container and flags.

See FSIterator for a description of the FSIterator data type.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

Catalog iterators must be closed when you are done using them, whether or not you have iterated over all the items. Iterators are automatically closed upon process termination, just like open files. However, you should use the FSCloseIterator function, or one of the related parameter block functions, PBCloseIteratorSync and PBCloseIteratorAsync , to close an iterator to free up any system resources allocated to the iterator.

Before calling this function, you should check that it is present, by calling the Gestalt function.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

QTCarbonShell

Declared In

Files.h

FSPathCopyObjectAsync

Starts an asynchronous file operation to copy a source object to a destination directory using pathnames.

OSStatus FSPathCopyObjectAsync (
   FSFileOperationRef fileOp,
   const char *sourcePath,
   const char *destDirPath,
   CFStringRef destName,
   OptionBits flags,
   FSPathFileOperationStatusProcPtr callback,
   CFTimeInterval statusChangeInterval,
   FSFileOperationClientContext *clientContext
);

Parameters

fileOp: The file operation object you created for this copy operation.
sourcePath: The UTF-8 pathname of the source object to copy. The object can be a file or a directory.
destDirPath: The UTF-8 pathname of the destination directory.
destName: The name for the new object in the destination directory. Pass NULL to use the name of the source object.
flags: One or more file operation option flags. See “File Operation Options.”
callback: A callback function to receive status updates as the file operation proceeds. For more information, see “File Operation Callbacks.” This parameter is optional; pass NULL if you don’t need to supply a status callback.
statusChangeInterval: The minimum time in seconds between callbacks within a single stage of an operation.
clientContext: User-defined data to associate with this operation. For more information, see FSFileOperationClientContext. This parameter is optional; pass NULL if you don’t need to supply a client context.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

If you specify a status callback function, status callbacks will occur in one of the run loop and mode combinations with which you scheduled the file operation.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSPathCopyObjectSync

Copies a source object to a destination directory using pathnames.

OSStatus FSPathCopyObjectSync (
   const char *sourcePath,
   const char *destDirPath,
   CFStringRef destName,
   char **targetPath,
   OptionBits options
);

Parameters

sourcePath: The UTF-8 pathname of the source object to copy. The object can be a file or a directory.
destDirPath: The UTF-8 pathname of the destination directory.
destName: The name for the new object in the destination directory. Pass NULL to use the name of the source object.
targetPath: A pointer to a char* variable that, on output, refers to the UTF-8 pathname of the new object in the destination directory. If the operation fails, the pathname is set to NULL. When you no longer need the pathname, you should free it. This parameter is optional; pass NULL if you don’t need the pathname.
options: One or more file operation option flags. See “File Operation Options.”

Return Value

A result code. See “File Manager Result Codes.”

Discussion

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSPathFileOperationCopyStatus

Gets a copy of the current status information for an asynchronous file operation that uses pathnames.

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

Parameters

fileOp: The file operation to access.
currentItem: A pointer to a char* variable. On output, the variable refers to 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). You should free the pathname when you are finished using it.
stage: A pointer to a file operation stage variable. On output, the variable contains the current stage of the file operation.
error: A pointer to an error status variable. On output, the variable contains the current error status of the file operation.
statusDictionary: A pointer to a dictionary variable. On output, the variable contains a dictionary with more detailed status information. For information about the contents of the dictionary, see “File Operation Status Dictionary Keys”. You should release the dictionary when you are finished using it.
info: A pointer to a generic pointer. On output, the generic pointer refers to user-defined data associated with this file operation.

Return Value

A result code. See “File Manager Result Codes.”

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSPathMakeRef

Converts a POSIX-style pathname into an FSRef structure.

OSStatus FSPathMakeRef (
   const UInt8 *path,
   FSRef *ref,
   Boolean *isDirectory
);

Parameters

path: A UTF-8 C string that contains the pathname to convert.
ref: A pointer to an FSRef structure allocated by the caller. On output, the FSRef structure refers to the object whose location is specified by the path parameter.
isDirectory: A pointer to a Boolean variable allocated by the caller. On output, true indicates the object is a directory. This parameter is optional and may be NULL.

Return Value

A result code. See “File Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

CocoaDVDPlayer

Declared In

Files.h

FSPathMakeRefWithOptions

Converts a POSIX-style pathname into an FSRef structure with options.

OSStatus FSPathMakeRefWithOptions (
   const UInt8 *path,
   OptionBits options,
   FSRef *ref,
   Boolean *isDirectory
);

Parameters

path: A UTF-8 C string that contains the pathname to convert.
options: One or more conversion flags. See “Path Conversion Options.”
ref: A pointer to an FSRef structure allocated by the caller. On output, the FSRef structure refers to the object whose location is specified by the path parameter. If the object is a symbolic link, the options parameter determines whether the FSRef structure refers to the link itself or to the linked object.
isDirectory: A pointer to a Boolean variable allocated by the caller. On output, true indicates the object is a directory. This parameter is optional and may be NULL.

Return Value

A result code. See “File Manager Result Codes.”

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSPathMoveObjectAsync

Starts an asynchronous file operation to move a source object to a destination directory using pathnames.

OSStatus FSPathMoveObjectAsync (
   FSFileOperationRef fileOp,
   const char *sourcePath,
   const char *destDirPath,
   CFStringRef destName,
   OptionBits flags,
   FSPathFileOperationStatusProcPtr callback,
   CFTimeInterval statusChangeInterval,
   FSFileOperationClientContext *clientContext
);

Parameters

fileOp: The file operation object you created for this move operation.
sourcePath: The UTF-8 pathname of the source object to move. The object can be a file or a directory.
destDirPath: The UTF-8 pathname of the destination directory. If the destination directory is not on the same volume as the source object, the source object is copied and then deleted.
destName: The name for the new object in the destination directory. Pass NULL to use the name of the source object.
flags: One or more file operation option flags. See “File Operation Options.” If you specify the kFSFileOperationDoNotMoveAcrossVolumes flag and the destination directory is not on the same volume as the source object, this function does nothing and returns an error.
callback: A callback function to receive status updates as the file operation proceeds. For more information, see “File Operation Callbacks.” This parameter is optional; pass NULL if you don’t need to supply a status callback.
statusChangeInterval: The minimum time in seconds between callbacks within a single stage of an operation.
clientContext: User-defined data to associate with this operation. For more information, see FSFileOperationClientContext. This parameter is optional; pass NULL if you don’t need to supply a client context.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

If you specify a status callback function, status callbacks will occur in one of the run loop and mode combinations with which you scheduled the file operation.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSPathMoveObjectSync

Moves a source object to a destination directory using pathnames.

OSStatus FSPathMoveObjectSync (
   const char *sourcePath,
   const char *destDirPath,
   CFStringRef destName,
   char **targetPath,
   OptionBits options
);

Parameters

sourcePath: The UTF-8 pathname of the source object to move. The object can be a file or a directory.
destDirPath: The UTF-8 pathname of the destination directory. If the destination directory is not on the same volume as the source object, the source object is copied and then deleted.
destName: The name for the new object in the destination directory. Pass NULL to use the name of the source object.
targetPath: A pointer to a char* variable that, on output, refers to the UTF-8 pathname of the new object in the destination directory. When you no longer need the pathname, you should free it. If the operation fails, the pathname is set to NULL. This parameter is optional; pass NULL if you don’t need the pathname.
options: One or more file operation option flags. See “File Operation Options.” If you specify the kFSFileOperationDoNotMoveAcrossVolumes flag and the destination directory is not on the same volume as the source object, this function does nothing and returns an error.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

If the destination directory is on the same volume as the source object, this is a fast operation. If the move is across volumes, this function could take a significant amount of time to execute; you should call it in a thread other than the main thread or use FSPathMoveObjectAsync instead.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSPathMoveObjectToTrashAsync

Starts an asynchronous file operation to move a source object, specified using a pathname, to the Trash.

OSStatus FSPathMoveObjectToTrashAsync (
   FSFileOperationRef fileOp,
   const char *sourcePath,
   OptionBits flags,
   FSPathFileOperationStatusProcPtr callback,
   CFTimeInterval statusChangeInterval,
   FSFileOperationClientContext *clientContext
);

Parameters

fileOp: The file operation object you created for this move operation. For more information, see the function FSFileOperationCreate.
sourcePath: The UTF-8 pathname of the source object to move. The object can be a file or a directory.
flags: One or more file operation option flags. See “File Operation Options.”
callback: A callback function to receive status updates as the file operation proceeds. For more information, see “File Operation Callbacks.” This parameter is optional; pass NULL if you don’t need to supply a status callback.
statusChangeInterval: The minimum time in seconds between callbacks within a single stage of an operation.
clientContext: User-defined data to associate with this operation. This data is passed to the function you specify in the callback parameter. For more information, see FSFileOperationClientContext. This parameter is optional; pass NULL if you don’t need to supply a client context.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

This function starts an asynchronous file operation to move the object specified by the sourcePath parameter to the Trash. If the source volume does not support a trash folder, the operation will fail and return an error to the status callback specified in the callback parameter. (This is the same circumstance that triggers the delete immediately behavior in the Finder.)

Availability

Available in Mac OS X v10.5 and later.

Declared In

Files.h

FSPathMoveObjectToTrashSync

Moves a source object, specified using a pathname, to the Trash.

OSStatus FSPathMoveObjectToTrashSync (
   const char *sourcePath,
   char **targetPath,
   OptionBits options
);

Parameters

sourcePath: The UTF-8 pathname of the source object to move. The object can be a file or a directory.
targetPath: A pointer to a char* variable that, on output, refers to the UTF-8 pathname of the target object in the Trash. When you no longer need the pathname, you should free it. If the operation fails, the pathname is set to NULL. This parameter is optional; pass NULL if you don’t need the pathname.
options: One or more file operation option flags. See “File Operation Options.”

Return Value

A result code. See “File Manager Result Codes.”

Discussion

Availability

Available in Mac OS X v10.5 and later.

Declared In

Files.h

FSReadFork

Reads data from an open fork.

OSErr FSReadFork (
   FSIORefNum forkRefNum,
   UInt16 positionMode,
   SInt64 positionOffset,
   ByteCount requestCount,
   void *buffer,
   ByteCount *actualCount
);

Parameters

forkRefNum

The reference number of the fork to read from. You should have previously opened this fork using the FSOpenFork call, or one of the corresponding parameter block calls, PBOpenForkSync and PBOpenForkAsync.

positionMode

A constant specifying the base location within the fork for the start of the read. See “Position Mode Constants” for a description of the constants which you can use to specify the base location.

The caller can also use this parameter to hint to the File Manager whether the data being read should or should not be cached. Caching reads appropriately can be important in ensuring that your program access files efficiently.

If you add the forceReadMask constant to the value you pass in this parameter, this tells the File Manager to force the data to be read directly from the disk. This is different from adding the noCacheMask constant since forceReadMask tells the File Manager to flush the appropriate part of the cache first, then ignore any data already in the cache. However, data that is read may be placed in the cache for future reads. The forceReadMask constant is also passed to the device driver, indicating that the driver should avoid reading from any device caches.

See “Cache Constants” for further description of the constants that you can use to indicate your preference for caching the read.

positionOffset

The offset from the base location for the start of the read.

requestCount

The number of bytes to read.

buffer

A pointer to the buffer where the data will be returned.

actualCount

On return, a pointer to the number of bytes actually read. The value pointed to by the actualCount parameter should be equal to the value in the requestCount parameter unless there was an error during the read operation.

This parameter is optional; if you don’t want this information returned, set actualCount to NULL.

Return Value

A result code. See “File Manager Result Codes.” If there are fewer than requestCount bytes from the specified position to the logical end-of-file, then all of those bytes are read, and eofErr is returned.

Discussion

FSReadFork reads data starting at the position specified by the positionMode and positionOffset parameters. The function reads up to requestCount bytes into the buffer pointed to by the buffer parameter and sets the fork’s current position to the byte immediately after the last byte read (that is, the initial position plus actualCount).

To verify that data previously written has been correctly transferred to disk, read it back in using the forceReadMask constant in the positionMode parameter and compare it with the data you previously wrote.

When reading data from a fork, it is important to pay attention to that way that your program accesses the fork, because this can have a significant performance impact. For best results, you should use an I/O size of at least 4KB and block align your read requests. In Mac OS X, you should align your requests to 4KB boundaries.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSRefMakePath

Converts an FSRef structure into a POSIX-style pathname.

OSStatus FSRefMakePath (
   const FSRef *ref,
   UInt8 *path,
   UInt32 maxPathSize
);

Parameters

ref: A pointer to the FSRef structure to convert.
path: A pointer to a character buffer allocated by the caller. On output, the buffer contains a UTF-8 C string that specifies the absolute path to the object referred to by the ref parameter. The File Manager uses the maxPathSize parameter to make sure it does not overrun the buffer.
maxPathSize: The maximum number of bytes to copy into the buffer.

Return Value

A result code. See “File Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

BSDLLCTest

Declared In

Files.h

FSRenameUnicode

Renames a file or folder.

OSErr FSRenameUnicode (
   const FSRef *ref,
   UniCharCount nameLength,
   const UniChar *name,
   TextEncoding textEncodingHint,
   FSRef *newRef
);

Parameters

ref: A pointer to an FSRef for the file or directory to rename. See FSRef for a description of the FSRef data type.
nameLength: The length of the new name in Unicode characters.
name: A pointer to the new Unicode name of the file or directory.
textEncodingHint: The suggested text encoding to use when converting the Unicode name of the file or directory to some other encoding. If you pass the constant kTextEncodingUnknown, the File Manager will use a default value.
newRef: On return, a pointer to the new FSRef for the file or directory. This parameter is optional; if you do not wish the FSRef returned, pass NULL.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

Because renaming an object may change its FSRef, you should pass a non- NULL pointer in the newRef parameter and use the FSRef returned there to access the object after the renaming, if you wish to continue to refer to the object. The FSRef passed in the ref parameter may or may not be usable after the object is renamed. The FSRef returned in the newRef parameter may point to the same storage as the FSRef passed in ref.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSSetCatalogInfo

Sets catalog information about a file or directory.

OSErr FSSetCatalogInfo (
   const FSRef *ref,
   FSCatalogInfoBitmap whichInfo,
   const FSCatalogInfo *catalogInfo
);

Parameters

ref

A pointer to an FSRef specifying the file or directory whose information is to be changed. See FSRef for a description of the FSRef data type.

whichInfo

A bitmap specifying which catalog information fields to set. Only some of the catalog information fields may be set. These fields are given by the constant kFSCatInfoSettableInfo; no other bits may be set in the whichInfo parameter. See “Catalog Information Bitmap Constants” for a description of the bits in this parameter.

To set the user ID (UID) and group ID (GID), specify the kFSCatInfoSetOwnership flag in this parameter. The File Manager attempts to set the user and group ID to the values specified in the permissions field of the catalog information structure. If FSSetCatalogInfo cannot set the user and group IDs, it returns an error.

catalogInfo

A pointer to the structure containing the new catalog information. Only some of the catalog information fields may be set. The fields which may be set are:

createDate
contentModDate
attributeModDate
accessDate
backupDate
permissions
finderInfo
extFinderInfo
textEncodingHint

Return Value

A result code. See “File Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

BSDLLCTest

Declared In

Files.h

FSSetForkPosition

Sets the current position of an open fork.

OSErr FSSetForkPosition (
   FSIORefNum forkRefNum,
   UInt16 positionMode,
   SInt64 positionOffset
);

Parameters

forkRefNum: The reference number of a fork previously opened by the FSOpenFork, PBOpenForkSync, or PBOpenForkAsync function.
positionMode: A constant specifying the base location within the fork for the new position. If this parameter is equal to fsAtMark, then the positionOffset parameter is ignored. See “Position Mode Constants” for a description of the constants you can use to specify the base location.
positionOffset: The offset of the new position from the base location specified in the positionMode parameter.

Return Value

A result code. See “File Manager Result Codes.” This function returns the result code posErr if you attempt to set the current position of the fork to an offset before the start of the file.

Special Considerations

To determine if the FSSetForkPosition function is present, call the Gestalt function with the gestaltFSAttr selector. If the FSSetForkPosition function is present, but the volume does not directly support it, the File Manager will automatically call the PBSetFPosSync function. However, if the volume does not directly support the FSSetForkPosition function, you can only set the file position for the data and resource forks, and you cannot grow these files beyond 2GB.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSSetForkSize

Changes the size of an open fork.

OSErr FSSetForkSize (
   FSIORefNum forkRefNum,
   UInt16 positionMode,
   SInt64 positionOffset
);

Parameters

forkRefNum: The reference number of the open fork. You can obtain this fork reference number with the FSOpenFork function, or one of the corresponding parameter block calls, PBOpenForkSync and PBOpenForkAsync.
positionMode: A constant indicating the base location within the fork for the new size. See “Position Mode Constants” for more information about the constants you can use to specify the base location.
positionOffset: The offset of the new size from the base location specified in the positionMode parameter.

Return Value

A result code. See “File Manager Result Codes.” If there is not enough space on the volume to extend the fork, then dskFulErr is returned and the fork’s size is unchanged.

Discussion

The FSSetForkSize function sets the logical end-of-file to the position indicated by the positionMode and positionOffset parameters. The fork’s new size may be less than, equal to, or greater than the fork’s current size. If the fork’s new size is greater than the fork’s current size, then the additional bytes, between the old and new size, will have an undetermined value.

If the fork’s current position is larger than the fork’s new size, then the current position will be set to the new fork size the current position will be equal to the logical end-of-file.

Special Considerations

You do not need to check that the volume supports the FSSetForkSize function. If a volume does not support the FSSetForkSize function, but the FSSetForkSize function is present, the File Manager automatically calls the PBSetEOFSync function and translates between the calls appropriately.

Note, however, that if the volume does not support the FSSetForkSize function, you can only access the data and resource forks, and you cannot grow the fork beyond 2GB. To check that the FSSetForkSize function is present, call the Gestalt function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSSetVolumeInfo

Sets information about a volume.

OSErr FSSetVolumeInfo (
   FSVolumeRefNum volume,
   FSVolumeInfoBitmap whichInfo,
   const FSVolumeInfo *info
);

Parameters

volume: The volume reference number of the volume whose information is to be changed. See FSVolumeRefNum for a description of the FSVolumeRefNum data type.
whichInfo: A bitmap specifying which information to set. Only some of the volume information fields may be set. The settable fields are given by the constant kFSVolInfoSettableInfo; no other bits may be set in whichInfo. The fields which may be set are the backupDate, finderInfo, and flags fields. See “Volume Information Bitmap Constants” for a description of the bits in this parameter.
info: A pointer to the new volume information. See FSVolumeInfo for a description of the FSVolumeInfo data type.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

To set information about the root directory of a volume, use the FSSetCatalogInfo function, or one of the corresponding parameter block calls, PBSetCatalogInfoSync and PBSetCatalogInfoAsync.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

FSUnlockRange

Unlocks a range of bytes of the specified fork.

OSStatus FSUnlockRange (
   FSIORefNum forkRefNum,
   UInt16 positionMode,
   SInt64 positionOffset,
   UInt64 requestCount,
   UInt64 *rangeStart
);

Availability

Available in Mac OS X v10.4 and later.

Declared In

Files.h

FSUnmountVolumeAsync

Unmounts a volume asynchronously.

OSStatus FSUnmountVolumeAsync (
   FSVolumeRefNum vRefNum,
   OptionBits flags,
   FSVolumeOperation volumeOp,
   void *clientData,
   FSVolumeUnmountUPP callback,
   CFRunLoopRef runloop,
   CFStringRef runloopMode
);

Parameters

vRefNum: The volume reference number of the volume to unmount.
flags: Options for future use.
volumeOp: An FSVolumeOperation returned by the FSCreateVolumeOperation function.
clientData: A pointer to client data associated with the operation.
callback: The function to call when the unmount is complete.
runloop: The runloop to run on.
runloopMode: The mode for the runloop.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

This function starts the process of unmounting the volume specified by the vRefNum parameter. If a callback function is provided, that function will be called when the unmount operation is complete. Once this function returns noErr the status of the operation can be found using the FSGetAsyncUnmountStatus function.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

FSUnmountVolumeSync

Unmounts a volume.

OSStatus FSUnmountVolumeSync (
   FSVolumeRefNum vRefNum,
   OptionBits flags,
   pid_t *dissenter
);

Parameters

vRefNum: The volume reference number of the volume to unmount.
flags: Options for future use.
dissenter: On return, a pointer to the pid of the process which denied the unmount if the unmount is denied.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

This function unmounts the volume specified by the vRefNum parameter. If the volume cannot be unmounted the pid of the process which denied the unmount will be returned in the dissenter parameter. This function returns after the unmount is complete.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

FSVolumeMount

Mounts a volume using the specified mounting information.

OSStatus FSVolumeMount (
   BytePtr buffer,
   FSVolumeRefNum *mountedVolume
);

Availability

Available in Mac OS X v10.5 and later.

Declared In

Files.h

FSWriteFork

Writes data to an open fork.

OSErr FSWriteFork (
   FSIORefNum forkRefNum,
   UInt16 positionMode,
   SInt64 positionOffset,
   ByteCount requestCount,
   const void *buffer,
   ByteCount *actualCount
);

Parameters

forkRefNum

The reference number of the fork to which to write. You should have previously opened the fork using the FSOpenFork function, or one of the corresponding parameter block calls, PBOpenForkSync and PBOpenForkAsync.

positionMode

A constant specifying the base location within the fork for the start of the write. See “Position Mode Constants” for a description of the constants which you can use to specify the base location.

The caller can also use this parameter to hint to the File Manager whether the data being written should or should not be cached. See “Cache Constants” for further description of the constants that you can use to indicate your preference for caching.

positionOffset

The offset from the base location for the start of the write.

requestCount

The number of bytes to write.

buffer

A pointer to a buffer containing the data to write.

actualCount

On return, a pointer to the number of bytes actually written. The value pointed to by the actualCount parameter will be equal to the value in the requestCount parameter unless there was an error during the write operation.

This parameter is optional; if you don’t want this information, set actualCount to NULL.

Return Value

A result code. See “File Manager Result Codes.” If there is not enough space on the volume to write requestCount bytes, then dskFulErr is returned.

Discussion

FSWriteFork writes data starting at the position specified by the positionMode and positionOffset parameters. The function attempts to write requestCount bytes from the buffer pointed at by the buffer parameter and sets the fork’s current position to the byte immediately after the last byte written (that is, the initial position plus actualCount).

When writing data to a fork, it is important to pay attention to that way that your program accesses the fork, because this can have a significant performance impact. For best results, you should use an I/O size of at least 4KB and block align your write requests. In Mac OS X, you should align your requests to 4KB boundaries.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

InvokeFNSubscriptionUPP

Calls your directory change callback function.

void InvokeFNSubscriptionUPP (
   FNMessage message,
   OptionBits flags,
   void *refcon,
   FNSubscriptionRef subscription,
   FNSubscriptionUPP userUPP
);

Discussion

The File Manager calls this function to invoke the directory change function which you have provided for use after an asynchronous call has been completed. You should not need to use this function yourself. For more information on directory change functions, see FNSubscriptionProcPtr.

Availability

Available in Mac OS X v10.1 and later.

Declared In

Files.h

InvokeFSVolumeEjectUPP

Calls your volume ejection callback function.

void InvokeFSVolumeEjectUPP (
   FSVolumeOperation volumeOp,
   void *clientData,
   OSStatus err,
   FSVolumeRefNum volumeRefNum,
   pid_t dissenter,
   FSVolumeEjectUPP userUPP
);

Discussion

The File Manager calls this function to invoke the volume ejection function which you have provided for use after an asynchronous call has been completed. You should not need to use this function yourself. For more information on change notification functions, see FSVolumeEjectProcPtr.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

InvokeFSVolumeMountUPP

Calls your volume mount callback function.

void InvokeFSVolumeMountUPP (
   FSVolumeOperation volumeOp,
   void *clientData,
   OSStatus err,
   FSVolumeRefNum mountedVolumeRefNum,
   FSVolumeMountUPP userUPP
);

Discussion

The File Manager calls this function to invoke the volume mount function which you have provided for use after an asynchronous call has been completed. You should not need to use this function yourself. For more information on change notification functions, see FSVolumeMountProcPtr.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

InvokeFSVolumeUnmountUPP

Calls your volume unmount callback function.

void InvokeFSVolumeUnmountUPP (
   FSVolumeOperation volumeOp,
   void *clientData,
   OSStatus err,
   FSVolumeRefNum volumeRefNum,
   pid_t dissenter,
   FSVolumeUnmountUPP userUPP
);

Discussion

The File Manager calls this function to invoke the volume unmount function which you have provided for use after an asynchronous call has been completed. You should not need to use this function yourself. For more information on change notification functions, see FSVolumeUnmountProcPtr.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

InvokeIOCompletionUPP

Calls your I/O completion callback function.

void InvokeIOCompletionUPP (
   ParmBlkPtr paramBlock,
   IOCompletionUPP userUPP
);

Discussion

The File Manager calls this function to invoke the I/O completion function which you have provided for use after an asynchronous call has been completed. You should not need to use this function yourself. For more information on I/O completion functions, see IOCompletionProcPtr.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

NewFNSubscriptionUPP

Creates a new universal procedure pointer (UPP) to your directory change callback function.

FNSubscriptionUPP NewFNSubscriptionUPP (
   FNSubscriptionProcPtr userRoutine
);

Parameters

userRoutine: A pointer to a directory change callback function. For more information, see FNSubscriptionProcPtr.

Return Value

A UPP to your directory change callback function.

Availability

Available in Mac OS X v10.1 and later.

Declared In

Files.h

NewFSVolumeEjectUPP

Creates a new universal procedure pointer (UPP) to your volume ejection callback function.

FSVolumeEjectUPP NewFSVolumeEjectUPP (
   FSVolumeEjectProcPtr userRoutine
);

Parameters

userRoutine: A pointer to a volume ejection callback function. For more information, see FSVolumeEjectProcPtr.

Return Value

A UPP to your volume ejection callback function.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

NewFSVolumeMountUPP

Creates a new universal procedure pointer (UPP) to your volume mount callback function.

FSVolumeMountUPP NewFSVolumeMountUPP (
   FSVolumeMountProcPtr userRoutine
);

Parameters

userRoutine: A pointer to a volume mount callback function. For more information, see FSVolumeEjectProcPtr.

Return Value

A UPP to your volume mount callback function.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

NewFSVolumeUnmountUPP

Creates a new universal procedure pointer (UPP) to your volume unmount callback function.

FSVolumeUnmountUPP NewFSVolumeUnmountUPP (
   FSVolumeUnmountProcPtr userRoutine
);

Parameters

userRoutine: A pointer to a volume unmount callback function. For more information, see FSVolumeUnmountProcPtr.

Return Value

A UPP to your volume unmount callback function.

Availability

Available in Mac OS X v10.2 and later.

Declared In

Files.h

NewIOCompletionUPP

Creates a new universal procedure pointer (UPP) to your I/O completion callback function.

IOCompletionUPP NewIOCompletionUPP (
   IOCompletionProcPtr userRoutine
);

Parameters

userRoutine: A pointer to your I/O completion callback function. For more information, see IOCompletionProcPtr.

Return Value

A UPP to your I/O completion callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

PBAllocateForkAsync

Allocates space on a volume to an open fork.

void PBAllocateForkAsync (
   FSForkIOParam *paramBlock
);

Parameters

paramBlock: A pointer to a fork I/O parameter block. See FSForkIOParam for a description of the FSForkIOParam data type.

Discussion

The relevant fields of the parameter block are:

ioCompletion: On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.
ioResult: On output, the result code of the function.
forkRefNum: On input, the reference number of the open fork. You can obtain a fork reference number with the FSOpenFork function, or with one of the corresponding parameter block calls, PBOpenForkSync and PBOpenForkAsync.
allocationFlags: On input, a constant indicating how the new space should be allocated. See “Allocation Flags” for a description of the constants which you can use in this field.
positionMode: On input, a constant specifying the base location within the fork for the start of the allocation. See “Position Mode Constants” for more information on the constants which you can use to specify the base location.
positionOffset: On input, the offset from the base location of the start of the allocation.
allocationAmount: On input, the number of bytes to allocate. On output, the number of bytes actually allocated to the file. The number of bytes allocated may be smaller than the requested amount if some of the space was already allocated. The value returned in this field does not reflect any additional bytes that may have been allocated because space is allocated in terms of fixed units such as allocation blocks, or the use of a clump size to reduce fragmentation.

The PBAllocateForkAsync function attempts to allocate the number of requested bytes of physical storage starting at the offset specified by the positionMode and positionOffset fields. For volume formats that support preallocated space, you can later write to this range of bytes (including extending the size of the fork) without requiring an implicit allocation.

Any extra space allocated but not used will be deallocated when the fork is closed, using FSCloseFork , PBCloseForkSync , or PBCloseForkAsync ; or when flushed, using FSFlushFork , PBFlushForkSync , or PBFlushForkAsync.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

PBAllocateForkSync

Allocates space on a volume to an open fork.

OSErr PBAllocateForkSync (
   FSForkIOParam *paramBlock
);

Parameters

paramBlock: A pointer to a fork I/O parameter block. See FSForkIOParam for a description of the FSForkIOParam data type.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

The relevant fields of the parameter block are:

forkRefNum: On input, the reference number of the open fork. You can obtain a fork reference number with the FSOpenFork function, or with one of the corresponding parameter block functions, PBOpenForkSync and PBOpenForkAsync.
allocationFlags: On input, a constant indicating how the new space should be allocated. See “Allocation Flags” for a description of the constants you can use in this field.
positionMode: On input, a constant specifying the base location within the fork for the start of the allocation. See “Position Mode Constants” for more information on the constants which you can use to specify the base location.
positionOffset: On input, the offset from the base location of the start of the allocation.
allocationAmount: On input, the number of bytes to allocate. On output, the number of bytes actually allocated to the file. The number of bytes allocated may be smaller than the requested amount if some of the space was already allocated. The value returned in this field does not reflect any additional bytes that may have been allocated because space is allocated in terms of fixed units such as allocation blocks, or the use of a clump size to reduce fragmentation.

The PBAllocateForkSync function attempts to allocate the number of requested bytes of physical storage starting at the offset specified by the positionMode and positionOffset fields. For volume formats that support preallocated space, you can later write to this range of bytes (including extending the size of the fork) without requiring an implicit allocation.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

PBCatalogSearchAsync

Searches for objects traversed by a catalog iterator that match a given set of criteria.

void PBCatalogSearchAsync (
   FSCatalogBulkParam *paramBlock
);

Parameters

paramBlock: A pointer to a catalog information parameter block. See FSCatalogBulkParam for a description of the FSCatalogBulkParam data type.

Discussion

The relevant fields of this parameter are:

ioCompletion: On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.
ioResult: On output, the result code of the function. When the entire volume has been searched, errFSNoMoreItems is returned.
iterator: On input, the iterator to use. Objects traversed by this iterator are matched against the criteria specified by the searchParams field. You can obtain a catalog iterator with the function FSOpenIterator , or with one of the related parameter block calls, PBOpenIteratorSync and PBOpenIteratorAsync. Currently, this iterator must be created with the kFSIterateSubtree option and the container must be the root directory of a volume. See FSIterator for more information on the FSIterator data type.
searchParams: On input, a pointer to an FSSearchParams structure containing the search criteria. You can match against the object’s name in Unicode and by the fields in an FSCatalogInfo structure. You may use the same search bits as passed in the ioSearchBits field to the PBCatSearchSync and PBCatSearchAsync functions; they control the corresponding FSCatalogInfo fields. See “Catalog Search Masks” for a description of the search bits. There are a few new search criteria supported by PBCatalogSearchAsync but not by PBCatSearchSync and PBCatSearchAsync. These new search criteria are indicated by the constants described in “Catalog Search Constants.”If the searchTime field of this structure is non-zero, it is interpreted as a Time Manager duration; the search may terminate after this duration even if maximumItems objects have not been returned and the entire catalog has not been scanned. If searchTime is zero, there is no time limit for the search. If you are searching by any criteria other than name, you must set the searchInfo1 and searchInfo2 fields of the structure in this field to point to FSCatalogInfo structures containing the values to match against.
maximumItems: On input, the maximum number of items to return for this call.
actualItems: On output, the actual number of items returned for this call.
containerChanged: On output, a Boolean value indicating whether the container’s contents have changed. If true, the container’s contents changed since the previous PBCatalogSearchAsync call. Objects may still be returned even though the container changed. Note that if the container has changed, then the total set of items returned may be incorrect; some items may be returned multiple times, and some items may not be returned at all.
whichInfo: On input, a bitmap specifying the catalog information fields to return for each item. If you don’t wish any catalog information returned, pass the constant kFSCatInfoNone in this field. See “Catalog Information Bitmap Constants” for a description of the bits in this field.
catalogInfo: On output, a pointer to an array of FSCatalogInfo structures; one for each found item. On input, the catalogInfo field should point to an array of maximumItems catalog information structures. This field is optional; if you do not wish any catalog information returned, pass NULL here.
refs: On output, a pointer to an array of FSRef structures; one for each returned item. On input, if you want an FSRef for each item found, pass a pointer to an array of maximumItems FSRef structures. Otherwise, pass NULL.
names: On output, a pointer to an array of filenames; one for each returned item. On input, if you want the Unicode filename for each item found, pass a pointer to an array of maximumItems HFSUniStr255 structures. Otherwise, pass NULL.

A single search may span more than one call to PBCatalogSearchAsync. The call may complete with no error before scanning the entire volume. This typically happens because the time limit ( searchTime) has been reached or maximumItems items have been returned. If the search is not completed, you can continue the search by making another call to PBCatalogSearchAsync and passing the updated iterator returned by the previous call in the iterator field.

Before calling this function, you should determine that it is present, by calling the Gestalt function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

PBCatalogSearchSync

Searches for objects traversed by a catalog iterator that match a given set of criteria.

OSErr PBCatalogSearchSync (
   FSCatalogBulkParam *paramBlock
);

Parameters

paramBlock: A pointer to a catalog information parameter block. See FSCatalogBulkParam for a description of the FSCatalogBulkParam data type.

Return Value

A result code. See “File Manager Result Codes.” When the entire volume has been searched, errFSNoMoreItems is returned.

Discussion

The relevant fields of this parameter are:

iterator: On input, the iterator to use. Objects traversed by this iterator are matched against the criteria specified by the searchParams field. You can obtain a catalog iterator with the function FSOpenIterator , or with one of the related parameter block calls, PBOpenIteratorSync and PBOpenIteratorAsync. Currently, this iterator must be created with the kFSIterateSubtree option and the container must be the root directory of a volume. See FSIterator for more information on the FSIterator data type.
searchParams: On input, a pointer to an FSSearchParams structure containing the search criteria. You can match against the object’s name in Unicode and by the fields in an FSCatalogInfo structure. You may use the same search bits as passed in the ioSearchBits field to the PBCatSearchSync and PBCatSearchAsync functions; they control the corresponding FSCatalogInfo fields. See “Catalog Search Masks” for a description of the search bits. There are a few new search criteria supported by PBCatalogSearchSync but not by PBCatSearchSync and PBCatSearchAsync. These new search criteria are indicated by the constants described in “Catalog Search Constants.”If the searchTime field of this structure is non-zero, it is interpreted as a Time Manager duration; the search may terminate after this duration even if maximumItems objects have not been returned and the entire catalog has not been scanned. If searchTime is zero, there is no time limit for the search. If you are searching by any criteria other than name, you must set the searchInfo1 and searchInfo2 fields of the structure in this field to point to FSCatalogInfo structures containing the values to match against.
maximumItems: On input, the maximum number of items to return for this call.
actualItems: On output, the actual number of items returned for this call.
containerChanged: On output, a Boolean value indicating whether the container’s contents have changed. If true, the container’s contents changed since the previous PBCatalogSearchSync call. Objects may still be returned even though the container changed. Note that if the container has changed, then the total set of items returned may be incorrect; some items may be returned multiple times, and some items may not be returned at all.
whichInfo: On input, a bitmap specifying the catalog information fields to return for each item. If you don’t wish any catalog information returned, pass the constant kFSCatInfoNone in this field. See “Catalog Information Bitmap Constants” for a description of the bits in this field.
catalogInfo: On output, a pointer to an array of FSCatalogInfo structures; one for each found item. On input, the catalogInfo field should point to an array of maximumItems catalog information structures. This field is optional; if you do not wish any catalog information returned, pass NULL here.
refs: On output, a pointer to an array of FSRef structures; one for each returned item. On input, if you want an FSRef for each item found, pass a pointer to an array of maximumItems FSRef structures. Otherwise, pass NULL.
names: On output, a pointer to an array of filenames; one for each returned item. On input, if you want the Unicode filename for each item found, pass a pointer to an array of maximumItems HFSUniStr255 structures. Otherwise, pass NULL.

A single search may span more than one call to PBCatalogSearchSync. The call may complete with no error before scanning the entire volume. This typically happens because the time limit ( searchTime) has been reached or maximumItems items have been returned. If the search is not completed, you can continue the search by making another call to PBCatalogSearchSync and passing the updated iterator returned by the previous call in the iterator field.

Before calling this function, you should determine that it is present, by calling the Gestalt function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

PBCloseForkAsync

Closes an open fork.

void PBCloseForkAsync (
   FSForkIOParam *paramBlock
);

Parameters

paramBlock: A pointer to a fork I/O parameter block. See FSForkIOParam for a description of the FSForkIOParam.

Discussion

The relevant fields of the parameter block are:

ioCompletion: On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.
ioResult: On output, the result code of the function.
forkRefNum: On input, the reference number of the fork to close. After the call to this function, the reference number in this parameter is invalid.

The PBCloseForkAsync function causes all data written to the fork to be written to disk, in the same manner as the PBFlushForkAsync function, before it closes the fork.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

PBCloseForkSync

Closes an open fork.

OSErr PBCloseForkSync (
   FSForkIOParam *paramBlock
);

Parameters

paramBlock: A pointer to a fork I/O parameter block. See FSForkIOParam for a description of the FSForkIOParam.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

The relevant field of the parameter block is:

forkRefNum: On input, the reference number of the fork to close. After the call to this function, the reference number in this parameter is invalid.

The PBCloseForkSync function causes all data written to the fork to be written to disk, in the same manner as the PBFlushForkSync function, before it closes the fork.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

PBCloseIteratorAsync

Closes a catalog iterator.

void PBCloseIteratorAsync (
   FSCatalogBulkParam *paramBlock
);

Parameters

paramBlock: A pointer to a catalog information parameter block. See FSCatalogBulkParam for a description of the FSCatalogBulkParam data type.

Discussion

The relevant fields of the parameter block are:

ioCompletion: On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.
ioResult: On output, the result code of the function.
iterator: On input, the catalog iterator to close. PBCloseIteratorAsync releases memory and other system resources used by the iterator, making the iterator invalid. See FSIterator for a description of the FSIterator data type.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

PBCloseIteratorSync

Closes a catalog iterator.

OSErr PBCloseIteratorSync (
   FSCatalogBulkParam *paramBlock
);

Parameters

paramBlock: A pointer to a catalog information parameter block. See FSCatalogBulkParam for a description of the FSCatalogBulkParam data type.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

The relevant field of the parameter block is:

iterator: On input, the catalog iterator to close. PBCloseIteratorSync releases memory and other system resources used by the iterator, making the iterator invalid. See FSIterator for a description of the FSIterator data type.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

PBCompareFSRefsAsync

Determines whether two FSRef structures refer to the same file or directory.

void PBCompareFSRefsAsync (
   FSRefParam *paramBlock
);

Parameters

paramBlock: A pointer to a file system reference parameter block. See FSRefParam for a description of the FSRefParam data type.

Discussion

The relevant fields of the parameter block are:

ioCompletion: On input, a pointer to a completion routine. For more information about completion routines, see IOCompletionProcPtr.
ioResult: On output, the result code of the function. If the two FSRef structures refer to the same file or directory, then noErr is returned. If they refer to objects on different volumes, then diffVolErr is returned. If they refer to different files or directories on the same volume, then errFSRefsDifferent is returned. This call may return other errors, including nsvErr, fnfErr, dirNFErr, and volOffLinErr. See “File Manager Result Codes”.
ref: On input, a pointer to the first FSRef to compare. See FSRef for a description of the FSRef data type.
parentRef: On input, a pointer to the second FSRef to compare.

You must use FSCompareFSRefs , or one of the corresponding parameter block functions, PBCompareFSRefsSync and PBCompareFSRefsAsync, to compare FSRef structures. It is not possible to compare the FSRef structures directly since some bytes may be uninitialized, case-insensitive text, or contain hint information.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

PBCompareFSRefsSync

Determines whether two FSRef structures refer to the same file or directory.

OSErr PBCompareFSRefsSync (
   FSRefParam *paramBlock
);

Parameters

paramBlock: A pointer to a file system reference parameter block. See FSRefParam for a description of the FSRefParam data type.

Return Value

Discussion

The relevant fields of the parameter block are:

ref: On input, a pointer to the first FSRef to compare. See FSRef for a description of the FSRef data type.
parentRef: On input, a pointer to the second FSRef to compare.

You must use FSCompareFSRefs , or one of the corresponding parameter block functions, PBCompareFSRefsSync and PBCompareFSRefsAsync , to compare FSRef structures. It is not possible to compare the FSRef structures directly since some bytes may be uninitialized, case-insensitive text, or contain hint information.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

PBCreateDirectoryUnicodeAsync

Creates a new directory (folder) with a Unicode name.

void PBCreateDirectoryUnicodeAsync (
   FSRefParam *paramBlock
);

Parameters

paramBlock: A pointer to a file system reference parameter block. See FSRefParam for a description of the FSRefParam data type.

Discussion

The relevant fields of the parameter block are:

ioCompletion: On input, a pointer to a completion routine. For more information about completion routines, see IOCompletionProcPtr.
ioResult: On output, the result code of the function. See “File Manager Result Codes”.
ref: On input, a pointer to an FSRef for the parent directory where the new directory is to be created.
nameLength: On input, the number of Unicode characters in the new directory's name.
name: On input, a pointer to the Unicode name of the new directory.
whichInfo: On input, a bitmap specifying which catalog information fields to set for the new directory. Specify the values for these fields in the catInfo field. If you do not wish to set catalog information for the new directory, specify the constant kFSCatInfoNone. See “Catalog Information Bitmap Constants” for a description of the bits defined for this field.
catInfo: On input, a pointer to the FSCatalogInfo structure which specifies the values of the new directory’s catalog information fields. Specify which fields to set in the whichInfo field. Specify NULL if you do not wish to set catalog information for the new directory.
newRef: On output, a pointer to the FSRef for the new directory. If you do not want the FSRef returned, pass NULL on input.
spec: On output, a pointer to the FSSpec for the new directory. If you do not want the FSSpec returned, pass NULL on input.
ioDirID: On output, the directory ID of the new directory.

You may optionally set catalog information for the new directory using the whichInfo and catInfo fields; this is equivalent to calling FSSetCatalogInfo , or one of the corresponding parameter block functions, PBSetCatalogInfoSync and PBSetCatalogInfoAsync , after creating the directory.

If possible, you should set the textEncodingHint field of the catalog information structure specified in the catInfo field. This will be used by the volume format when converting the Unicode filename to other encodings.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

PBCreateDirectoryUnicodeSync

Creates a new directory (folder) with a Unicode name.

OSErr PBCreateDirectoryUnicodeSync (
   FSRefParam *paramBlock
);

Parameters

paramBlock: A pointer to a file system reference parameter block. See FSRefParam for a description of the FSRefParam data type.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

The relevant fields of the parameter block are:

ref: On input, a pointer to an FSRef for the parent directory where the new directory is to be created.
nameLength: On input, the number of Unicode characters in the new directory's name.
name: On input, a pointer to the Unicode name of the new directory.
whichInfo: On input, a bitmap specifying which catalog information fields to set for the new directory. Specify the values for these fields in the catInfo field. If you do not wish to set catalog information for the new directory, specify the constant kFSCatInfoNone. See “Catalog Information Bitmap Constants” for a description of the bits defined for this field.
catInfo: On input, a pointer to the FSCatalogInfo structure which specifies the values of the new directory’s catalog information fields. Specify which fields to set in the whichInfo field. Specify NULL if you do not wish to set catalog information for the new directory.
newRef: On output, a pointer to the FSRef for the new directory. If you do not want the FSRef returned, pass NULL on input.
spec: On output, a pointer to the FSSpec for the new directory. If you do not want the FSSpec returned, pass NULL on input.
ioDirID: On output, the directory ID of the new directory.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

PBCreateFileUnicodeAsync

Creates a new file with a Unicode name.

void PBCreateFileUnicodeAsync (
   FSRefParam *paramBlock
);

Parameters

paramBlock: A pointer to a file system reference parameter block. See FSRefParam for a description of the FSRefParam data type.

Discussion

The relevant fields of the parameter block are:

ioCompletion: On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.
ioResult: On output, the result code of the function. See “File Manager Result Codes”.
ref: On input, a pointer to an FSRef for the directory where the file is to be created.
nameLength: On input, the number of Unicode characters in the file's name.
name: On input, a pointer to the Unicode name of the new file.
whichInfo: On input, a bitmap specifying which catalog information fields to set for the new file. Specify the values for these fields in the catInfo field. If you do not wish to set catalog information for the new file, pass the constant kFSCatInfoNone here. See “Catalog Information Bitmap Constants” for a description of the bits defined for this field.
catInfo: On input, a pointer to the FSCatalogInfo structure which specifies the values of the new file’s catalog information fields. Specify which fields to set in the whichInfo field. This field is optional; specify NULL if you do not wish to set catalog information for the new file.
newRef: On output, a pointer to the FSRef for the new file. If you do not want the FSRef returned, pass NULL on input.
spec: On output, a pointer to the FSSpec for the new file. If you do not want the FSSpec returned, pass NULL on input.

You may optionally set catalog information for the file using the whichInfo and catInfo fields; this is equivalent to calling FSSetCatalogInfo , or one of the corresponding parameter block functions, PBSetCatalogInfoSync and PBSetCatalogInfoAsync , after creating the file.

Special Considerations

If the PBCreateFileUnicodeAsync function is present, but is not implemented by a particular volume, the File Manager will emulate this function by making the appropriate call to PBHCreateAsync. However, if the function is not directly supported by the volume, you will not be able to use the long Unicode filenames, or other features added with HFS Plus.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Files.h

PBCreateFileUnicodeSync

Creates a new file with a Unicode name.

OSErr PBCreateFileUnicodeSync (
   FSRefParam *paramBlock
);

Parameters

paramBlock: A pointer to a file system reference parameter block. See FSRefParam for a description of the FSRefParam data type.

Return Value

A result code. See “File Manager Result Codes.”

Discussion

The relevant fields of the parameter block are:

ref: On input, a pointer to an FSRef for the directory where the file is to be created.
nameLength: On input, the number of Unicode characters in the file's name.
name: On input, a pointer to the Unicode name of the new file.
whichInfo: On input, a bitmap specifying which catalog information fields to set for the new file. Specify the values for these fields in the catInfo field. If you do not wish to set catalog information for the new file, pass the constant kFSCatInfoNone here. See “Catalog Information Bitmap Constants”