Framework | CoreServices/CoreServices.h |
Declared in | Files.h HFSVolumes.h |
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.
FSGetCatalogInfo
PBGetCatalogInfoSync
PBGetCatalogInfoAsync
FSSetCatalogInfo
PBSetCatalogInfoSync
PBSetCatalogInfoAsync
FSpGetFInfo
Deprecated in Mac OS X v10.4
FSpSetFInfo
Deprecated in Mac OS X v10.4
HGetFInfo
Deprecated in Mac OS X v10.4
HSetFInfo
Deprecated in Mac OS X v10.4
PBGetCatInfoAsync
Deprecated in Mac OS X v10.4
PBGetCatInfoSync
Deprecated in Mac OS X v10.4
PBHGetFInfoAsync
Deprecated in Mac OS X v10.4
PBHGetFInfoSync
Deprecated in Mac OS X v10.4
PBHSetFInfoAsync
Deprecated in Mac OS X v10.4
PBHSetFInfoSync
Deprecated in Mac OS X v10.4
PBSetCatInfoAsync
Deprecated in Mac OS X v10.4
PBSetCatInfoSync
Deprecated in Mac OS X v10.4
PBDTAddAPPLAsync
Deprecated in Mac OS X v10.4
PBDTAddAPPLSync
Deprecated in Mac OS X v10.4
PBDTAddIconAsync
Deprecated in Mac OS X v10.4
PBDTAddIconSync
Deprecated in Mac OS X v10.4
PBDTCloseDown
Deprecated in Mac OS X v10.4
PBDTDeleteAsync
Deprecated in Mac OS X v10.4
PBDTDeleteSync
Deprecated in Mac OS X v10.4
PBDTFlushAsync
Deprecated in Mac OS X v10.4
PBDTFlushSync
Deprecated in Mac OS X v10.4
PBDTGetAPPLAsync
Deprecated in Mac OS X v10.4
PBDTGetAPPLSync
Deprecated in Mac OS X v10.4
PBDTGetCommentAsync
Deprecated in Mac OS X v10.4
PBDTGetCommentSync
Deprecated in Mac OS X v10.4
PBDTGetIconAsync
Deprecated in Mac OS X v10.4
PBDTGetIconInfoAsync
Deprecated in Mac OS X v10.4
PBDTGetIconInfoSync
Deprecated in Mac OS X v10.4
PBDTGetIconSync
Deprecated in Mac OS X v10.4
PBDTGetInfoAsync
Deprecated in Mac OS X v10.4
PBDTGetInfoSync
Deprecated in Mac OS X v10.4
PBDTGetPath
Deprecated in Mac OS X v10.4
PBDTOpenInform
Deprecated in Mac OS X v10.4
PBDTRemoveAPPLAsync
Deprecated in Mac OS X v10.4
PBDTRemoveAPPLSync
Deprecated in Mac OS X v10.4
PBDTRemoveCommentAsync
Deprecated in Mac OS X v10.4
PBDTRemoveCommentSync
Deprecated in Mac OS X v10.4
PBDTResetAsync
Deprecated in Mac OS X v10.4
PBDTResetSync
Deprecated in Mac OS X v10.4
PBDTSetCommentAsync
Deprecated in Mac OS X v10.4
PBDTSetCommentSync
Deprecated in Mac OS X v10.4
FSAllocateFork
PBAllocateForkSync
PBAllocateForkAsync
Allocate
Deprecated in Mac OS X v10.4
AllocContig
Deprecated in Mac OS X v10.4
PBAllocateAsync
Deprecated in Mac OS X v10.4
PBAllocateSync
Deprecated in Mac OS X v10.4
PBAllocContigAsync
Deprecated in Mac OS X v10.4
PBAllocContigSync
Deprecated in Mac OS X v10.4
FSCloseFork
PBCloseForkSync
PBCloseForkAsync
PBCloseAsync
Deprecated in Mac OS X v10.5
PBCloseSync
Deprecated in Mac OS X v10.5
FSClose
Deprecated in Mac OS X v10.4
PBHGetDirAccessAsync
Deprecated in Mac OS X v10.5
PBHGetDirAccessSync
Deprecated in Mac OS X v10.5
PBHSetDirAccessAsync
Deprecated in Mac OS X v10.5
PBHSetDirAccessSync
Deprecated in Mac OS X v10.5
PBHMapIDAsync
Deprecated in Mac OS X v10.5
PBHMapIDSync
Deprecated in Mac OS X v10.5
PBHMapNameAsync
Deprecated in Mac OS X v10.5
PBHMapNameSync
Deprecated in Mac OS X v10.5
PBHGetLogInInfoAsync
Deprecated in Mac OS X v10.4
PBFSCopyFileSync
PBFSCopyFileAsync
PBHCopyFileAsync
Deprecated in Mac OS X v10.5
PBHCopyFileSync
Deprecated in Mac OS X v10.5
PBHMoveRenameAsync
Deprecated in Mac OS X v10.4
PBHMoveRenameSync
Deprecated in Mac OS X v10.4
FSFileOperationCreate
FSFileOperationCancel
FSFileOperationGetTypeID
FSFileOperationScheduleWithRunLoop
FSFileOperationUnscheduleFromRunLoop
FSCopyObjectAsync
FSMoveObjectAsync
FSMoveObjectToTrashAsync
FSPathCopyObjectAsync
FSPathMoveObjectAsync
FSPathMoveObjectToTrashAsync
FSFileOperationCopyStatus
FSPathFileOperationCopyStatus
FSCopyObjectSync
FSMoveObjectSync
FSMoveObjectToTrashSync
FSPathCopyObjectSync
FSPathMoveObjectSync
FSPathMoveObjectToTrashSync
FSMakeFSRefUnicode
PBMakeFSRefUnicodeSync
PBMakeFSRefUnicodeAsync
FSpMakeFSRef
Deprecated in Mac OS X v10.5
PBMakeFSRefAsync
Deprecated in Mac OS X v10.5
PBMakeFSRefSync
Deprecated in Mac OS X v10.5
PBCreateFileIDRefAsync
Deprecated in Mac OS X v10.5
PBCreateFileIDRefSync
Deprecated in Mac OS X v10.5
PBDeleteFileIDRefAsync
Deprecated in Mac OS X v10.5
PBDeleteFileIDRefSync
Deprecated in Mac OS X v10.5
FSCreateDirectoryUnicode
PBCreateDirectoryUnicodeSync
PBCreateDirectoryUnicodeAsync
DirCreate
Deprecated in Mac OS X v10.4
FSpDirCreate
Deprecated in Mac OS X v10.4
PBDirCreateAsync
Deprecated in Mac OS X v10.4
PBDirCreateSync
Deprecated in Mac OS X v10.4
FSMakeFSSpec
Deprecated in Mac OS X v10.4
PBMakeFSSpecAsync
Deprecated in Mac OS X v10.4
PBMakeFSSpecSync
Deprecated in Mac OS X v10.4
FSCreateFileUnicode
PBCreateFileUnicodeSync
PBCreateFileUnicodeAsync
FSpCreate
Deprecated in Mac OS X v10.4
HCreate
Deprecated in Mac OS X v10.4
PBHCreateAsync
Deprecated in Mac OS X v10.4
PBHCreateSync
Deprecated in Mac OS X v10.4
NewIOCompletionUPP
NewFNSubscriptionUPP
NewFSVolumeEjectUPP
NewFSVolumeMountUPP
NewFSVolumeUnmountUPP
InvokeIOCompletionUPP
InvokeFNSubscriptionUPP
InvokeFSVolumeEjectUPP
InvokeFSVolumeMountUPP
InvokeFSVolumeUnmountUPP
DisposeIOCompletionUPP
DisposeFNSubscriptionUPP
DisposeFSVolumeEjectUPP
DisposeFSVolumeMountUPP
DisposeFSVolumeUnmountUPP
FSDeleteObject
PBDeleteObjectSync
PBDeleteObjectAsync
FSpDelete
Deprecated in Mac OS X v10.4
HDelete
Deprecated in Mac OS X v10.4
PBHDeleteAsync
Deprecated in Mac OS X v10.4
PBHDeleteSync
Deprecated in Mac OS X v10.4
FSExchangeObjects
PBExchangeObjectsSync
PBExchangeObjectsAsync
FSpExchangeFiles
Deprecated in Mac OS X v10.4
PBExchangeFilesAsync
Deprecated in Mac OS X v10.4
PBExchangeFilesSync
Deprecated in Mac OS X v10.4
FSGetVolumeInfo
PBGetVolumeInfoSync
PBGetVolumeInfoAsync
FSSetVolumeInfo
PBSetVolumeInfoSync
PBSetVolumeInfoAsync
FSCopyDiskIDForVolume
FSCopyURLForVolume
GetVRefNum
Deprecated in Mac OS X v10.4
PBHGetVInfoAsync
Deprecated in Mac OS X v10.4
PBHGetVInfoSync
Deprecated in Mac OS X v10.4
PBSetVInfoAsync
Deprecated in Mac OS X v10.4
PBSetVInfoSync
Deprecated in Mac OS X v10.4
PBXGetVolInfoAsync
Deprecated in Mac OS X v10.4
PBXGetVolInfoSync
Deprecated in Mac OS X v10.4
FSGetVolumeParms
PBHGetVolParmsAsync
Deprecated in Mac OS X v10.5
PBHGetVolParmsSync
Deprecated in Mac OS X v10.5
FSLockRange
PBXLockRangeSync
PBXLockRangeAsync
FSUnlockRange
PBXUnlockRangeSync
PBXUnlockRangeAsync
PBLockRangeAsync
Deprecated in Mac OS X v10.4
PBLockRangeSync
Deprecated in Mac OS X v10.4
PBUnlockRangeAsync
Deprecated in Mac OS X v10.4
PBUnlockRangeSync
Deprecated in Mac OS X v10.4
FSpRstFLock
Deprecated in Mac OS X v10.4
FSpSetFLock
Deprecated in Mac OS X v10.4
HRstFLock
Deprecated in Mac OS X v10.4
HSetFLock
Deprecated in Mac OS X v10.4
PBHRstFLockAsync
Deprecated in Mac OS X v10.4
PBHRstFLockSync
Deprecated in Mac OS X v10.4
PBHSetFLockAsync
Deprecated in Mac OS X v10.4
PBHSetFLockSync
Deprecated in Mac OS X v10.4
FSGetForkSize
PBGetForkSizeSync
PBGetForkSizeAsync
FSSetForkSize
PBSetForkSizeSync
PBSetForkSizeAsync
GetEOF
Deprecated in Mac OS X v10.4
PBGetEOFAsync
Deprecated in Mac OS X v10.4
PBGetEOFSync
Deprecated in Mac OS X v10.4
PBSetEOFAsync
Deprecated in Mac OS X v10.4
PBSetEOFSync
Deprecated in Mac OS X v10.4
SetEOF
Deprecated in Mac OS X v10.4
FSGetForkPosition
PBGetForkPositionSync
PBGetForkPositionAsync
FSSetForkPosition
PBSetForkPositionSync
PBSetForkPositionAsync
GetFPos
Deprecated in Mac OS X v10.4
PBGetFPosAsync
Deprecated in Mac OS X v10.4
PBGetFPosSync
Deprecated in Mac OS X v10.4
PBSetFPosAsync
Deprecated in Mac OS X v10.4
PBSetFPosSync
Deprecated in Mac OS X v10.4
SetFPos
Deprecated in Mac OS X v10.4
HGetVol
Deprecated in Mac OS X v10.4
HSetVol
Deprecated in Mac OS X v10.4
PBHGetVolAsync
Deprecated in Mac OS X v10.4
PBHGetVolSync
Deprecated in Mac OS X v10.4
PBHSetVolAsync
Deprecated in Mac OS X v10.4
PBHSetVolSync
Deprecated in Mac OS X v10.4
FSMountLocalVolumeSync
FSMountServerVolumeSync
FSUnmountVolumeSync
FSEjectVolumeSync
FSCreateVolumeOperation
FSCancelVolumeOperation
FSDisposeVolumeOperation
FSMountLocalVolumeAsync
FSMountServerVolumeAsync
FSUnmountVolumeAsync
FSEjectVolumeAsync
FSGetAsyncMountStatus
FSGetAsyncUnmountStatus
FSGetAsyncEjectStatus
PBUnmountVol
Deprecated in Mac OS X v10.4
UnmountVol
Deprecated in Mac OS X v10.4
FSGetVolumeMountInfoSize
FSGetVolumeMountInfo
FSVolumeMount
PBGetVolMountInfo
Deprecated in Mac OS X v10.5
PBGetVolMountInfoSize
Deprecated in Mac OS X v10.5
PBVolumeMount
Deprecated in Mac OS X v10.5
FSMoveObject
PBMoveObjectSync
PBMoveObjectAsync
FSRenameUnicode
PBRenameUnicodeSync
PBRenameUnicodeAsync
CatMove
Deprecated in Mac OS X v10.4
FSpCatMove
Deprecated in Mac OS X v10.4
FSpRename
Deprecated in Mac OS X v10.4
HRename
Deprecated in Mac OS X v10.4
PBCatMoveAsync
Deprecated in Mac OS X v10.4
PBCatMoveSync
Deprecated in Mac OS X v10.4
PBHRenameAsync
Deprecated in Mac OS X v10.4
PBHRenameSync
Deprecated in Mac OS X v10.4
PBGetFCBInfoAsync
Deprecated in Mac OS X v10.4
PBGetFCBInfoSync
Deprecated in Mac OS X v10.4
FSOpenFork
PBOpenForkSync
PBOpenForkAsync
FSpOpenDF
Deprecated in Mac OS X v10.4
FSpOpenRF
Deprecated in Mac OS X v10.4
HOpen
Deprecated in Mac OS X v10.4
HOpenDF
Deprecated in Mac OS X v10.4
HOpenRF
Deprecated in Mac OS X v10.4
PBHOpenAsync
Deprecated in Mac OS X v10.4
PBHOpenDFAsync
Deprecated in Mac OS X v10.4
PBHOpenDFSync
Deprecated in Mac OS X v10.4
PBHOpenRFAsync
Deprecated in Mac OS X v10.4
PBHOpenRFSync
Deprecated in Mac OS X v10.4
PBHOpenSync
Deprecated in Mac OS X v10.4
PBHOpenDenyAsync
Deprecated in Mac OS X v10.5
PBHOpenDenySync
Deprecated in Mac OS X v10.5
PBHOpenRFDenyAsync
Deprecated in Mac OS X v10.5
PBHOpenRFDenySync
Deprecated in Mac OS X v10.5
FSReadFork
PBReadForkSync
PBReadForkAsync
FSWriteFork
PBWriteForkSync
PBWriteForkAsync
PBReadAsync
Deprecated in Mac OS X v10.5
PBReadSync
Deprecated in Mac OS X v10.5
PBWriteAsync
Deprecated in Mac OS X v10.5
PBWriteSync
Deprecated in Mac OS X v10.5
FSRead
Deprecated in Mac OS X v10.4
FSWrite
Deprecated in Mac OS X v10.4
PBResolveFileIDRefAsync
Deprecated in Mac OS X v10.5
PBResolveFileIDRefSync
Deprecated in Mac OS X v10.5
PBCatSearchAsync
Deprecated in Mac OS X v10.4
PBCatSearchSync
Deprecated in Mac OS X v10.4
FSOpenIterator
PBOpenIteratorSync
PBOpenIteratorAsync
FSCatalogSearch
PBCatalogSearchSync
PBCatalogSearchAsync
FSCloseIterator
PBCloseIteratorSync
PBCloseIteratorAsync
FSFlushFork
PBFlushForkSync
PBFlushForkAsync
PBFlushFileAsync
Deprecated in Mac OS X v10.4
PBFlushFileSync
Deprecated in Mac OS X v10.4
FSFlushVolume
PBFlushVolumeSync
PBFlushVolumeAsync
FlushVol
Deprecated in Mac OS X v10.5
PBFlushVolAsync
Deprecated in Mac OS X v10.5
PBFlushVolSync
Deprecated in Mac OS X v10.5
FNNotify
FNNotifyAll
FNNotifyByPath
FNSubscribe
FNSubscribeByPath
FNUnsubscribe
FNGetDirectoryForSubscription
This section lists functions that are not recommended and you should no longer use.
PBWaitIOComplete
Deprecated in Mac OS X v10.5
PBGetForeignPrivsAsync
Deprecated in Mac OS X v10.4
PBGetForeignPrivsSync
Deprecated in Mac OS X v10.4
PBGetUGEntryAsync
Deprecated in Mac OS X v10.4
PBGetUGEntrySync
Deprecated in Mac OS X v10.4
PBGetXCatInfoAsync
Deprecated in Mac OS X v10.4
PBGetXCatInfoSync
Deprecated in Mac OS X v10.4
PBHGetLogInInfoSync
Deprecated in Mac OS X v10.4
PBSetForeignPrivsAsync
Deprecated in Mac OS X v10.4
PBSetForeignPrivsSync
Deprecated in Mac OS X v10.4
PBShareAsync
Deprecated in Mac OS X v10.4
PBShareSync
Deprecated in Mac OS X v10.4
PBUnshareAsync
Deprecated in Mac OS X v10.4
PBUnshareSync
Deprecated in Mac OS X v10.4
Deletes a universal procedure pointer (UPP) to your directory change callback function.
void DisposeFNSubscriptionUPP ( FNSubscriptionUPP userUPP );
The UPP to delete.
You should use this function to delete the UPP after the File Manager is finished calling your directory change callback function.
Files.h
Deletes a universal procedure pointer (UPP) to your volume ejection callback function.
void DisposeFSVolumeEjectUPP ( FSVolumeEjectUPP userUPP );
The UPP to delete.
You should use this function to delete the UPP after the File Manager is finished calling your volume ejection callback function.
Files.h
Deletes a universal procedure pointer (UPP) to your volume mount callback function.
void DisposeFSVolumeMountUPP ( FSVolumeMountUPP userUPP );
The UPP to delete.
You should use this function to delete the UPP after the File Manager is finished calling your volume mount callback function.
Files.h
Deletes a universal procedure pointer (UPP) to your volume unmount callback function.
void DisposeFSVolumeUnmountUPP ( FSVolumeUnmountUPP userUPP );
The UPP to delete.
You should use this function to delete the UPP after the File Manager is finished calling your volume unmount callback function.
Files.h
Deletes a universal procedure pointer (UPP) to your I/O completion callback function.
void DisposeIOCompletionUPP ( IOCompletionUPP userUPP );
The UPP to delete.
You should use this function to delete the UPP after the File Manager is finished calling your I/O completion callback function.
Files.h
Fetches the directory for which this subscription was originally entered.
OSStatus FNGetDirectoryForSubscription ( FNSubscriptionRef subscription, FSRef *ref );
The subscription previously returned from the functions FNSubscribe
or FNSubscribeByPath
.
On return, a file system reference to the directory for which this subscription was created.
A result code. See “File Manager Result Codes.”
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.
Files.h
Broadcasts notification of changes to the specified directory.
OSStatus FNNotify ( const FSRef *ref, FNMessage message, OptionBits flags );
A file system reference describing the directory for which to broadcast the notification.
An indication of what happened to the target directory.
Options regarding the delivery of the notification. Specify kNilOptions
for the default behavior.
A result code. See “File Manager Result Codes.”
Files.h
Broadcasts notification of changes to the filesystem.
OSStatus FNNotifyAll ( FNMessage message, OptionBits flags );
An indication of what happened.
Options regarding the delivery of the notification. Specify kNilOptions
for the default behavior.
A result code. See “File Manager Result Codes.”
This function should only be used by installers or programs which make lots of changes and only send one broadcast.
Files.h
Broadcasts notification of changes to the specified directory.
OSStatus FNNotifyByPath ( const UInt8 *path, FNMessage message, OptionBits flags );
The path to the directory for which to broadcast the notification.
An indication of what happened to the target directory.
Options regarding the delivery of the notification. Specify kNilOptions
for the default behavior.
A result code. See “File Manager Result Codes.”
Files.h
Subscribes to change notifications for the specified directory.
OSStatus FNSubscribe ( const FSRef *directoryRef, FNSubscriptionUPP callback, void *refcon, OptionBits flags, FNSubscriptionRef *subscription );
A file system reference describing the directory for which the caller wants notifications.
A pointer to the function to call when a notification arrives.
A pointer to user state carried with the subscription.
Specify kNilOptions
, or one of the options described in “Notification Subscription Options.”
A subscription token for subsequent query or unsubscription.
A result code. See “File Manager Result Codes.”
Files.h
Subscribes to change notifications for the specified directory.
OSStatus FNSubscribeByPath ( const UInt8 *directoryPath, FNSubscriptionUPP callback, void *refcon, OptionBits flags, FNSubscriptionRef *subscription );
A path to the directory for which the caller wants notifications.
The function to call when a notification arrives.
A pointer to the user state carried with the subscription.
Specify kNilOptions
, or one of the options described in “Notification Subscription Options.”
A subscription token for subsequent query or unsubscription.
A result code. See “File Manager Result Codes.”
Files.h
Releases a subscription which is no longer needed.
OSStatus FNUnsubscribe ( FNSubscriptionRef subscription );
A subscription previously returned from the FNSubscribe
orFNSubscribeByPath
functions.
A result code. See “File Manager Result Codes.”
Files.h
Allocates space on a volume to an open fork.
OSErr FSAllocateFork ( FSIORefNum forkRefNum, FSAllocationFlags flags, UInt16 positionMode, SInt64 positionOffset, UInt64 requestCount, UInt64 *actualCount );
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
.
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.
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.
The offset from the base location of the start of the allocation.
The number of bytes to allocate.
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
.
A result code. See “File Manager Result Codes.”
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
.
Files.h
Cancels an outstanding asynchronous volume mounting operation.
OSStatus FSCancelVolumeOperation ( FSVolumeOperation volumeOp );
The asynchronous volume operation to cancel.
A result code. See “File Manager Result Codes.”
This function currently is only supported for server mounts.
Files.h
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 );
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.
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.
The maximum number of items to return for this call.
On return, a pointer to the actual number of items found for this call.
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.
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.
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.
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 maximumObjects
FSRef
structures. Otherwise, set it to NULL
. See FSRef
for a description of the FSRef
data type.
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 maximumObjects
HFSUniStr255
structures. Otherwise, set it to NULL
. See HFSUniStr255
for a description of the HFSUniStr255
data type.
A result code. See “File Manager Result Codes.” When the entire volume has been searched, errFSNoMoreItems
is returned.
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.
Files.h
Closes an open fork.
OSErr FSCloseFork ( FSIORefNum forkRefNum );
The reference number of the fork to close. After the call to this function, the reference number in this parameter is invalid.
A result code. See “File Manager Result Codes.”
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.
Files.h
Closes a catalog iterator.
OSErr FSCloseIterator ( FSIterator 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.
A result code. See “File Manager Result Codes.”
This function releases memory and other system resources used by the iterator. The iterator becomes invalid.
Files.h
Determines whether two FSRef
structures refer to the same file or directory.
OSErr FSCompareFSRefs ( const FSRef *ref1, const FSRef *ref2 );
A pointer to the first FSRef
to compare. For a description of the FSRef
data type, see FSRef
.
A pointer to the second FSRef
to compare.
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
.
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.
Files.h
Returns a copy of the disk ID for a volume.
OSStatus FSCopyDiskIDForVolume ( FSVolumeRefNum vRefNum, CFStringRef *diskID );
The volume reference number of the target volume.
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.
A result code. See “File Manager Result Codes.”
Files.h
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 );
The file operation object you created for this copy operation.
A pointer to the source object to copy. The object can be a file or a directory.
A pointer to the destination directory.
The name for the new object in the destination directory. Pass NULL
to use the name of the source object.
One or more file operation option flags. See “File Operation Options.”
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.
The minimum time in seconds between callbacks within a single stage of an operation.
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.
A result code. See “File Manager Result Codes.”
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.
Files.h
Copies a source object to a destination directory.
OSStatus FSCopyObjectSync ( const FSRef *source, const FSRef *destDir, CFStringRef destName, FSRef *target, OptionBits options );
A pointer to the source object to copy. The object can be a file or a directory.
A pointer to the destination directory.
The name for the new object in the destination directory. Pass NULL
to use the name of the source object.
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.
One or more file operation option flags. See “File Operation Options.”
A result code. See “File Manager Result Codes.”
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.
Files.h
Returns a copy of the URL for a volume.
OSStatus FSCopyURLForVolume ( FSVolumeRefNum vRefNum, CFURLRef *url );
The volume reference number of the target volume.
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.
A result code. See “File Manager Result Codes.”
Files.h
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 );
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.
The length of the new directory's Unicode name.
A pointer to the Unicode name of the new directory.
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.
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.
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.
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.
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.
A result code. See “File Manager Result Codes.”
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.
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.
Files.h
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 );
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.
The length of the file's name.
A pointer to the Unicode name for the new file.
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.
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.
On return, a pointer to the FSRef
for the new file. If you do not want the FSRef
returned, specify NULL
.
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.
A result code. See “File Manager Result Codes.”
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.
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.
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.
Files.h
Creates a named fork for a file or directory.
OSErr FSCreateFork ( const FSRef *ref, UniCharCount forkNameLength, const UniChar *forkName );
A pointer to an FSRef
specifying the file or directory. See FSRef
for a description of the FSRef
data type.
The length of the name of the new fork.
A pointer to the Unicode name of the fork.
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
.
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.
Files.h
Returns an FSVolumeOperation
which can be used for an asynchronous volume operation.
OSStatus FSCreateVolumeOperation ( FSVolumeOperation *volumeOp );
The new FSVolumeOperation
.
A result code. See “File Manager Result Codes.”
When the operation is completed the FSVolumeOperation
should be disposed of to free the memory associated with the operation using FSDisposeVolumeOperation
.
Files.h
Deletes a named fork from a file or directory.
OSErr FSDeleteFork ( const FSRef *ref, UniCharCount forkNameLength, const UniChar *forkName );
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.
The length of the Unicode name of the fork name.
A pointer to the Unicode name of the fork to delete.
A result code. See “File Manager Result Codes.” If the named fork does not exist, the function returns errFSForkNotFound
.
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.
Files.h
Deletes a file or an empty directory.
OSErr FSDeleteObject ( const FSRef *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.
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.
Files.h
Releases the memory associated with a volume operation.
OSStatus FSDisposeVolumeOperation ( FSVolumeOperation volumeOp );
The FSVolumeOperation
to release.
A result code. See “File Manager Result Codes.” This function will return paramErr
if the FSVolumeOperation
is in use.
Files.h
Asynchronously ejects a volume.
OSStatus FSEjectVolumeAsync ( FSVolumeRefNum vRefNum, OptionBits flags, FSVolumeOperation volumeOp, void *clientData, FSVolumeEjectUPP callback, CFRunLoopRef runloop, CFStringRef runloopMode );
The volume reference number of the volume to eject.
Options for future use.
An FSVolumeOperation
returned by FSCreateVolumeOperation
.
A pointer to client data associated with the operation. This parameter can be NULL
.
The function to call when eject is complete.
The runloop to run on.
The mode for the runloop.
A result code. See “File Manager Result Codes.”
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
.
Files.h
Ejects a volume.
OSStatus FSEjectVolumeSync ( FSVolumeRefNum vRefNum, OptionBits flags, pid_t *dissenter );
The volume reference number of the volume to eject.
Options for future use.
On return, a pointer to the pid of the process which denied the unmount if the eject is denied.
A result code. See “File Manager Result Codes.”
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.
Files.h
Swaps the contents of two files.
OSErr FSExchangeObjects ( const FSRef *ref, const FSRef *destRef );
A pointer to an FSRef
for the first file. See FSRef
for a description of the FSRef
data type.
A pointer to an FSRef
for the second file.
A result code. See “File Manager Result Codes.”
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).
Files.h
Cancels an asynchronous file operation.
OSStatus FSFileOperationCancel ( FSFileOperationRef fileOp );
The file operation to cancel.
A result code. See “File Manager Result Codes.”
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
.
Files.h
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 );
The file operation to access.
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).
A pointer to a file operation stage variable. On output, the variable contains the current stage of the file operation.
A pointer to an error status variable. On output, the variable contains the current error status of the file operation.
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.
A pointer to a generic pointer. On output, the generic pointer refers to user-defined data associated with this file operation.
A result code. See “File Manager Result Codes.”
Files.h
Creates an object that represents an asynchronous file operation.
FSFileOperationRef FSFileOperationCreate ( CFAllocatorRef alloc );
The allocator to use. Pass NULL
for the default allocator.
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
.
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
.
Files.h
Returns the Core Foundation type identifier for the FSFileOperation opaque type.
CFTypeID FSFileOperationGetTypeID ( void );
The type identifier for the FSFileOperation opaque type. For information about this type, see FSFileOperationRef
.
Files.h
Schedules an asynchronous file operation with the specified run loop and mode.
OSStatus FSFileOperationScheduleWithRunLoop ( FSFileOperationRef fileOp, CFRunLoopRef runLoop, CFStringRef runLoopMode );
The file operation to schedule.
The run loop in which to schedule the operation. For information about Core Foundation run loops, see Run Loops.
The run loop mode in which to schedule the operation. In most cases, you may specify kCFRunLoopCommonModes
.
A result code. See “File Manager Result Codes.”
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.
Files.h
Unschedules an asynchronous file operation from the specified run loop and mode.
OSStatus FSFileOperationUnscheduleFromRunLoop ( FSFileOperationRef fileOp, CFRunLoopRef runLoop, CFStringRef runLoopMode );
The file operation to unschedule.
The run loop on which to unschedule the operation.
The run loop mode in which to unschedule the operation.
A result code. See “File Manager Result Codes.”
Files.h
Causes all data written to an open fork to be written to disk.
OSErr FSFlushFork ( FSIORefNum forkRefNum );
The reference number of the fork to flush.
A result code. See “File Manager Result Codes.”
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.
Files.h
For the specified volume, writes all open and modified files in the current process to permanent storage.
OSStatus FSFlushVolume ( FSVolumeRefNum vRefNum );
The volume reference number of the volume to flush.
A result code. See “File Manager Result Codes.”
Files.h
Returns the current status of an asynchronous eject operation.
OSStatus FSGetAsyncEjectStatus ( FSVolumeOperation volumeOp, FSEjectStatus *status, OSStatus *volumeOpStatus, FSVolumeRefNum *volumeRefNum, pid_t *dissenter, void **clientData );
The asynchronous volume operation to get status about.
On return, a pointer to the status of the operation.
If the status parameter is kAsyncEjectComplete
then this contains the result code (OSStatus
) for the operation on return.
On return, the volume reference number of the volume being ejected.
On return, a pointer to the pid of the process which denied the unmount if the eject is denied.
On return, a pointer to client data associated with the original FSMountServerVolumeAsync
operation.
A result code. See “File Manager Result Codes.” A return value of noErr
signifies that the status
parameter has been filled with valid information.
Files.h
Returns the current status of an asynchronous mount operation.
OSStatus FSGetAsyncMountStatus ( FSVolumeOperation volumeOp, FSMountStatus *status, OSStatus *volumeOpStatus, FSVolumeRefNum *mountedVolumeRefNum, void **clientData );
The asynchronous volume operation to get status about.
On return, a pointer to the status of the operation.
If the status is kAsyncMountComplete
then this parameter contains the result code for the operation on return.
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.
On return, a pointer to client data associated with the original FSMountServerVolumeAsync
operation.
A result code. See “File Manager Result Codes.”
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.
Files.h
Returns the current status of an asynchronous unmount operation.
OSStatus FSGetAsyncUnmountStatus ( FSVolumeOperation volumeOp, FSUnmountStatus *status, OSStatus *volumeOpStatus, FSVolumeRefNum *volumeRefNum, pid_t *dissenter, void **clientData );
The asynchronous volume operation to get status about.
On return, a pointer to the status of the operation.
If the status is kAsyncUnmountComplete
then this parameter contains a pointer to the result code (OSStatus
) for the operation on return.
On return, a pointer to the volume reference number of the volume being unmounted.
On return, a pointer to the pid of the process which denied the unmount if the unmount is denied.
On return, a pointer to client data associated with the original FSMountServerVolumeAsync
operation.
A result code. See “File Manager Result Codes.” A return value of noErr
signifies that the status parameter has been filled with valid information.
Files.h
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 );
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.
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.
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.
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.
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.
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.
A result code. See “File Manager Result Codes.”
Files.h
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 );
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.
The maximum number of items to return for this call.
On return, a pointer to the actual number of items found for this call.
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.
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.”
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.
A pointer to an array of FSRef
structures; one for each returned item. On input, this parameter should to point to an array of maximumObjects
FSRef
structures.
This parameter is optional; if you do not wish any FSRef
structures returned, pass NULL
here.
A pointer to an array of FSSpec
structures; one for each returned item. On input, this parameter should to point to an array of maximumObjects
FSSpec
structures.
This parameter is optional; if you do not wish any FSSpec
structures returned, pass NULL
here.
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 maximumObjects
HFSUniStr255
structures. Otherwise, set it to NULL
.
A result code. See “File Manager Result Codes.” When all of the iterator’s objects have been returned, the call will return errFSNoMoreItems
.
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.
Files.h
Returns a Unicode string constant for the name of the data fork.
OSErr FSGetDataForkName ( HFSUniStr255 *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.
A result code. See “File Manager Result Codes.”
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.
Files.h
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 );
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.
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.
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.
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
.
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.
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.
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.
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.
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.
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.
Files.h
Returns the current position of an open fork.
OSErr FSGetForkPosition ( FSIORefNum forkRefNum, SInt64 *position );
The reference number of a fork previously opened by the FSOpenFork
function or one of its corresponding parameter block calls, PBOpenForkSync
and PBOpenForkAsync
.
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).
A result code. See “File Manager Result Codes.”
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.
Files.h
Returns the size of an open fork.
OSErr FSGetForkSize ( FSIORefNum forkRefNum, SInt64 *forkSize );
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
.
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.
A result code. See “File Manager Result Codes.”
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.
Files.h
Returns a Unicode string constant for the name of the resource fork.
OSErr FSGetResourceForkName ( HFSUniStr255 *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.
A result code. See “File Manager Result Codes.”
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.
Files.h
Returns information about a volume.
OSErr FSGetVolumeInfo ( FSVolumeRefNum volume, ItemCount volumeIndex, FSVolumeRefNum *actualVolume, FSVolumeInfoBitmap whichInfo, FSVolumeInfo *info, HFSUniStr255 *volumeName, FSRef *rootDirectory );
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.
The index of the desired volume, or 0 to use the volume reference number in the volume
parameter.
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
.
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.
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.
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.
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.
A result code. See “File Manager Result Codes.”
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
.
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.
Files.h
Retrieves the mounting information associated with the specified volume.
OSStatus FSGetVolumeMountInfo ( FSVolumeRefNum volume, BytePtr buffer, ByteCount bufferSize, ByteCount *actualSize );
Files.h
Determines the size of the mounting information associated with the specified volume.
OSStatus FSGetVolumeMountInfoSize ( FSVolumeRefNum volume, ByteCount *size );
Files.h
Retrieves information about the characteristics of a volume.
OSStatus FSGetVolumeParms ( FSVolumeRefNum volume, GetVolParmsInfoBuffer *buffer, ByteCount bufferSize );
Files.h
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 );
A pointer to an FSRef
specifying the file or directory to iterate. See FSRef
for a description of the FSRef
data type.
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.
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.
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.
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.
A result code. See “File Manager Result Codes.”
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.
Files.h
Locks a range of bytes of the specified fork.
OSStatus FSLockRange ( FSIORefNum forkRefNum, UInt16 positionMode, SInt64 positionOffset, UInt64 requestCount, UInt64 *rangeStart );
Files.h
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 );
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.
The length of the file or directory 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
.
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.
On return, if the function returns a result of noErr,
a pointer to the new FSRef
.
A result code. See “File Manager Result Codes.”
Files.h
Mounts a volume asynchronously.
OSStatus FSMountLocalVolumeAsync ( CFStringRef diskID, CFURLRef mountDir, FSVolumeOperation volumeOp, void *clientData, OptionBits flags, FSVolumeMountUPP callback, CFRunLoopRef runloop, CFStringRef runloopMode );
The disk to mount.
Pass in NULL
; currently only NULL
is supported.
An FSVolumeOperation
returned by FSCreateVolumeOperation
A pointer to client data associated with the operation. This parameter can be NULL
.
Options for future use.
The function to call when mount is complete. This parameter can be NULL
.
The runloop to run on.
The mode for the runloop.
A result code. See “File Manager Result Codes.”
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.
Files.h
Mounts a volume.
OSStatus FSMountLocalVolumeSync ( CFStringRef diskID, CFURLRef mountDir, FSVolumeRefNum *mountedVolumeRefNum, OptionBits flags );
The disk to mount.
Pass in NULL
; currently only NULL
is supported.
On return, a pointer to the volume reference number of the newly mounted volume.
Options for future use.
A result code. See “File Manager Result Codes.”
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.
Files.h
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 );
The server to mount.
The directory to mount the server to. If this parameter is NULL
, the default location is used.
A string to pass as the user for authentication. This parameter can be NULL
.
A string to pass as the password for authenticated log in. This parameter can be NULL
.
An FSVolumeOperation
returned by the FSCreateVolumeOperation
function.
A pointer to client data associated with the operation. This parameter can be NULL
.
Options for future use.
A function to call when the mount is complete. This parameter can be NULL
.
The runloop to run on.
The mode for the runloop.
A result code. See “File Manager Result Codes.”
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.
Files.h
Mounts a server volume.
OSStatus FSMountServerVolumeSync ( CFURLRef url, CFURLRef mountDir, CFStringRef user, CFStringRef password, FSVolumeRefNum *mountedVolumeRefNum, OptionBits flags );
The server to mount.
The directory to mount the server to. If this parameter is NULL
, the default location is used.
A string to pass as the user for authentication.
A string to pass as the password for authenticated log in.
On return, a pointer to the volume reference number of the newly mounted volume.
Options for future use.
A result code. See “File Manager Result Codes.”
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.
Files.h
Moves a file or directory into a different directory.
OSErr FSMoveObject ( const FSRef *ref, const FSRef *destDirectory, FSRef *newRef );
A pointer to an FSRef
specifying the file or directory to move. See FSRef
for a description of the FSRef
data type.
A pointer to an FSRef
specifying the directory into which the file or directory indicated by the ref
parameter will be moved.
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
.
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.
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.
Files.h
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 );
The file operation object you created for this move operation.
A pointer to the source object to move. The object can be a file or a directory.
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.
The name for the new object in the destination directory. Pass NULL
to use the name of the source object.
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.
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.
The minimum time in seconds between callbacks within a single stage of an operation.
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.
A result code. See “File Manager Result Codes.”
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.
Files.h
Moves a source object to a destination directory.
OSStatus FSMoveObjectSync ( const FSRef *source, const FSRef *destDir, CFStringRef destName, FSRef *target, OptionBits options );
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.
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.
The name for the new object in the destination directory. Pass NULL
to use the name of the source object.
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.
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.
A result code. See “File Manager Result Codes.”
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.
Files.h
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 );
The file operation object you created for this move operation. For more information, see the function FSFileOperationCreate
.
A pointer to the source object to move. The object can be a file or a directory.
One or more file operation option flags. See “File Operation Options.”
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.
The minimum time in seconds between callbacks within a single stage of an operation.
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.
A result code. See “File Manager Result Codes.”
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.
Files.h
Moves a source object to the Trash.
OSStatus FSMoveObjectToTrashSync ( const FSRef *source, FSRef *target, OptionBits options );
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.
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.
One or more file operation option flags. See “File Operation Options.”
A result code. See “File Manager Result Codes.”
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.)
Files.h
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 );
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.
The length of the fork name in Unicode characters.
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.
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.”
On return, a pointer to the fork reference number for accessing the open fork.
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.
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.
Files.h
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 );
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.
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.
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.
A result code. See “File Manager Result Codes.”
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.
Files.h
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 );
The file operation object you created for this copy operation.
The UTF-8 pathname of the source object to copy. The object can be a file or a directory.
The UTF-8 pathname of the destination directory.
The name for the new object in the destination directory. Pass NULL
to use the name of the source object.
One or more file operation option flags. See “File Operation Options.”
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.
The minimum time in seconds between callbacks within a single stage of an operation.
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.
A result code. See “File Manager Result Codes.”
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.
Files.h
Copies a source object to a destination directory using pathnames.
OSStatus FSPathCopyObjectSync ( const char *sourcePath, const char *destDirPath, CFStringRef destName, char **targetPath, OptionBits options );
The UTF-8 pathname of the source object to copy. The object can be a file or a directory.
The UTF-8 pathname of the destination directory.
The name for the new object in the destination directory. Pass NULL
to use the name of the source object.
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.
One or more file operation option flags. See “File Operation Options.”
A result code. See “File Manager Result Codes.”
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 FSPathCopyObjectAsync
instead.
Files.h
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 );
The file operation to access.
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.
A pointer to a file operation stage variable. On output, the variable contains the current stage of the file operation.
A pointer to an error status variable. On output, the variable contains the current error status of the file operation.
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.
A pointer to a generic pointer. On output, the generic pointer refers to user-defined data associated with this file operation.
A result code. See “File Manager Result Codes.”
Files.h
Converts a POSIX-style pathname into an FSRef
structure.
OSStatus FSPathMakeRef ( const UInt8 *path, FSRef *ref, Boolean *isDirectory );
A UTF-8 C string that contains the pathname to convert.
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.
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
.
A result code. See “File Manager Result Codes.”
Files.h
Converts a POSIX-style pathname into an FSRef
structure with options.
OSStatus FSPathMakeRefWithOptions ( const UInt8 *path, OptionBits options, FSRef *ref, Boolean *isDirectory );
A UTF-8 C string that contains the pathname to convert.
One or more conversion flags. See “Path Conversion Options.”
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.
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
.
A result code. See “File Manager Result Codes.”
Files.h
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 );
The file operation object you created for this move operation.
The UTF-8 pathname of the source object to move. The object can be a file or a directory.
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.
The name for the new object in the destination directory. Pass NULL
to use the name of the source object.
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.
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.
The minimum time in seconds between callbacks within a single stage of an operation.
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.
A result code. See “File Manager Result Codes.”
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.
Files.h
Moves a source object to a destination directory using pathnames.
OSStatus FSPathMoveObjectSync ( const char *sourcePath, const char *destDirPath, CFStringRef destName, char **targetPath, OptionBits options );
The UTF-8 pathname of the source object to move. The object can be a file or a directory.
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.
The name for the new object in the destination directory. Pass NULL
to use the name of the source object.
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.
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.
A result code. See “File Manager Result Codes.”
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.
Files.h
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 );
The file operation object you created for this move operation. For more information, see the function FSFileOperationCreate
.
The UTF-8 pathname of the source object to move. The object can be a file or a directory.
One or more file operation option flags. See “File Operation Options.”
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.
The minimum time in seconds between callbacks within a single stage of an operation.
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.
A result code. See “File Manager Result Codes.”
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.)
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.
Files.h
Moves a source object, specified using a pathname, to the Trash.
OSStatus FSPathMoveObjectToTrashSync ( const char *sourcePath, char **targetPath, OptionBits options );
The UTF-8 pathname of the source object to move. The object can be a file or a directory.
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.
One or more file operation option flags. See “File Operation Options.”
A result code. See “File Manager Result Codes.”
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.)
Files.h
Reads data from an open fork.
OSErr FSReadFork ( FSIORefNum forkRefNum, UInt16 positionMode, SInt64 positionOffset, ByteCount requestCount, void *buffer, ByteCount *actualCount );
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
.
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.
The offset from the base location for the start of the read.
The number of bytes to read.
A pointer to the buffer where the data will be returned.
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
.
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.
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.
Files.h
Converts an FSRef
structure into a POSIX-style pathname.
OSStatus FSRefMakePath ( const FSRef *ref, UInt8 *path, UInt32 maxPathSize );
A pointer to the FSRef
structure to convert.
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.
The maximum number of bytes to copy into the buffer.
A result code. See “File Manager Result Codes.”
Files.h
Renames a file or folder.
OSErr FSRenameUnicode ( const FSRef *ref, UniCharCount nameLength, const UniChar *name, TextEncoding textEncodingHint, FSRef *newRef );
A pointer to an FSRef
for the file or directory to rename. See FSRef
for a description of the FSRef
data type.
The length of the new name in Unicode characters.
A pointer to the new Unicode name of the file or directory.
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.
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
.
A result code. See “File Manager Result Codes.”
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
.
Files.h
Sets catalog information about a file or directory.
OSErr FSSetCatalogInfo ( const FSRef *ref, FSCatalogInfoBitmap whichInfo, const FSCatalogInfo *catalogInfo );
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.
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.
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
A result code. See “File Manager Result Codes.”
Files.h
Sets the current position of an open fork.
OSErr FSSetForkPosition ( FSIORefNum forkRefNum, UInt16 positionMode, SInt64 positionOffset );
The reference number of a fork previously opened by the FSOpenFork
, PBOpenForkSync
, or PBOpenForkAsync
function.
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.
The offset of the new position from the base location specified in the positionMode
parameter.
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.
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.
Files.h
Changes the size of an open fork.
OSErr FSSetForkSize ( FSIORefNum forkRefNum, UInt16 positionMode, SInt64 positionOffset );
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
.
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.
The offset of the new size from the base location specified in the positionMode
parameter.
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.
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.
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.
Files.h
Sets information about a volume.
OSErr FSSetVolumeInfo ( FSVolumeRefNum volume, FSVolumeInfoBitmap whichInfo, const FSVolumeInfo *info );
The volume reference number of the volume whose information is to be changed. See FSVolumeRefNum
for a description of the FSVolumeRefNum
data type.
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.
A pointer to the new volume information. See FSVolumeInfo
for a description of the FSVolumeInfo
data type.
A result code. See “File Manager Result Codes.”
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
.
Files.h
Unlocks a range of bytes of the specified fork.
OSStatus FSUnlockRange ( FSIORefNum forkRefNum, UInt16 positionMode, SInt64 positionOffset, UInt64 requestCount, UInt64 *rangeStart );
Files.h
Unmounts a volume asynchronously.
OSStatus FSUnmountVolumeAsync ( FSVolumeRefNum vRefNum, OptionBits flags, FSVolumeOperation volumeOp, void *clientData, FSVolumeUnmountUPP callback, CFRunLoopRef runloop, CFStringRef runloopMode );
The volume reference number of the volume to unmount.
Options for future use.
An FSVolumeOperation
returned by the FSCreateVolumeOperation
function.
A pointer to client data associated with the operation.
The function to call when the unmount is complete.
The runloop to run on.
The mode for the runloop.
A result code. See “File Manager Result Codes.”
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.
Files.h
Unmounts a volume.
OSStatus FSUnmountVolumeSync ( FSVolumeRefNum vRefNum, OptionBits flags, pid_t *dissenter );
The volume reference number of the volume to unmount.
Options for future use.
On return, a pointer to the pid of the process which denied the unmount if the unmount is denied.
A result code. See “File Manager Result Codes.”
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.
Files.h
Mounts a volume using the specified mounting information.
OSStatus FSVolumeMount ( BytePtr buffer, FSVolumeRefNum *mountedVolume );
Files.h
Writes data to an open fork.
OSErr FSWriteFork ( FSIORefNum forkRefNum, UInt16 positionMode, SInt64 positionOffset, ByteCount requestCount, const void *buffer, ByteCount *actualCount );
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
.
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.
The offset from the base location for the start of the write.
The number of bytes to write.
A pointer to a buffer containing the data to write.
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
.
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.
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.
Files.h
Calls your directory change callback function.
void InvokeFNSubscriptionUPP ( FNMessage message, OptionBits flags, void *refcon, FNSubscriptionRef subscription, FNSubscriptionUPP userUPP );
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
.
Files.h
Calls your volume ejection callback function.
void InvokeFSVolumeEjectUPP ( FSVolumeOperation volumeOp, void *clientData, OSStatus err, FSVolumeRefNum volumeRefNum, pid_t dissenter, FSVolumeEjectUPP userUPP );
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
.
Files.h
Calls your volume mount callback function.
void InvokeFSVolumeMountUPP ( FSVolumeOperation volumeOp, void *clientData, OSStatus err, FSVolumeRefNum mountedVolumeRefNum, FSVolumeMountUPP userUPP );
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
.
Files.h
Calls your volume unmount callback function.
void InvokeFSVolumeUnmountUPP ( FSVolumeOperation volumeOp, void *clientData, OSStatus err, FSVolumeRefNum volumeRefNum, pid_t dissenter, FSVolumeUnmountUPP userUPP );
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
.
Files.h
Calls your I/O completion callback function.
void InvokeIOCompletionUPP ( ParmBlkPtr paramBlock, IOCompletionUPP userUPP );
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
.
Files.h
Creates a new universal procedure pointer (UPP) to your directory change callback function.
FNSubscriptionUPP NewFNSubscriptionUPP ( FNSubscriptionProcPtr userRoutine );
A pointer to a directory change callback function. For more information, see FNSubscriptionProcPtr
.
A UPP to your directory change callback function.
Files.h
Creates a new universal procedure pointer (UPP) to your volume ejection callback function.
FSVolumeEjectUPP NewFSVolumeEjectUPP ( FSVolumeEjectProcPtr userRoutine );
A pointer to a volume ejection callback function. For more information, see FSVolumeEjectProcPtr
.
A UPP to your volume ejection callback function.
Files.h
Creates a new universal procedure pointer (UPP) to your volume mount callback function.
FSVolumeMountUPP NewFSVolumeMountUPP ( FSVolumeMountProcPtr userRoutine );
A pointer to a volume mount callback function. For more information, see FSVolumeEjectProcPtr
.
A UPP to your volume mount callback function.
Files.h
Creates a new universal procedure pointer (UPP) to your volume unmount callback function.
FSVolumeUnmountUPP NewFSVolumeUnmountUPP ( FSVolumeUnmountProcPtr userRoutine );
A pointer to a volume unmount callback function. For more information, see FSVolumeUnmountProcPtr
.
A UPP to your volume unmount callback function.
Files.h
Creates a new universal procedure pointer (UPP) to your I/O completion callback function.
IOCompletionUPP NewIOCompletionUPP ( IOCompletionProcPtr userRoutine );
A pointer to your I/O completion callback function. For more information, see IOCompletionProcPtr
.
A UPP to your I/O completion callback function.
Files.h
Allocates space on a volume to an open fork.
void PBAllocateForkAsync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
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
.
Files.h
Allocates space on a volume to an open fork.
OSErr PBAllocateForkSync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
A result code. See “File Manager Result Codes.”
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.
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
.
Files.h
Searches for objects traversed by a catalog iterator that match a given set of criteria.
void PBCatalogSearchAsync ( FSCatalogBulkParam *paramBlock );
A pointer to a catalog information parameter block. See FSCatalogBulkParam
for a description of the FSCatalogBulkParam
data type.
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.
Files.h
Searches for objects traversed by a catalog iterator that match a given set of criteria.
OSErr PBCatalogSearchSync ( FSCatalogBulkParam *paramBlock );
A pointer to a catalog information parameter block. See FSCatalogBulkParam
for a description of the FSCatalogBulkParam
data type.
A result code. See “File Manager Result Codes.” When the entire volume has been searched, errFSNoMoreItems
is returned.
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.
Files.h
Closes an open fork.
void PBCloseForkAsync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
.
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.
Files.h
Closes an open fork.
OSErr PBCloseForkSync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
.
A result code. See “File Manager Result Codes.”
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.
Files.h
Closes a catalog iterator.
void PBCloseIteratorAsync ( FSCatalogBulkParam *paramBlock );
A pointer to a catalog information parameter block. See FSCatalogBulkParam
for a description of the FSCatalogBulkParam
data type.
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.
Files.h
Closes a catalog iterator.
OSErr PBCloseIteratorSync ( FSCatalogBulkParam *paramBlock );
A pointer to a catalog information parameter block. See FSCatalogBulkParam
for a description of the FSCatalogBulkParam
data type.
A result code. See “File Manager Result Codes.”
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.
Files.h
Determines whether two FSRef
structures refer to the same file or directory.
void PBCompareFSRefsAsync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
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.
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.
Files.h
Determines whether two FSRef
structures refer to the same file or directory.
OSErr PBCompareFSRefsSync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
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
.
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.
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.
Files.h
Creates a new directory (folder) with a Unicode name.
void PBCreateDirectoryUnicodeAsync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
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.
Files.h
Creates a new directory (folder) with a Unicode name.
OSErr PBCreateDirectoryUnicodeSync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
A result code. See “File Manager Result Codes.”
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.
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.
Files.h
Creates a new file with a Unicode name.
void PBCreateFileUnicodeAsync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
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.
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.
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.
Files.h
Creates a new file with a Unicode name.
OSErr PBCreateFileUnicodeSync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
A result code. See “File Manager Result Codes.”
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” 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, set this field to NULL
on input.
spec
On output, a pointer to the FSSpec
for the new file. If you do not want the FSSpec
returned, set this field to NULL
on input.
You may optionally set catalog information for the new 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.
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.
If the PBCreateFileUnicodeSync
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.
Files.h
Creates a named fork for a file or directory.
void PBCreateForkAsync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
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. If the named fork already exists, the function returns errFSForkExists
. If the fork name is syntactically invalid or otherwise unsupported for the given volume, PBCreateForkAsync
returns errFSBadForkName
or errFSNameTooLong
.
ref
On input, a pointer to an FSRef
specifying the file or directory.
forkNameLength
On input, the length of the Unicode name of the new fork.
forkName
On input, a pointer to the Unicode name of the fork.
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.
Files.h
Creates a named fork for a file or directory.
OSErr PBCreateForkSync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
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, PBCreateForkSync
returns errFSBadForkName
or errFSNameTooLong
.
The relevant fields of the parameter block are:
ioResult
On output, the result code of the function. If the named fork already exists, the function returns errFSForkExists
. If the fork name is syntactically invalid or otherwise unsupported for the given volume, PBCreateForkAsync
returns errFSBadForkName
or errFSNameTooLong
.
ref
On input, a pointer to an FSRef
specifying the file or directory.
forkNameLength
On input, the length of the Unicode name of the new fork.
forkName
On input, a pointer to the Unicode name of the fork.
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.
Files.h
Deletes a named fork of a file or directory.
void PBDeleteForkAsync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
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. If the named fork does not exist, the function returns errFSForkNotFound
.
ref
On input, a pointer to an FSRef
for the file or directory from which to delete the fork.
forkNameLength
On input, the length of the fork’s Unicode name.
forkName
On input, a pointer to the Unicode name of the fork to delete.
The permissions
, forkRefNum
, positionMode
, and positionOffset
fields of the parameter block may be modified by this call.
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.
Files.h
Deletes a named fork from a file or directory.
OSErr PBDeleteForkSync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
A result code. See “File Manager Result Codes.” If the named fork does not exist, the function returns errFSForkNotFound
.
The relevant fields of the parameter block are:
ref
On input, a pointer to an FSRef
for the file or directory from which to delete the fork.
forkNameLength
On input, the length of the fork’s Unicode name.
forkName
On input, a pointer to the Unicode name of the fork to delete.
The permissions
, forkRefNum
, positionMode
, and positionOffset
fields of the parameter block may be modified by this call.
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.
Files.h
Deletes a file or an empty directory.
void PBDeleteObjectAsync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
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
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.
ref
On input, a pointer to the FSRef
for 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).
Files.h
Deletes a file or an empty directory.
OSErr PBDeleteObjectSync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
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.
The relevant field of the parameter block is:
ref
On input, a pointer to the FSRef
for 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).
Files.h
Swaps the contents of two files.
void PBExchangeObjectsAsync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
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.
ref
On input, a pointer to an FSRef
for the first file.
parentRef
On input, a pointer to an FSRef
for the second file.
The PBExchangeObjectsAsync
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).
Files.h
Swaps the contents of two files.
OSErr PBExchangeObjectsSync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
A result code. See “File Manager Result Codes.”
The relevant fields of the parameter block are:
ref
On input, a pointer to an FSRef
for the first file.
parentRef
On input, a pointer to an FSRef
for the second file.
The PBExchangeObjectsSync
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).
Files.h
Causes all data written to an open fork to be written to disk.
void PBFlushForkAsync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for more information on the FSForkIOParam
data type.
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 flush.
The PBFlushForkAsync
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 PBFlushForkAsync
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 PBFlushForkAsync
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.
Files.h
Causes all data written to an open fork to be written to disk.
OSErr PBFlushForkSync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for more information on the FSForkIOParam
data type.
A result code. See “File Manager Result Codes.”
The relevant field of the parameter block is:
forkRefNum
On input, the reference number of the fork to flush.
The PBFlushForkSync
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 PBFlushForkSync
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 PBFlushForkSync
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.
Files.h
For the specified volume, writes all open and modified files in the current process to permanent storage.
OSStatus PBFlushVolumeAsync ( FSRefParamPtr paramBlock );
A parameter block containing the volume reference number of the volume to flush. See FSRefParam
.
A result code. See “File Manager Result Codes.”
Files.h
For the specified volume, writes all open and modified files in the current process to permanent storage.
OSStatus PBFlushVolumeSync ( FSRefParamPtr paramBlock );
A parameter block containing the volume reference number of the volume to flush. See FSRefParam
.
A result code. See “File Manager Result Codes.”
Files.h
Duplicates a file and optionally renames it.
OSStatus PBFSCopyFileAsync ( FSRefParamPtr paramBlock );
Files.h
Duplicates a file and optionally renames it.
OSStatus PBFSCopyFileSync ( FSRefParamPtr paramBlock );
Files.h
Returns catalog information about a file or directory. You can use this function to map from an FSRef
to an FSSpec
.
void PBGetCatalogInfoAsync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
fro s description of the FSRefParam
data type.
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.
ref
On input, a pointer to an FSRef
specifying the file or directory for which to retrieve information.
whichInfo
On input, 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 field.
catInfo
On output, a pointer to an FSCatalogInfo
structure containing the information about the file or directory. Only the information specified in the whichInfo
field is returned. If you don’t want any catalog information, pass NULL
here.
spec
On output, a pointer to the FSSpec
for the file or directory. This output is optional; if you do not wish the FSSpec
returned, pass NULL
here.
parentRef
On output, a pointer to the FSRef
for the object's parent directory. This output is optional; if you do not wish the parent directory returned, pass NULL
here. If the object specified in the ref
field is a volume’s root directory, then the FSRef
returned in this field will not be a valid FSRef
, since the root directory has no parent object.
outName
On output, a pointer to the Unicode name of the file or directory. On input, pass a pointer to an HFSUniStr255
structure if you wish the name returned; otherwise, pass NULL
.
Files.h
Returns information about one or more objects from a catalog iterator. This function can return information about multiple objects in a single call.
void PBGetCatalogInfoBulkAsync ( FSCatalogBulkParam *paramBlock );
A pointer to a catalog information parameter block. See FSCatalogBulkParam
for a description of the FSCatalogBulkParam
data type.
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. When all of the iterator’s objects have been returned, the call will return errFSNoMoreItems
.
iterator
On input, 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.
maximumItems
On input, the maximum number of items to return for this call.
actualItems
On output, the actual number of items found for this call.
containerChanged
On output, a value indicating whether or not the container’s contents have changed since the previous PBGetCatalogInfoBulkAsync
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.
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. For a description of the bits in this field, see “Catalog Information Bitmap Constants.”
catalogInfo
On output, a pointer to an array of catalog information structures; one for each returned 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. See FSCatalogInfo
for a description of the FSCatalogInfo
data type.
refs
On input, a pointer to an array of maximumItems
FSRef
structures. On output, an FSRef
is filled out for each returned item. This field is optional; if you do not wish any FSRef
structures returned, pass NULL
here.
names
On output, a pointer to an array of names; one for each returned item. If you want the Unicode name for each item found, set this field to point to an array of maximumItems
HFSUniStr255
structures. Otherwise, set it to NULL
.
specs
On input, a pointer to an array of maximumItems
FSSpec
structures. On output, an FSSpec
structure is filled out for each returned item. This field is optional; if you do not wish any FSSpec
structures returned, pass NULL
here.
The PBGetCatalogInfoBulkAsync
call may complete and return noErr
with fewer than maximumItems
items returned. This may be due to various reasons related to the internal implementation. In this case, you may continue to make PBGetCatalogInfoBulkSync
calls using the same iterator.
Before calling this function, you should determine whether it is available, by calling the Gestalt
function.
Files.h
Returns information about one or more objects from a catalog iterator. This function can return information about multiple objects in a single call.
OSErr PBGetCatalogInfoBulkSync ( FSCatalogBulkParam *paramBlock );
A pointer to a catalog information parameter block. See FSCatalogBulkParam
for a description of the FSCatalogBulkParam
data type.
A result code. See “File Manager Result Codes.” When all of the iterator’s objects have been returned, the call will return errFSNoMoreItems
.
The relevant fields of the parameter block are:
iterator
On input, 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.
maximumItems
On input, the maximum number of items to return for this call.
actualItems
On output, the actual number of items found for this call.
containerChanged
On output, a value indicating whether or not the container’s contents have changed since the previous PBGetCatalogInfoBulkSync
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.
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. For a description of the bits in this field, see “Catalog Information Bitmap Constants.”
catalogInfo
On output, a pointer to an array of catalog information structures; one for each returned 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. See FSCatalogInfo
for a description of the FSCatalogInfo
data type.
refs
On input, a pointer to an array of maximumItems
HFSUniStr255
structures. On output, an FSRef
is filled out for each returned item. This field is optional; if you do not wish any FSRef
structures returned, pass NULL
here.
names
On output, a pointer to an array of names; one for each returned item. If you want the Unicode name for each item found, set this field to point to an array of maximumItems
HFSUniStr255
structures. Otherwise, set it to NULL
.
specs
On input, a pointer to an array of maximumItems
FSSpec
structures. On output, an FSSpec
structure is filled out for each returned item. This field is optional; if you do not wish any FSSpec
structures returned, pass NULL
here.
The PBGetCatalogInfoBulkSync
call may complete and return noErr
with fewer than maximumItems
items returned. This may be due to various reasons related to the internal implementation. In this case, you may continue to make PBGetCatalogInfoBulkSync
calls using the same iterator.
Before calling this function, you should determine whether it is available, by calling the Gestalt
function.
Files.h
Returns catalog information about a file or directory. You can use this function to map from an FSRef
to an FSSpec
.
OSErr PBGetCatalogInfoSync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
A result code. See “File Manager Result Codes.”
The relevant fields of the parameter block are:
ref
On input, a pointer to an FSRef
specifying the file or directory for which to retrieve information.
whichInfo
On input, 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 field.
catInfo
On output, a pointer to an FSCatalogInfo
structure containing the information about the file or directory. Only the information specified in the whichInfo
field is returned. If you don’t want any catalog information, pass NULL
here.
spec
On output, a pointer to the FSSpec
for the file or directory. This output is optional; if you do not wish the FSSpec
returned, pass NULL
here.
parentRef
On output, a pointer to the FSRef
for the object's parent directory. This output is optional; if you do not wish the parent directory returned, pass NULL
here. If the object specified in the ref
field is a volume’s root directory, then the FSRef
returned in this field will not be a valid FSRef
, since the root directory has no parent object.
outName
On output, a pointer to the Unicode name of the file or directory. On input, pass a pointer to an HFSUniStr255
structure if you wish the name returned; otherwise, pass NULL
.
Files.h
Returns information about a specified open fork, or about all open forks.
void PBGetForkCBInfoAsync ( FSForkCBInfoParam *paramBlock );
A pointer to a fork control block parameter block. See FSForkCBInfoParam
for a description of the FSForkCBInfoParam
data type.
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.
desiredRefNum
On input, if you want information on a specific fork, set this field to that fork’s reference number. If you pass a non-zero value in this parameter, the function attempts to get information on the fork specified by that reference number the field is unchanged on output. Pass zero in this field to iterate over all open forks; on output, this field contains the fork's reference number. You can limit this iteration to a specific volume with the volumeRefNum
field.
volumeRefNum
On input, 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 field. To iterate over all open forks on all volumes, set this field to the constant kFSInvalidVolumeRefNum
. This field 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
On input, an iterator. If the desiredRefNum
parameter is 0, the iterator maintains state between calls to PBGetForkCBInfoAsync
. Set the iterator
field to 0 before you begin iterating, on the first call to PBGetForkCBInfoAsync
. On return, the iterator will be updated; pass this updated iterator in the iterator
field of the next call to PBGetForkCBInfoAsync
to continue iterating.
actualRefNum
On output, the actual reference number of the open fork that was found.
ref
On output, a pointer to the FSRef
for the file or directory that contains the fork. This information is optional; if you do not wish to the FSRef
, set ref
to NULL
.
forkInfo
On output, a pointer to an FSForkInfo
structure containing information about the open fork. This information is optional; if you do not wish it returned, set forkInfo
to NULL
.
forkName
On output, a pointer to the name of the fork. This field is optional; if you do not wish the name returned, set forkName
to NULL
. See HFSUniStr255
for a description of the HFSUniStr255
data type.
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.
Returning the fork information in the forkInfo
field generally does not require a disk access; returning the information in the ref
or forkName
fields may cause disk access for some volume formats.
Files.h
Returns information about a specified open fork, or about all open forks.
OSErr PBGetForkCBInfoSync ( FSForkCBInfoParam *paramBlock );
A pointer to a fork control block parameter block. See FSForkCBInfoParam
for a description of the FSForkCBInfoParam
data type.
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.
The relevant fields of the parameter block are:
desiredRefNum
On input, if you want information on a specific fork, set this field to that fork’s reference number. If you pass a non-zero value in this parameter, the function attempts to get information on the fork specified by that reference number the field is unchanged on output. Pass zero in this field to iterate over all open forks; on output, this field contains the fork's reference number. You can limit this iteration to a specific volume with the volumeRefNum
field.
volumeRefNum
On input, 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 field. To iterate over all open forks on all volumes, set this field to the constant kFSInvalidVolumeRefNum
. This field 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
On input, an iterator. If the desiredRefNum
parameter is 0, the iterator maintains state between calls to PBGetForkCBInfoSync
. Set the iterator
field to 0 before you begin iterating, on the first call to PBGetForkCBInfoSync
. On return, the iterator will be updated; pass this updated iterator in the iterator
field of the next call to PBGetForkCBInfoSync
to continue iterating.
actualRefNum
On output, the actual reference number of the open fork that was found.
ref
On output, a pointer to the FSRef
for the file or directory that contains the fork. This information is optional; if you do not wish to the FSRef
, set ref
to NULL
.
forkInfo
On output, a pointer to an FSForkInfo
structure containing information about the open fork. This information is optional; if you do not wish it returned, set forkInfo
to NULL
.
forkName
On output, a pointer to the name of the fork. This field is optional; if you do not wish the name returned, set forkName
to NULL
. See HFSUniStr255
for a description of the HFSUniStr255
data type.
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.
Returning the fork information in the forkInfo
field generally does not require a disk access; returning the information in the ref
or forkName
fields may cause disk access for some volume formats.
Files.h
Returns the current position of an open fork.
void PBGetForkPositionAsync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
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 a fork previously opened by the FSOpenFork
, PBOpenForkSync
, or PBOpenForkAsync
function.
positionOffset
On output, 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).
Before calling the PBGetForkPositionAsync
function, call the Gestalt
function with the gestaltFSAttr
selector to determine if PBGetForkPositionAsync
is available. If the function is available, but is not directly supported by a volume, the File Manager will automatically call PBGetFPosAsync
; 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.
Files.h
Returns the current position of an open fork.
OSErr PBGetForkPositionSync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
A result code. See “File Manager Result Codes.”
The relevant fields of the parameter block are:
forkRefNum
On input, the reference number of a fork previously opened by the FSOpenFork
, PBOpenForkSync
or PBOpenForkAsync
function.
positionOffset
On output, 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).
Before calling the PBGetForkPositionSync
function, call the Gestalt
function with the gestaltFSAttr
selector to determine if PBGetForkPositionSync
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.
Files.h
Returns the size of an open fork.
void PBGetForkSizeAsync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
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 this fork reference number with the FSOpenFork
function, or with one of the corresponding parameter block calls, PBOpenForkSync
and PBOpenForkAsync
.
positionOffset
On output, 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.
To determine whether the PBGetForkSizeAsync
function is present, call the Gestalt
function. If PBGetForkSizeAsync
is present, but is not directly supported by a volume, the File Manager will call PBGetEOFAsync
; 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.
Files.h
Returns the size of an open fork.
OSErr PBGetForkSizeSync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
A result code. See “File Manager Result Codes.”
The relevant fields of the parameter block are:
forkRefNum
On input, 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
.
positionOffset
On output, 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.
To determine whether the PBGetForkSizeSync
function is present, call the Gestalt
function. If PBGetForkSizeSync
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.
Files.h
Returns information about a volume.
void PBGetVolumeInfoAsync ( FSVolumeInfoParam *paramBlock );
A pointer to a volume information parameter block. See FSVolumeInfoParam
for a description of the FSVolumeInfoParam
data type.
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.
ioVRefNum
On input, the volume whose information is to be returned. For information on a particular volume, pass that volume’s reference number and set the volumeIndex
field to 0. To index through the list of mounted volumes, pass the constant kFSInvalidVolumeRefNum
.On output, the volume reference number of the volume. This is useful when indexing over all mounted volumes, when you have not specified a particular volume reference number on input.
volumeIndex
On input, the index of the desired volume, or 0 to use the volume reference number in the ioVRefNum
field.
whichInfo
On input, a bitmap specifying which volume information fields to return in the volumeInfo
field. If you don’t want the information about the volume returned in the volumeInfo
field, set whichInfo
to kFSVolInfoNone
. See “Volume Information Bitmap Constants” for a description of the bits in this field.
volumeInfo
On output, a pointer to the volume information, as described by the FSVolumeInfo
data type. If you don’t want this output, set this field to NULL
.
volumeName
On output, a pointer to the Unicode name of the volume. If you do not wish the name returned, pass NULL
. Otherwise, pass a pointer to an HFSUniStr255
structure.
ref
On output, a pointer to the FSRef
for the volume’s root directory. If you do not wish the root directory returned, pass NULL
.
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 ioVRefNum
field and set the volumeIndex
field to zero. To index through the list of mounted volumes, pass kFSInvalidVolumeRefNum
in the ioVRefNum
field and set volumeIndex
to the index, starting at 1 with the first call to PBGetVolumeInfoAsync
.
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
.
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 PBGetVolumeInfoAsync
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.
Files.h
Returns information about a volume.
OSErr PBGetVolumeInfoSync ( FSVolumeInfoParam *paramBlock );
A pointer to a volume information parameter block. See FSVolumeInfoParam
for a description of the FSVolumeInfoParam
data type.
A result code. See “File Manager Result Codes.”
The relevant fields of the parameter block are:
ioVRefNum
On input, the volume whose information is to be returned. For information on a particular volume, pass that volume’s reference number and set the volumeIndex
field to 0. To index through the list of mounted volumes, pass the constant kFSInvalidVolumeRefNum
.On output, the volume reference number of the volume. This is useful when indexing over all mounted volumes, when you have not specified a particular volume reference number on input.
volumeIndex
On input, the index of the desired volume, or 0 to use the volume reference number in the ioVRefNum
field.
whichInfo
On input, a bitmap specifying which volume information fields to return in the volumeInfo
field. If you don’t want the information about the volume returned in the volumeInfo
field, set whichInfo
to kFSVolInfoNone
. See “Volume Information Bitmap Constants” for a description of the bits in this field.
volumeInfo
On output, a pointer to the volume information, as described by the FSVolumeInfo
data type. If you don’t want this output, set this field to NULL
.
volumeName
On output, a pointer to the Unicode name of the volume. If you do not wish the name returned, pass NULL
. Otherwise, pass a pointer to an HFSUniStr255
structure.
ref
On output, a pointer to the FSRef
for the volume’s root directory. If you do not wish the root directory returned, pass NULL
.
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 ioVRefNum
field and set the volumeIndex
field to zero. To index through the list of mounted volumes, pass kFSInvalidVolumeRefNum
in the ioVRefNum
field and set volumeIndex
to the index, starting at 1 with the first call to PBGetVolumeInfoSync
.
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
.
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 PBGetVolumeInfoSync
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.
Files.h
Determines the name and size of every named fork belonging to a file or directory.
void PBIterateForksAsync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for more information on the FSForkIOParam
data type.
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.
ref
On input, a pointer to an FSRef
specifying the file or directory to iterate.
forkIterator
A pointer to a structure which maintains state between calls to PBIterateForksAsync
. Before the first call, set the initialize
field of this 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 structure pointed to in this field.
outForkName
On output, a pointer to the Unicode name of the fork.
positionOffset
On output, the logical size of the fork, in bytes.
allocationAmount
On output, the fork’s physical size (that is, the amount of space allocated on disk), in bytes.
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.
Files.h
Determines the name and size of every named fork belonging to a file or directory.
OSErr PBIterateForksSync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for more information on the FSForkIOParam
data type.
A result code. See “File Manager Result Codes.”
The relevant fields of the parameter block are:
ref
On input, a pointer to an FSRef
specifying the file or directory to iterate.
forkIterator
A pointer to a structure which maintains state between calls to PBIterateForksSync
. Before the first call, set the initialize
field of this 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 structure pointed to in this field.
outForkName
On output, a pointer to the Unicode name of the fork.
positionOffset
On output, the logical size of the fork, in bytes.
allocationAmount
On output, the fork’s physical size (that is, the amount of space allocated on disk), in bytes.
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.
Files.h
Constructs an FSRef
for a file or directory, given a parent directory and a Unicode name.
void PBMakeFSRefUnicodeAsync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
The relevant fields of the parameter block are:
ioCompletion
On input, a pointer to a completion function. For more information on completion routines, see IOCompletionProcPtr
.
ioResult
On output, the result code of the function.
ref
On input, 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
On input, the length of the file or directory name.
name
On input, 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 PBMakeFSRefUnicodeAsync
.
textEncodingHint
On input, 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 output, if the function returns a result of noErr
, a pointer to the new FSRef
Files.h
Constructs an FSRef
for a file or directory, given a parent directory and a Unicode name.
OSErr PBMakeFSRefUnicodeSync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
A result code. See “File Manager Result Codes.”
The relevant fields of the parameter block are:
ref
On input, 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
On input, the length of the file or directory name.
name
On input, 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 PBMakeFSRefUnicodeSync
.
textEncodingHint
On input, 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 output, if the function returns a result of noErr
, a pointer to the new FSRef
Files.h
Moves a file or directory into a different directory.
void PBMoveObjectAsync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
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. If the parentRef
field specifies a non-existent object, dirNFErr
is returned; if it refers to a file, then errFSNotAFolder
is returned. If the directory specified in parentRef
is on a different volume than the file or directory indicated by the ref
field, diffVolErr
is returned.
ref
On input, a pointer to an FSRef
specifying the file or directory to move.
On input, a pointer to an FSRef
specifying the directory into which the file or directory given in the ref
field will be moved.
newRef
On output, a pointer to the new FSRef
for the file or directory in its new location. This field is optional; if you do not wish the FSRef
returned, pass NULL
here.
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
field and use the FSRef
returned there to refer to the object after the move. The original FSRef
passed in the ref
field may or may not be usable after the move. The newRef
field may point to the same storage as the parentRef
or ref
fields.
Files.h
Moves a file or directory into a different directory.
OSErr PBMoveObjectSync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
A result code. See “File Manager Result Codes.” If the the parentRef
field of the parameter block specifies a non-existent object, dirNFErr
is returned; if it refers to a file, errFSNotAFolder
is returned. If the directory specified in the parentRef
field is on a different volume than the file or directory indicated in the ref
field, diffVolErr
is returned.
The relevant fields of the parameter block are:
ioResult
On output, the result code of the function. If the parentRef
field specifies a non-existent object, dirNFErr
is returned; if it refers to a file, then errFSNotAFolder
is returned. If the directory specified in parentRef
is on a different volume than the file or directory indicated by the ref
field, diffVolErr
is returned.
ref
On input, a pointer to an FSRef
specifying the file or directory to move.
parentRef
On input, a pointer to an FSRef
specifying the directory into which the file or directory given in the ref
field will be moved.
newRef
On output, a pointer to the new FSRef
for the file or directory in its new location. This field is optional; if you do not wish the FSRef
returned, pass NULL
here.
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
field and use the FSRef
returned there to refer to the object after the move. The original FSRef
passed in the ref
field may or may not be usable after the move. The newRef
field may point to the same storage as the parentRef
or ref
fields.
Files.h
Opens any fork of a file or directory for streaming access.
void PBOpenForkAsync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
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. On some file systems, PBOpenForkAsync
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.
ref
On input, a pointer to an FSRef
specifying the file or directory that owns the fork to open.
forkNameLength
On input, the length of the fork’s Unicode name.
forkName
On input, a pointer to the Unicode name of the fork to open. You can obtain the string constants for the data 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
On input, a constant indicating the type of access that 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 output, the fork reference number for accessing the open fork.
If you wish 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 PBOpenForkSync
function is present, call the Gestalt
function.
Files.h
Opens any fork of a file or directory for streaming access.
OSErr PBOpenForkSync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
A result code. See “File Manager Result Codes.” On some file systems, PBOpenForkSync
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.
The relevant fields of the parameter block are:
ref
On input, a pointer to an FSRef
specifying the file or directory that owns the fork to open.
forkNameLength
On input, the length of the fork’s Unicode name.
forkName
On input, a pointer to the Unicode name of the fork to open. You can obtain the string constants for the data 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
On input, a constant indicating the type of access that 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 output, the fork reference number for accessing the open fork.
If you wish 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 PBOpenForkSync
function is present, call the Gestalt
function.
Files.h
Creates a catalog iterator that can be used to iterate over the contents of a directory or volume.
void PBOpenIteratorAsync ( FSCatalogBulkParam *paramBlock );
A pointer to a catalog information parameter block. See FSCatalogBulkParam
for a description of the FSCatalogBulkParam
data type.
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 output, 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.
iteratorFlags
On input, 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 field. 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 field returns errFSBadIteratorFlags
. To determine whether subtree iterators are supported, check that the bSupportsSubtreeIterators
bit returned by PBHGetVolParmsAsync
is set.
container
On input, 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).
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.
Files.h
Creates a catalog iterator that can be used to iterate over the contents of a directory or volume.
OSErr PBOpenIteratorSync ( FSCatalogBulkParam *paramBlock );
A pointer to a catalog information parameter block. See FSCatalogBulkParam
for a description of the FSCatalogBulkParam
data type.
A result code. See “File Manager Result Codes.”
The relevant fields of the parameter block are:
iterator
On output, 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.
iteratorFlags
On input, 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 field. 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 field returns errFSBadIteratorFlags
. To determine whether subtree iterators are supported, check that the bSupportsSubtreeIterators
bit returned by PBHGetVolParmsSync
is set.
container
On input, 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).
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.
Files.h
Reads data from an open fork.
void PBReadForkAsync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
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. 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.
forkRefNum
On input, 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
On input, 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
On input, the offset from the base location for the start of the read.
requestCount
On input, the number of bytes to read. The value that you pass in this field should be greater than zero.
buffer
A pointer to the buffer where the data will be returned.
actualCount
On output, the number of bytes actually read. The value in this field should be equal to the value in the requestCount
field unless there was an error during the read operation.
PBReadForkAsync
reads data starting at the position specified by the positionMode
and positionOffset
fields. The function reads up to requestCount
bytes into the buffer pointed to by the buffer
field 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
field 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.
Files.h
Reads data from an open fork.
OSErr PBReadForkSync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
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.
The relevant fields of the parameter block are:
forkRefNum
On input, 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
On input, 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
On input, the offset from the base location for the start of the read.
requestCount
On input, the number of bytes to read. The value that you pass in this field should be greater than zero.
buffer
A pointer to the buffer where the data will be returned.
actualCount
On output, the number of bytes actually read. The value in this field should be equal to the value in the requestCount
field unless there was an error during the read operation.
PBReadForkSync
reads data starting at the position specified by the positionMode
and positionOffset
fields. The function reads up to requestCount
bytes into the buffer pointed to by the buffer
field 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
field 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.
Files.h
Renames a file or folder.
void PBRenameUnicodeAsync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
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.
ref
On input, a pointer to an FSRef
for the file or directory to rename.
nameLength
On input, the length of the new name in Unicode characters.
name
On input, a pointer to the new Unicode name of the file or directory.
textEncodingHint
On input, 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 output, a a pointer to the new FSRef
for the file or directory. This field is optional; if you do not wish the FSRef
returned, pass NULL
.
Because renaming an object may change its FSRef
, you should pass a non- NULL
pointer in the newRef
field 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
field may or may not be usable after the object is renamed. The FSRef
returned in the newRef
field may point to the same storage as the FSRef
passed in ref
.
Files.h
Renames a file or folder.
OSErr PBRenameUnicodeSync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
A result code. See “File Manager Result Codes.”
The relevant fields of the parameter block are:
ref
On input, a pointer to an FSRef
for the file or directory to rename.
nameLength
On input, the length of the new name in Unicode characters.
name
On input, a pointer to the new Unicode name of the file or directory.
textEncodingHint
On input, 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 output, a a pointer to the new FSRef
for the file or directory. This field is optional; if you do not wish the FSRef
returned, pass NULL
.
Because renaming an object may change its FSRef
, you should pass a non- NULL
pointer in the newRef
field 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
field may or may not be usable after the object is renamed. The FSRef
returned in the newRef
field may point to the same storage as the FSRef
passed in ref
.
Files.h
Sets the catalog information about a file or directory.
void PBSetCatalogInfoAsync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
for a description of the FSRefParam
data type.
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.
ref
On input, a pointer to an FSRef
specifying the file or directory whose information is to be changed.
whichInfo
On input, 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
field. See “Catalog Information Bitmap Constants” for a description of the bits in this field.
To set the user ID (UID) and group ID (GID), specify the kFSCatInfoSetOwnership
flag in this field. 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 PBSetCatalogInfoAsync
cannot set the user and group IDs, it returns an error.
catInfo
On input, a pointer to the FSCatalogInfo
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
Files.h
Sets the catalog information about a file or directory.
OSErr PBSetCatalogInfoSync ( FSRefParam *paramBlock );
A pointer to a file system reference parameter block. See FSRefParam
fro s description of the FSRefParam
data type.
A result code. See “File Manager Result Codes.”
The relevant fields of the parameter block are:
ref
On input, a pointer to an FSRef
specifying the file or directory whose information is to be changed.
whichInfo
On input, 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
field. See “Catalog Information Bitmap Constants” for a description of the bits in this field.
To set the user ID (UID) and group ID (GID), specify the kFSCatInfoSetOwnership
flag in this field. 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 PBSetCatalogInfoSync
cannot set the user and group IDs, it returns an error.
catInfo
On input, a pointer to the FSCatalogInfo
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
Files.h
Sets the current position of an open fork.
void PBSetForkPositionAsync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
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. 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.
forkRefNum
On input, the reference number of a fork previously opened by the FSOpenFork
, PBOpenForkSync
, or PBOpenForkAsync
function.
positionMode
On input, a constant specifying the base location within the fork for the new position. If this field is equal to fsAtMark
, then the positionOffset
field is ignored. See “Position Mode Constants” for a description of the constants you can use to specify the base location.
positionOffset
On input, the offset of the new position from the base location specified in the positionMode
field.
To determine if the PBSetForkPositionAsync
function is present, call the Gestalt
function with the gestaltFSAttr
selector. If the PBSetForkPositionAsync
function is present, but the volume does not directly support it, the File Manager will automatically call the PBSetFPosAsync
function. However, if the volume does not directly support the PBSetForkPositionAsync
function, you can only set the file position for the data and resource forks, and you cannot grow these files beyond 2GB.
Files.h
Sets the current position of an open fork.
OSErr PBSetForkPositionSync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
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.
The relevant fields of the parameter block are:
forkRefNum
On input, the reference number of a fork previously opened by the FSOpenFork
, PBOpenForkSync
, or PBOpenForkAsync
function.
positionMode
On input, a constant specifying the base location within the fork for the new position. If this field is equal to fsAtMark
, then the positionOffset
field is ignored. See “Position Mode Constants” for a description of the constants you can use to specify the base location.
positionOffset
On input, the offset of the new position from the base location specified in the positionMode
field.
To determine if the PBSetForkPositionSync
function is present, call the Gestalt
function with the gestaltFSAttr
selector. If the PBSetForkPositionSync
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 PBSetForkPositionSync
function, you can only set the file position for the data and resource forks, and you cannot grow these files beyond 2GB.
Files.h
Changes the size of an open fork.
void PBSetForkSizeAsync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
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. If there is not enough space on the volume to extend the fork, then dskFulErr
is returned and the fork’s size is unchanged.
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
.
positionMode
On input, 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
On input, the offset of the new size from the base location specified in the positionMode
field.
The PBSetForkSizeAsync
function sets the logical end-of-file to the position indicated by the positionMode
and positionOffset
fields. 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. That is, the current position will be equal to the logical end of file.
You do not need to check that the volume supports the PBSetForkSizeAsync
function. If a volume does not support the PBSetForkSizeAsync
function, but the PBSetForkSizeAsync
function is present, the File Manager automatically calls the PBSetEOFAsync
function and translates between the calls appropriately.
Note, however, that if the volume does not support the PBSetForkSizeAsync
function, you can only access the data and resource forks, and you cannot grow the fork beyond 2GB. To check that the PBSetForkSizeAsync
function is present, call the Gestalt
function.
Files.h
Changes the size of an open fork.
OSErr PBSetForkSizeSync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
data type.
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.
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 one of the corresponding parameter block calls, PBOpenForkSync
and PBOpenForkAsync
.
positionMode
On input, 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
On input, the offset of the new size from the base location specified in the positionMode
field.
The PBSetForkSizeSync
function sets the logical end-of-file to the position indicated by the positionMode
and positionOffset
fields. 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. That is, the current position will be equal to the logical end-of-file.
You do not need to check that the volume supports the PBSetForkSizeSync
function. If a volume does not support the PBSetForkSizeSync
function, but the PBSetForkSizeSync
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 PBSetForkSizeSync
function, you can only access the data and resource forks, and you cannot grow the fork beyond 2GB. To check that the PBSetForkSizeSync
function is present, call the Gestalt
function.
Files.h
Sets information about a volume.
void PBSetVolumeInfoAsync ( FSVolumeInfoParam *paramBlock );
A pointer to a volume information parameter block. See FSVolumeInfoParam
for a description of the FSVolumeInfoParam
data type.
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.
ioVRefNum
On input, the volume reference number of the volume whose information is to be changed.
whichInfo
On input, 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.
volumeInfo
On input, the new volume information. See FSVolumeInfo
for more information about the volume information structure.
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
.
Files.h
Sets information about a volume.
OSErr PBSetVolumeInfoSync ( FSVolumeInfoParam *paramBlock );
A pointer to a volume information parameter block. See FSVolumeInfoParam
for a description of the FSVolumeInfoParam
data type.
A result code. See “File Manager Result Codes.”
The relevant fields of the parameter block are:
ioVRefNum
On input, the volume reference number of the volume whose information is to be changed.
whichInfo
On input, 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.
volumeInfo
On input, the new volume information. See FSVolumeInfo
for more information about the volume information structure.
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
.
Files.h
Writes data to an open fork.
void PBWriteForkAsync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
.
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. If there is not enough space on the volume to write requestCount
bytes, then dskFulErr
is returned.
forkRefNum
On input, 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
On input, 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
On input, the offset from the base location for the start of the write.
requestCount
On input, the number of bytes to write.
buffer
A pointer to a buffer containing the data to write.
actualCount
On output, the number of bytes actually written. The value in the actualCount
field will be equal to the value in the requestCount
field unless there was an error during the write operation.
PBWriteForkAsync
writes data starting at the position specified by the positionMode
and positionOffset
fields. The function attempts to write requestCount
bytes from the buffer pointed to by the buffer
field 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.
Files.h
Writes data to an open fork.
OSErr PBWriteForkSync ( FSForkIOParam *paramBlock );
A pointer to a fork I/O parameter block. See FSForkIOParam
for a description of the FSForkIOParam
.
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.
The relevant fields of the parameter block are:
ioResult
On output, the result code of the function. If there is not enough space on the volume to write requestCount
bytes, then dskFulErr
is returned.
forkRefNum
On input, 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
On input, 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
On input, the offset from the base location for the start of the write.
requestCount
On input, the number of bytes to write.
buffer
A pointer to a buffer containing the data to write.
actualCount
On output, the number of bytes actually written. The value in the actualCount
field will be equal to the value in the requestCount
field unless there was an error during the write operation.
PBWriteForkSync
writes data starting at the position specified by the positionMode
and positionOffset
fields. The function attempts to write requestCount
bytes from the buffer pointed to by the buffer
field 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.
Files.h
Locks a range of bytes of the specified fork.
OSStatus PBXLockRangeAsync ( FSRangeLockParamPtr paramBlock );
Files.h
Locks a range of bytes of the specified fork.
OSStatus PBXLockRangeSync ( FSRangeLockParamPtr paramBlock );
Files.h
Unlocks a range of bytes of the specified fork.
OSStatus PBXUnlockRangeAsync ( FSRangeLockParamPtr paramBlock );
Files.h
Unlocks a range of bytes of the specified fork.
OSStatus PBXUnlockRangeSync ( FSRangeLockParamPtr paramBlock );
Files.h
FNSubscriptionProcPtr
FSVolumeEjectProcPtr
FSVolumeMountProcPtr
FSVolumeUnmountProcPtr
IOCompletionProcPtr
Callback delivered for directory notifications.
typedef void (*FNSubscriptionProcPtr) ( FNMessage message, OptionBits flags, void * refcon, FNSubscriptionRef subscription );
If you name your function MyFNSubscriptionProc
, you would declare it like this:
void MyFNSubscriptionProc ( FNMessage message, OptionBits flags, void * refcon, FNSubscriptionRef subscription );
An indication of what happened.
Options regarding the delivery of the notification; typically kNilOptions
.
A pointer to a user reference supplied with subscription.
A subscription corresponding to this notification.
Files.h
Defines a status callback function for an asynchronous file operation on an FSRef
object.
typedef void (*FSFileOperationStatusProcPtr) ( FSFileOperationRef fileOp, const FSRef *currentItem, FSFileOperationStage stage, OSStatus error, CFDictionaryRef statusDictionary, void *info );
If you name your function MyFSFileOperationStatusProc
, you would declare it like this:
void MyFSFileOperationStatusProc ( FSFileOperationRef fileOp, const FSRef *currentItem, FSFileOperationStage stage, OSStatus error, CFDictionaryRef statusDictionary, void *info );
The file operation.
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).
The current stage of the operation.
The current error status of the operation.
A dictionary with more detailed status information. For information about the contents of the dictionary, see “File Operation Status Dictionary Keys”
. You are not responsible for releasing the dictionary.
A pointer to user-defined data associated with this operation.
When you call FSCopyObjectAsync
, FSMoveObjectAsync
, or FSMoveObjectToTrashAsync
, you can specify a status callback function of this type. The function you provide is called by the File Manager whenever the file operation changes stages (including failing due to an error), or as updated information is available limited by the status change interval of the operation. If you need to save any of the status information beyond the scope of the callback, you should make a copy of the information.
Files.h
Defines a status callback function for an asynchronous file operation on an object specified with a pathname.
typedef void (*FSPathFileOperationStatusProcPtr) ( FSFileOperationRef fileOp, const char *currentItem, FSFileOperationStage stage, OSStatus error, CFDictionaryRef statusDictionary, void *info );
If you name your function MyFSPathFileOperationStatusProc
, you would declare it like this:
void MyFSPathFileOperationStatusProc ( FSFileOperationRef fileOp, const char *currentItem, FSFileOperationStage stage, OSStatus error, CFDictionaryRef statusDictionary, void *info );
The file operation.
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).
The current stage of the operation.
The current error status of the operation.
A dictionary with more detailed status information. For information about the contents of the dictionary, see “File Operation Status Dictionary Keys”
. You are not responsible for releasing the dictionary.
A pointer to user-defined data associated with this operation.
When you call FSPathCopyObjectAsync
, FSPathMoveObjectAsync
, or FSPathMoveObjectToTrashAsync
, you can specify a status callback function of this type. The function you provide is called by the File Manager whenever the file operation changes stages (including failing due to an error), or as updated information is available limited by the status change interval of the operation. If you need to save any of the status information beyond the scope of the callback, you should make a copy of the information.
Files.h
typedef void (*FSVolumeEjectProcPtr) ( FSVolumeOperation volumeOp, void * clientData, OSStatus err, FSVolumeRefNum volumeRefNum, pid_t dissenter );
If you name your function MyFSVolumeEjectProc
, you would declare it like this:
void MyFSVolumeEjectProc ( FSVolumeOperation volumeOp, void * clientData, OSStatus err, FSVolumeRefNum volumeRefNum, pid_t dissenter );
Files.h
typedef void (*FSVolumeMountProcPtr) ( FSVolumeOperation volumeOp, void * clientData, OSStatus err, FSVolumeRefNum mountedVolumeRefNum );
If you name your function MyFSVolumeMountProc
, you would declare it like this:
void MyFSVolumeMountProc ( FSVolumeOperation volumeOp, void * clientData, OSStatus err, FSVolumeRefNum mountedVolumeRefNum );
Files.h
typedef void (*FSVolumeUnmountProcPtr) ( FSVolumeOperation volumeOp, void * clientData, OSStatus err, FSVolumeRefNum volumeRefNum, pid_t dissenter );
If you name your function MyFSVolumeUnmountProc
, you would declare it like this:
void MyFSVolumeUnmountProc ( FSVolumeOperation volumeOp, void * clientData, OSStatus err, FSVolumeRefNum volumeRefNum, pid_t dissenter );
Files.h
Defines a pointer to a completion function. Your completion function is executed by the File Manager after the completion of an asynchronous File Manager function call.
typedef void (*IOCompletionProcPtr) ( ParmBlkPtr paramBlock );
If you name your function MyIOCompletionProc
, you would declare it like this:
void MyIOCompletionProc ( ParmBlkPtr paramBlock );
A pointer to the parameter block that was passed to the asynchronous File Manager function.
When you execute an asynchronous File Manager function (an Async
function), you can specify a completion routine by passing the routine’s address in the ioCompletion
field of the parameter block passed to the function. Because you requested asynchronous execution, the File Manager places an I/O request in the file I/O queue and returns control to your application—possibly even before the actual I/O operation is completed. The File Manager takes requests from the queue one at a time and processes them meanwhile, your application is free to do other processing.
A function executed asynchronously returns control to your application with the result code noErr
as soon as the call is placed in the file I/O queue. This result code does not indicate that the call has successfully completed, but simply indicates that the call was successfully placed in the queue. To determine when the call is actually completed, you can inspect the ioResult
field of the parameter block. This field is set to a positive number when the call is made and set to the actual result code when the call is completed. If you specify a completion routine, it is executed after the result code is placed in ioResult
.
The File Manager, when the File Sharing or AppleShare file server is active, will execute requests in arbitrary order. That means that if there is a request that depends on the completion of a previous request, it is an error for your program to issue the second request until the completion of the first request. For example, issuing a write request and then issuing a read request for the same data isn't guaranteed to read back what was written unless the read request isn't made until after the write request completes.
Request order can also change if a call results in a disk switch dialog to bring an offline volume back online.
Because a completion routine is executed at interrupt time, it should not allocate, move, or purge memory (either directly or indirectly) and should not depend on the validity of handles to unlocked blocks.
If your completion routine uses application global variables, it must also ensure that register A5 contains the address of the boundary between your application global variables and your application parameters.
Files.h
Defines a parameter block used by low-level HFS file and directory access rights manipulation functions.
struct AccessParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short filler3; short ioDenyModes; short filler4; SInt8 filler5; SInt8 ioACUser; long filler6; long ioACOwnerID; long ioACGroupID; long ioACAccess; long ioDirID; }; typedef struct AccessParam AccessParam; typedef AccessParam * AccessParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
filler3
Reserved.
ioDenyModes
Access mode information.
filler4
Reserved.
filler5
Reserved.
ioACUser
The user’s access rights for the specified directory.
filler6
Reserved.
ioACOwnerID
The owner ID.
ioACGroupID
The group ID.
ioACAccess
The directory access privileges.
ioDirID
Files.h
Defines a block of tagged addresses for AppleShare clients.
struct AFPAlternateAddress { UInt8 fVersion; UInt8 fAddressCount; UInt8 fAddressList[1]; }; typedef struct AFPAlternateAddress AFPAlternateAddress;
Files.h
Defines a structure which contains tagged address information for AppleShare clients.
struct AFPTagData { UInt8 fLength; UInt8 fType; UInt8 fData[1]; }; typedef struct AFPTagData AFPTagData;
fLength
The length, in bytes, of this data tag, including the fLength
field itself. See “AFP Tag Length Constants.”
fType
The type of the data tag. See “AFP Tag Type Constants” for the constants which you can use here.
fData
Variable length data, containing the address.
The new tagged data format for addressing allows for changes in addressing formats, allowing AppleShare clients to support new addressing standards without changing the interface. The AFPAlternateAddress
data structure uses the AFPTagData
structure to specify a tagged address.
Files.h
Defines a volume mounting structure for an AppleShare server.
struct AFPVolMountInfo { short length; VolumeType media; short flags; SInt8 nbpInterval; SInt8 nbpCount; short uamType; short zoneNameOffset; short serverNameOffset; short volNameOffset; short userNameOffset; short userPasswordOffset; short volPasswordOffset; char AFPData[144]; }; typedef struct AFPVolMountInfo AFPVolMountInfo; typedef AFPVolMountInfo * AFPVolMountInfoPtr;
length
The length of the AFPVolMountInfo
structure (that is, the total length of the structure header described here plus the variable-length location data).
media
The volume type of the remote volume. The value AppleShareMediaType
(a constant that translates to 'afpm'
) represents an AppleShare volume.
flags
If bit 0 is set, no greeting message from the server is displayed.
nbpInterval
The NBP retransmit interval, in units of 8 ticks.
nbpCount
The NBP retransmit count. This field specifies the total number of times a packet should be transmitted, including the first transmission.
uamType
The user authentication method used by the remote volume. AppleShare uses four methods, defined by the constants described in “Authentication Method Constants.”
zoneNameOffset
The offset in bytes from the beginning of the structure to the entry in the AFPData
field containing the name (as a pascal string) of the AppleShare zone.
serverNameOffset
The offset in bytes from the beginning of the structure to the entry in the AFPData
field containing the name (as a pascal string) of the AppleShare server.
volNameOffset
The offset in bytes from the beginning of the structure to the entry in the AFPData
field containing the name (as a pascal string) of the volume.
userNameOffset
The offset in bytes from the beginning of the structure to the entry in the AFPData
field containing the name (as a pascal string) of the user.
userPasswordOffset
The offset in bytes from the beginning of the structure to the entry in the AFPData
field containing the user’s password (as a pascal string).
volPasswordOffset
The offset in bytes from the beginning of the structure to the entry in the AFPData
field containing the volume’s password (as a pascal string). Some versions of the AppleShare software do not pass the information in this field to the server.
AFPData
The actual volume mounting information, offsets to which are contained in the preceding six fields. To mount an AFP volume, you must fill in the structure with at least the zone name, server name, user name, user password, and volume password. You can lay out the data in any order within this data field, as long as you specify the correct offsets in the offset fields.
The only volumes that currently support the programmatic mounting functions are AppleShare servers, which use a volume mounting structure of type AFPVolMountInfo
.
To mount an AppleShare server, fill out an AFPVolMountInfo
structure using the PBGetVolMountInfo
function and then pass this structure to the PBVolumeMount
function to mount the volume.
AppleShare clients prior to version 3.7 mount volumes over AppleTalk only. For maximum compatibility set the uamType
field to 1 for guest login or 3 for login using a password.
To mount volumes using IP addresses and other address formats, use the AFPXVolMountInfo
structure.
Files.h
Defines a volume mounting structure for an AppleShare server, for AppleShare 3.7 and later.
struct AFPXVolMountInfo { short length; VolumeType media; short flags; SInt8 nbpInterval; SInt8 nbpCount; short uamType; short zoneNameOffset; short serverNameOffset; short volNameOffset; short userNameOffset; short userPasswordOffset; short volPasswordOffset; short extendedFlags; short uamNameOffset; short alternateAddressOffset; char AFPData[176]; }; typedef struct AFPXVolMountInfo AFPXVolMountInfo; typedef AFPXVolMountInfo * AFPXVolMountInfoPtr;
length
The length of the AFPXVolMountInfo
structure (that is, the total length of the structure header described here plus the variable-length location data).
media
The volume type of the remote volume. The value AppleShareMediaType
(a constant that translates to 'afpm'
) represents an AppleShare volume.
flags
Volume mount flags. See “Volume Mount Flags” for a description of the bits in this field. In order to use the new features of the extended AFP volume mount structure, you must set the volMountExtendedFlagsBit
bit.
nbpInterval
The NBP retransmit interval, in units of 8 ticks.
nbpCount
The NBP retransmit count. This field specifies the total number of times a packet should be transmitted, including the first transmission.
uamType
The user authentication method used by the remote volume. AppleShare uses four methods, defined by the constants described in “Authentication Method Constants.”
zoneNameOffset
The offset in bytes from the beginning of the structure to the entry in the AFPData
field containing the name (as a pascal string) of the AppleShare zone.
serverNameOffset
The offset in bytes from the beginning of the structure to the entry in the AFPData
field containing the name (as a pascal string) of the AppleShare server.
volNameOffset
The offset in bytes from the beginning of the structure to the entry in the AFPData
field containing the name (as a pascal string) of the volume.
userNameOffset
The offset in bytes from the beginning of the structure to the entry in the AFPData
field containing the name (as a pascal string) of the user.
userPasswordOffset
The offset in bytes from the beginning of the structure to the entry in the AFPData
field containing the user’s password (as a pascal string).
volPasswordOffset
The offset in bytes from the beginning of the structure to the entry in the AFPData
field containing the volume’s password (as a pascal string). Some versions of the AppleShare software do not pass the information in this field to the server.
extendedFlags
Extended flags. See “Extended AFP Volume Mounting Information Flag.”
uamNameOffset
The offset in bytes from the beginning of the structure to the entry in the AFPData
field containing the user authentication module name (as a pascal string).
alternateAddressOffset
The offset in bytes from the beginning of the structure to the entry in the AFPData
field containing IP addresses, specified as a block of tagged data. This block of tagged data begins with a version byte and a count byte, followed by up to 255 tagged addresses. See AFPAlternateAddress
.
AFPData
The actual volume mounting information, offsets to which are contained in the preceding fields. To mount an AFP volume, you must fill in the structure with at least the zone name, server name, user name, user password, and volume password. You can lay out the data in any order within this data field, as long as you specify the correct offsets in the offset fields.
To mount an AppleShare server, fill out an AFPXVolMountInfo
structure using the PBGetVolMountInfo
function and then pass this structure to the PBVolumeMount
function to mount the volume.
The extended AFP volume mount information structure requires AppleShare client 3.7 and later. The new fields and flag bits allow you to specify the information needed to support TCP/IP and User Authentication Modules.
Note that, for all fields specifying an offset, if you wish to leave the string field in the AFPData
field empty, you must specify an empty string and have the offset in the corresponding offset field point to that empty string. You cannot simply pass 0 as the offset.
Files.h
Defines a catalog position structure, which maintains the current position of a catalog search between calls to PBCatSearchSync
or PBCatSearchAsync
.
struct CatPositionRec { long initialize; short priv[6]; }; typedef struct CatPositionRec CatPositionRec;
initialize
The starting point of the catalog search. To start searching at the beginning of a catalog, specify 0 in this field. To resume a previous search, pass the value returned by the previous call to PBCatSearchSync
or PBCatSearchAsync
.
priv
An array of integers that is used internally by PBCatSearchSync
and PBCatSearchAsync
.
When you call the PBCatSearchSync
or PBCatSearchAsync
function to search a volume’s catalog file, you can specify, in the ioCatPosition
field of the parameter block passed to PBCatSearchSync
and PBCatSearchAsync
, a catalog position structure. If a catalog search consumes more time than is allowed by the ioSearchTime
field, PBCatSearchSync
and PBCatSearchAsync
store a directory-location index in that structure; when you call PBCatSearchSync
or PBCatSearchAsync
again, it uses that structure to resume searching where it left off.
Files.h
Defines a catalog information parameter block for file and directory information.
union CInfoPBRec { HFileInfo hFileInfo; DirInfo dirInfo; }; typedef union CInfoPBRec CInfoPBRec; typedef CInfoPBRec * CInfoPBPtr;
hFileInfo
dirInfo
Files.h
Defines a parameter block, used with the functions PBCatMoveSync
and PBCatMoveAsync
.
struct CMovePBRec { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; long filler1; StringPtr ioNewName; long filler2; long ioNewDirID; long filler3[2]; long ioDirID; }; typedef struct CMovePBRec CMovePBRec; typedef CMovePBRec * CMovePBPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type (This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
filler1
Reserved.
ioNewName
The name of the directory into which the specified file or directory is to be moved.
filler2
Reserved.
ioNewDirID
The directory ID of the directory into which the specified file or directory is to be moved.
filler3
Reserved.
ioDirID
The current directory ID of the file or directory to be moved (used in conjunction with the ioVRefNum
and ioNamePtr
fields).
The low-level HFS function PBCatMove
uses the catalog move parameter block defined by the CMovePBRec
data type.
Files.h
Defines a parameter block used by control and status functions in the classic Device Manager.
struct CntrlParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short ioCRefNum; short csCode; short csParam[11]; }; typedef struct CntrlParam CntrlParam; typedef CntrlParam * CntrlParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
ioCRefNum
The driver reference number for the I/O operation.
csCode
A value identifying the type of control or status request. Each driver may interpret this number differently.
csParam
The control or status information passed to or from the driver. This field is declared generically as an array of eleven integers. Each driver may interpret the contents of this field differently. Refer to the driver's documentation for specific information.
Files.h
Defines a pointer to an FSSpec
structure.
typedef const FSSpec* ConstFSSpecPtr;
The only difference between “const FSSpec*
” and the ConstFSSpecPtr
data type is that, as a parameter, a ConstFSSpecPtr
data type is allowed to be NULL
. See FSSpec
.
Files.h
Defines a pointer to an HFSUniStr255
structure.
typedef const HFSUniStr255* ConstHFSUniStr255Param;
See HFSUniStr255
.
Files.h
Defines a parameter block used by low-level HFS file copying functions.
struct CopyParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short ioDstVRefNum; short filler8; StringPtr ioNewName; StringPtr ioCopyName; long ioNewDirID; long filler14; long filler15; long ioDirID; }; typedef struct CopyParam CopyParam; typedef CopyParam * CopyParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
ioDstVRefNum
A volume reference number for the destination volume.
filler8
Reserved.
ioNewName
A pointer to the destination pathname.
ioCopyName
A pointer to an optional name.
ioNewDirID
A destination directory ID.
filler14
Reserved.
filler15
Reserved.
ioDirID
A directory ID.
Files.h
Defines a parameter block used by low-level HFS catalog search functions.
struct CSParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; FSSpecPtr ioMatchPtr; long ioReqMatchCount; long ioActMatchCount; long ioSearchBits; CInfoPBPtr ioSearchInfo1; CInfoPBPtr ioSearchInfo2; long ioSearchTime; CatPositionRec ioCatPosition; Ptr ioOptBuffer; long ioOptBufSize; }; typedef struct CSParam CSParam; typedef CSParam * CSParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
ioMatchPtr
A pointer to an array of FSSpec
structures in which the file and directory names that match the selection criteria are returned. The array must be large enough to hold the largest possible number of FSSpec
structures, as determined by the ioReqMatchCount
field.
ioReqMatchCount
The maximum number of matches to return. This number should be the number of FSSpec
structures that will fit in the memory pointed to by the ioMatchPtr
field. You can use this field to avoid a possible excess of matches for criteria that prove to be too general (or to limit the length of a search if the ioSearchTime
field isn’t used).
ioActMatchCount
The number of actual matches found.
ioSearchBits
The fields of the parameter blocks in the ioSearchInfo1
and ioSearchInfo2
fields that are relevant to the search. See “Catalog Search Bits” for more information.
ioSearchInfo1
A pointer to a CInfoPBRec
parameter block that contains the search information. For values that match by mask and value (Finder information, for example), set the bits in the structure passed in the ioSearchInfo2
field, and set the matching values in this structure. For values that match against a range (such as dates), set the lower bounds for the range in this structure.
ioSearchInfo2
A pointer to a second CInfoPBRec
parameter block that contains the search information. For values that match by mask and value (Finder information, for example), set the bits in this structure, and set the matching values in the structure passed in the ioSearchInfo1
field. For values that match against a range (such as dates), set the upper bounds for the range in this structure.
ioSearchTime
A time limit on a search, in Time Manager format. Use this field to limit the run time of a single call to PBCatSearchSync
or PBCatSearchAsync
. A value of 0 imposes no time limit. If the value of this field is positive, it is interpreted as milliseconds. If the value of this field is negative, it is interpreted as negated microseconds.
ioCatPosition
A position in the catalog where searching should begin. Use this field to keep an index into the catalog when breaking down the PBCatSearchSync
or PBCatSearchAsync
search into a number of smaller searches. This field is valid whenever PBCatSearchSync
or PBCatSearchAsync
exits because it either spends the maximum time allowed by ioSearchTime
or finds the maximum number of matches allowed by ioReqMatchCount
.
To start at the beginning of the catalog, set the initialize
field of ioCatPosition
to 0. Before exiting after an interrupted search, PBCatSearchSync
or PBCatSearchAsync
sets that field to the next catalog entry to be searched.
To resume where the previous call stopped, pass the entire CatPositionRec
structure returned by the previous call as input to the next.
ioOptBuffer
A pointer to an optional read buffer. The ioOptBuffer
and ioOptBufSize
fields let you specify a part of memory as a read buffer, increasing search speed.
ioOptBufSize
The size of the buffer pointed to by ioOptBuffer
. Buffer size effectiveness varies with models and configurations, but a 16 KB buffer is likely to be optimal. The size should be at least 1024 bytes and should be an integral multiple of 512 bytes.
Files.h
Defines a structure which holds catalog information about a directory.
struct DirInfo { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short ioFRefNum; SInt8 ioFVersNum; SInt8 filler1; short ioFDirIndex; SInt8 ioFlAttrib; SInt8 ioACUser; DInfo ioDrUsrWds; long ioDrDirID; unsigned short ioDrNmFls; short filler3[9]; unsigned long ioDrCrDat; unsigned long ioDrMdDat; unsigned long ioDrBkDat; DXInfo ioDrFndrInfo; long ioDrParID; }; typedef struct DirInfo DirInfo;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
ioFRefNum
The file reference number of an open file.
ioFVersNum
A file version number. This field is no longer used. File version numbers are an artifact of the obsolete MFS, and are not supported on HFS volumes. You should always set this field to 0.
filler1
Reserved.
ioFDirIndex
A file and directory index. If this field contains a positive number, PBGetCatInfoSync
and PBGetCatInfoAsync
return information about the file or directory having that directory index in the directory specified by the ioVRefNum
field. (If ioVRefNum
contains a volume reference number, the specified directory is that volume’s root directory.)
If this field contains 0, PBGetCatInfoSync
and PBGetCatInfoAsync
return information about the file or directory whose name is specified in the ioNamePtr
field and that is located in the directory specified by the ioVRefNum
field. (Once again, if ioVRefNum
contains a volume reference number, the specified directory is that volume’s root directory.)
If this field contains a negative number, PBGetCatInfoSync
and PBGetCatInfoAsync
ignore the ioNamePtr
field and returns information about the directory specified in the ioDirID
field. If both ioDirID
and ioVRefNum
are set to 0, PBGetCatInfoSync
and PBGetCatInfoAsync
return information about the current default directory.
ioFlAttrib
File or directory attributes. See “File Attribute Constants” for the meaning of the bits in this field.
ioACUser
The user’s access rights for the specified directory. See “User Privileges Constants” for the meaning of the bits in this field.
ioDrUsrWds
Information used by the Finder.
ioDrDirID
A directory ID. On input to PBGetCatInfoSync
and PBGetCatInfoAsync
, this field contains a directory ID, which is used only if the value of the ioFDirIndex
field is negative. On output, this field contains the directory ID of the specified directory.
ioDrNmFls
The number of files in the directory.
filler3
Reserved.
ioDrCrDat
The date and time of the directory’s creation, in seconds since midnight, January 1, 1904. However, on Mac OS X, if you set the creation date to a date between January 1, 1904 and January 1, 1970, it will be clipped to January 1, 1970, and that is the value which will be returned if you later try to retrieve the creation date.
Note that file systems other than AFP, HFS and HFS Plus do not generally support creation dates.
ioDrMdDat
The date and time of the last modification to the directory, in seconds since midnight, January 1, 1904. However, on Mac OS X, if you set the modification date to a date between January 1, 1904 and January 1, 1970, it will be clipped to January 1, 1970.
ioDrBkDat
The date and time that the directory was last backed up, in seconds since midnight, January 1, 1904. However, on Mac OS X, if you set the backup date to a date between January 1, 1904 and January 1, 1970, it will be clipped to January 1, 1970.
Note that file systems other than AFP, HFS and HFS Plus do not generally support backup dates.
ioDrFndrInfo
Additional information used by the Finder.
ioDrParID
The directory ID of the specified directory’s parent directory.
refCon
Files.h
Defines a drive queue element.
struct DrvQEl { QElemPtr qLink; short qType; short dQDrive; short dQRefNum; short dQFSID; unsigned short dQDrvSz; unsigned short dQDrvSz2; }; typedef struct DrvQEl DrvQEl; typedef DrvQEl * DrvQElPtr;
qLink
A pointer to the next entry in the drive queue.
qType
Used to specify the size of the drive. If the value of this field is 0, the number of logical blocks on the drive is contained in the dQDrvSz
field alone. If the value of this field is 1, both the dQDrvSz
field and the dQDrvSz2
field are used to store the number of blocks; in that case, the dQDrvSz2
field contains the high-order word of this number and dQDrvSz
contains the low-order word.
dQDrive
The drive number of the drive.
dQRefNum
The driver reference number of the driver controlling the device on which the volume is mounted.
dQFSID
An identifier for the file system handling the volume in the drive it’s zero for volumes handled by the File Manager and nonzero for volumes handled by other file systems.
dQDrvSz
The number of logical blocks on the drive.
dQDrvSz2
An additional field to handle large drives. This field is only used if the qType
field is 1.
The File Manager maintains a list of all disk drives connected to the computer. It maintains this list in the drive queue, which is a standard operating system queue. The drive queue is initially created at system startup time. Elements are added to the queue at system startup time or when you call the AddDrive
function. The drive queue can support any number of drives, limited only by memory space. Each element in the drive queue contains information about the corresponding drive.
Files.h
Defines the desktop database parameter block used by the desktop database functions.
struct DTPBRec { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short ioDTRefNum; short ioIndex; long ioTagInfo; Ptr ioDTBuffer; long ioDTReqCount; long ioDTActCount; SInt8 ioFiller1; UInt8 ioIconType; short ioFiller2; long ioDirID; OSType ioFileCreator; OSType ioFileType; long ioFiller3; long ioDTLgLen; long ioDTPyLen; short ioFiller4[14]; long ioAPPLParID; }; typedef struct DTPBRec DTPBRec; typedef DTPBRec * DTPBPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a file, directory, or volume name. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
The volume reference number.
ioDTRefNum
The desktop database reference number.
ioIndex
The index into icon list.
ioTagInfo
The tag information.
ioDTBuffer
The data buffer.
ioDTReqCount
The requested length of data.
ioDTActCount
The actual length of data.
ioFiller1
Unused.
ioIconType
The icon type.
ioFiller2
Unused.
ioDirID
The parent directory ID.
ioFileCreator
The file creator.
ioFileType
The file type.
ioFiller3
Unused.
ioDTLgLen
The logical length of the desktop database.
ioDTPyLen
The physical length of the desktop database.
ioFiller4
Unused.
ioAPPLParID
The parent directory ID of an application.
Files.h
Defines a file control block (FCB) parameter block used by the functions PBGetFCBInfoSync
and PBGetFCBInfoAsync
.
struct FCBPBRec { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short ioRefNum; short filler; short ioFCBIndx; short filler1; long ioFCBFlNm; short ioFCBFlags; unsigned short ioFCBStBlk; long ioFCBEOF; long ioFCBPLen; long ioFCBCrPs; short ioFCBVRefNum; long ioFCBClpSiz; long ioFCBParID; }; typedef struct FCBPBRec FCBPBRec; typedef FCBPBRec * FCBPBPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
ioRefNum
The file reference number of an open file.
filler
Reserved.
ioFCBIndx
An index for use with the PBGetFCBInfoSync
and PBGetFCBInfoAsync
functions.
filler1
Reserved.
ioFCBFlNm
The file ID.
ioFCBFlags
Flags describing the status of the file. See “FCB Flags” for the meanings of the bits in this field.
ioFCBStBlk
The number of the first allocation block of the file.
ioFCBEOF
The logical length (logical end-of-file) of the file.
ioFCBPLen
The physical length (physical end-of-file) of the file.
ioFCBCrPs
The current position of the file mark.
ioFCBVRefNum
The volume reference number.
ioFCBClpSiz
The file clump size.
ioFCBParID
The file’s parent directory ID.
The low-level HFS function PBGetFCBInfo
uses the file control block parameter block defined by the FCBPBRec
data type.
Files.h
Defines a parameter block used by low-level HFS file ID functions.
struct FIDParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; long filler14; StringPtr ioDestNamePtr; long filler15; long ioDestDirID; long filler16; long filler17; long ioSrcDirID; short filler18; long ioFileID; }; typedef struct FIDParam FIDParam; typedef FIDParam * FIDParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
filler14
Reserved.
ioDestNamePtr
A pointer to the name of the destination file.
filler15
Reserved.
ioDestDirID
The parent directory ID of the destination file.
filler16
Reserved.
filler17
Reserved.
ioSrcDirID
The parent directory ID of the source file.
filler18
Reserved.
ioFileID
The file ID.
Files.h
Defines a parameter block used by low-level functions for getting and setting file information.
struct FileParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short ioFRefNum; SInt8 ioFVersNum; SInt8 filler1; short ioFDirIndex; SInt8 ioFlAttrib; SInt8 ioFlVersNum; FInfo ioFlFndrInfo; unsigned long ioFlNum; unsigned short ioFlStBlk; long ioFlLgLen; long ioFlPyLen; unsigned short ioFlRStBlk; long ioFlRLgLen; long ioFlRPyLen; unsigned long ioFlCrDat; unsigned long ioFlMdDat; }; typedef struct FileParam FileParam; typedef FileParam * FileParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
ioFRefNum
The file reference number of an open file.
ioFVersNum
A file version number. This field is no longer used. File version numbers are an artifact of the obsolete MFS, and are not supported on HFS volumes. You should always set this field to 0.
filler1
Reserved.
ioFDirIndex
A directory index for use with the PBHGetFInfoSync
and PBHGetFInfoAsync
functions.
ioFlAttrib
File attributes. See “File Attribute Constants” for the meaning of the bits in this field.
ioFlVersNum
A file version number. This feature is no longer supported, and you must always set this field to 0.
ioFlFndrInfo
Information used by the Finder.
ioFlNum
A file ID.
ioFlStBlk
The first allocation block of the data fork. This field contains 0 if the file’s data fork is empty.
ioFlLgLen
The logical length (logical end-of-file) of the data fork.
ioFlPyLen
The physical length (physical end-of-file) of the data fork.
ioFlRStBlk
The first allocation block of the resource fork. This field contains 0 if the file’s resource fork is empty.
ioFlRLgLen
The logical length (logical end-of-file) of the resource fork.
ioFlRPyLen
The physical length (physical end-of-file) of the resource fork.
ioFlCrDat
The date and time of the file’s creation, specified in seconds since midnight, January 1, 1904.
ioFlMdDat
The date and time of the last modification to the file, specified in seconds since midnight, January 1, 1904.
Files.h
typedef struct OpaqueFNSubscriptionRef * FNSubscriptionRef;
Files.h
typedef FNSubscriptionProcPtr FNSubscriptionUPP;
Files.h
Defines a parameter block used by low-level HFS foreign privileges functions.
struct ForeignPrivParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; long ioFiller21; long ioFiller22; Ptr ioForeignPrivBuffer; long ioForeignPrivActCount; long ioForeignPrivReqCount; long ioFiller23; long ioForeignPrivDirID; long ioForeignPrivInfo1; long ioForeignPrivInfo2; long ioForeignPrivInfo3; long ioForeignPrivInfo4; }; typedef struct ForeignPrivParam ForeignPrivParam; typedef ForeignPrivParam * ForeignPrivParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
ioFiller21
Reserved.
ioFiller22
Reserved.
ioForeignPrivBuffer
A pointer to a buffer containing access-control information about the foreign file system.
ioForeignPrivActCount
The size of the buffer pointed to by the ioForeignPrivBuffer
field.
ioForeignPrivReqCount
The amount of the buffer pointed to by the ioForeignPrivBuffer
field that was actually used to hold data.
ioFiller23
Reserved.
ioForeignPrivDirID
The parent directory ID of the foreign file or directory.
ioForeignPrivInfo1
A long word that may contain privileges data.
ioForeignPrivInfo2
A long word that may contain privileges data.
ioForeignPrivInfo3
A long word that may contain privileges data.
ioForeignPrivInfo4
A long word that may contain privileges data.
Files.h
Defines a parameter block used to retrieve catalog information in bulk on HFS Plus volumes.
struct FSCatalogBulkParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; Boolean containerChanged; UInt8 reserved; FSIteratorFlags iteratorFlags; FSIterator iterator; const FSRef * container; ItemCount maximumItems; ItemCount actualItems; FSCatalogInfoBitmap whichInfo; FSCatalogInfo * catalogInfo; FSRef * refs; FSSpec * specs; HFSUniStr255 * names; const FSSearchParams * searchParams; }; typedef struct FSCatalogBulkParam FSCatalogBulkParam; typedef FSCatalogBulkParam * FSCatalogBulkParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
containerChanged
A Boolean value indicating whether or not the container has changed since the last call to PBGetCatalogInfoBulkSync
or PBGetCatalogInfoBulkAsync
.
reserved
Reserved.
iteratorFlags
A set of flags which specifies how the iterator should iterate over the container. See “Iterator Flags” for the meaning of the constants used here.
iterator
A catalog iterator.
container
An FSRef
for the directory or volume to iterate over.
maximumItems
The maximum number of items to return information about.
actualItems
The actual number of items returned.
whichInfo
A bitmap indicating which fields of the catalog information structure to return. See “Catalog Information Bitmap Constants” for the bits defined for this field.
catalogInfo
A pointer to an array of catalog information structures. On input, you should pass a pointer to an array of maximumItems
FSCatalogInfo
structures. On return, actualItems
structures will be filled out with the information requested in the whichInfo
field. If you do not wish any catalog information to be returned, pass a NULL
pointer in this field and pass the constant kFSCatInfoNone
in the whichInfo
field.
refs
A pointer to an array of FSRef
structures. On input, you should pass a pointer to maximumItems
FSRef
structures. On return, actualItems
structures will be filled out. If you do not wish any FSRef
structures to be returned, pass a NULL
pointer in this field.
specs
A pointer to an array of FSSpec
structures. On input, you should pass a pointer to maximumItems
file system specifications. On return, actualItems
FSSpec
structures will be filled in. If you do not wish any FSSpec
information to be returned, pass a NULL
pointer in this field.
names
A pointer to an array of Unicode names. On input, you should pass a pointer to an array of maximumItems
HFSUniStr255
structures. On return, actualItems
structures will contain Unicode names. If you do not wish any file or directory names to be returned, pass a NULL
pointer in this field.
searchParams
A pointer to an FSSearchParams
structure, specifying the values to match against.
Files.h
Holds basic information about a file or directory.
struct FSCatalogInfo { UInt16 nodeFlags; FSVolumeRefNum volume; UInt32 parentDirID; UInt32 nodeID; UInt8 sharingFlags; UInt8 userPrivileges; UInt8 reserved1; UInt8 reserved2; UTCDateTime createDate; UTCDateTime contentModDate; UTCDateTime attributeModDate; UTCDateTime accessDate; UTCDateTime backupDate; UInt32 permissions[4]; UInt8 finderInfo[16]; UInt8 extFinderInfo[16]; UInt64 dataLogicalSize; UInt64 dataPhysicalSize; UInt64 rsrcLogicalSize; UInt64 rsrcPhysicalSize; UInt32 valence; TextEncoding textEncodingHint; }; typedef struct FSCatalogInfo FSCatalogInfo; typedef FSCatalogInfo * FSCatalogInfoPtr;
nodeFlags
Node flags. This field has two defined bits that indicate whether an object is a file or folder, and whether a file is locked (constants kFSNodeIsDirectoryMask
and kFSNodeLockedMask
). See “Catalog Information Node Flags” for the values you can use here.
volume
The object's volume reference.
parentDirID
The ID of the directory that contains the given object. The root directory of a volume always has ID fsRtDirID
(2); the parent of the root directory is ID fsRtParID
(1). Note that there is no object with ID fsRtParID
; this is merely used when the File Manager is asked for the parent of the root directory.
nodeID
The file or directory ID.
sharingFlags
The object’s sharing flags. See “Catalog Information Sharing Flags ” for the meaning of the bits defined for this field.
userPrivileges
The user's effective AFP privileges (same as ioACUser
in the old HFileInfo
and DirInfo
structures). See “User Privileges Constants.”
reserved1
Reserved.
reserved2
Reserved.
createDate
The date and time of the creation of the object. Note that file systems other than AFP, HFS and HFS Plus do not generally support creation dates. For file systems which do not support creation dates, FSGetCatalogInfo
, PBGetCatalogInfoSync
, and PBGetCatalogInfoAsync
return 0 in this field.
contentModDate
The date and time that the data or resource fork was last modified.
attributeModDate
The date and time that an attribute of the object (such as a fork other than the data or resource fork) was last modified.
accessDate
The date and time that the object was last accessed. The Mac OS 9 File Manager does not automatically update the accessDate
field; it exists primarily for use by other operating systems (notably Mac OS X).
backupDate
The date and time of the object’s last backup. This field is not updated by the File Manager a backup utility may use this field if it wishes. Note that file systems other than AFP, HFS and HFS Plus do not generally support backup dates. For file systems which do not support backup dates, FSGetCatalogInfo
, PBGetCatalogInfoSync
, and PBGetCatalogInfoAsync
return 0 in this field.
permissions
User and group permission information. The Mac OS 8 and 9 File Manager does not use or enforce this permission information. It could be used by a file server program or other operating system (primarily Mac OS X). In Mac OS X, this array contains the file system permissions of the returned item. To use this information, coerce the parameter to a FSPermissionInfo
structure.
finderInfo
Basic Finder information for the object. This information is available in the catalog information, instead of in a named fork, for historical reasons. The File Manager does not interpret the contents of these fields. To use this information, coerce the parameter to a FileInfo
or FolderInfo
structure.
extFinderInfo
Extended Finder information for the object. This information is available in the catalog information, instead of in a named fork, for historical reasons. The File Manager does not interpret the contents of these fields. To use this information, coerce the parameter to an ExtendedFileInfo
or ExtendedFolderInfo
structure.
dataLogicalSize
The size of the data fork in bytes (the fork’s logical size). The information in this field is only valid for files do not rely upon the value returned in this field for folders.
dataPhysicalSize
The amount of disk space, in bytes, occupied by the data fork (the fork’s physical size). The information in this field is only valid for files do not rely upon the value returned in this field for folders.
rsrcLogicalSize
The size of the resource fork (the fork’s logical size). The information in this field is only valid for files do not rely upon the value returned in this field for folders.
rsrcPhysicalSize
The amount of disk space occupied by the resource fork (the fork’s physical size). The information in this field is only valid for files do not rely upon the value returned in this field for folders.
valence
For folders only, the number of items (files plus directories) contained within the directory. For files, it is set to zero. Many volume formats do not store a field containing a directory’s valence. For those volume formats, this field is very expensive to compute. Think carefully before you ask the File Manager to return this field.
textEncodingHint
The textEncodingHint
field is used in conjunction with the Unicode filename of the object. It is an optional hint that can be used by the volume format when converting the Unicode to some other encoding. For example, HFS Plus stores this value and uses it when converting the name to a Mac OS encoding, such as when the name is returned by PBGetCatInfoSync
or PBGetCatInfoAsync
. As another example, HFS volumes use this value to convert the Unicode name to a Mac OS encoded name stored on disk. If the entire Unicode name can be converted to a single Mac OS encoding, then that encoding should be used as the textEncodingHint
; otherwise, a text encoding corresponding to the first characters of the name will probably provide the best user experience.
If a textEncodingHint
is not supplied when a file or directory is created or renamed, the volume format will use a default value. This default value may not be the best possible choice for the given filename. Whenever possible, a client should supply a textEncodingHint
.
The FSCatalogInfoBitmap
type is used to indicate which fields of the FSCatalogInfo
should be set or retrieved. If the bit corresponding to a particular field is not set, then that field is not changed if the FSCatalogInfo
is an output parameter, and that field is ignored if the FSCatalogInfo
is an input parameter.
Files.h
Describes which fields of the FSCatalogInfo
structure you wish to retrieve or set.
typedef UInt32 FSCatalogInfoBitmap;
If the bit corresponding to a particular field is not set in the bitmap, then that field is not changed in the FSCatalogInfo
structure if it is an output parameter, and that field is ignored if the FSCatalogInfo
structure is an input parameter. See “Catalog Information Bitmap Constants” for a description of the constants you should use with this data type.
Files.h
typedef UInt32 FSEjectStatus;
Files.h
Specifies user-defined data and callbacks associated with an asynchronous file operation.
struct FSFileOperationClientContext { CFIndex version; void *info; CFAllocatorRetainCallBack retain; CFAllocatorReleaseCallBack release; CFAllocatorCopyDescriptionCallBack copyDescription; }; typedef struct FSFileOperationClientContext FSFileOperationClientContext;
version
The version number of the structure; this field should always contain 0.
info
A generic pointer to your user-defined data. This pointer is passed back to your application when you check the status of the file operation. There are two ways you can ask the File Manager for status information about a file operation: by supplying a status callback function when you start the operation, or by calling a file operation status function directly.
retain
An optional callback function that the File Manager can use to retain the user-defined data specified in the info
parameter. If your data is a Core Foundation object, you can simply specify the function CFRetain
. If no callback is needed, set this field to NULL
.
release
An optional callback function that the File Manager can use to release the user-defined data specified in the info
parameter. If your data is a Core Foundation object, you can simply specify the function CFRelease
. If no callback is needed, set this field to NULL
.
copyDescription
An optional callback function that the File Manager can use to create a descriptive string representation of your user-defined data for debugging purposes. If no callback is needed, set this field to NULL
.
You supply a client context when calling functions such as FSCopyObjectAsync
or FSMoveObjectAsync
that start an asynchronous copy or move operation.
Files.h
Defines an opaque type that represents an asynchronous file operation.
typedef struct __FSFileOperation * FSFileOperationRef;
You supply a file operation object when calling functions such as FSCopyObjectAsync
or FSMoveObjectAsync
to start an asynchronous copy or move operation. You can also use a file operation object to check the status of a file operation or to cancel the operation.
To perform an asynchronous file operation:
Create a file operation object using the function FSFileOperationCreate
.
Pass the object to the function FSFileOperationScheduleWithRunLoop
to schedule the operation.
Pass the object to one of the asynchronous file operation functions to start the operation.
The FSFileOperationRef
opaque type is a standard Core Foundation data type. It is derived from CFType and inherits the properties that all Core Foundation types have in common. For more information, see CFType Reference.
Files.h
Defines a parameter block used by low-level HFS Plus fork control block functions.
struct FSForkCBInfoParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; SInt16 desiredRefNum; SInt16 volumeRefNum; SInt16 iterator; SInt16 actualRefNum; FSRef * ref; FSForkInfo * forkInfo; HFSUniStr255 * forkName; }; typedef struct FSForkCBInfoParam FSForkCBInfoParam; typedef FSForkCBInfoParam * FSForkCBInfoParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
desiredRefNum
A fork reference number.
volumeRefNum
The volume reference number of the volume to match, or zero to match all volumes.
iterator
An iterator. Set to zero to start iteration.
actualRefNum
On return, the actual fork reference number found.
ref
A pointer to an FSRef
for the specified fork.
forkInfo
A pointer to a fork information structure, FSForkInfo
.
forkName
A pointer to the fork’s Unicode name.
Files.h
Contains information about an open fork.
struct FSForkInfo { SInt8 flags; SInt8 permissions; FSVolumeRefNum volume; UInt32 reserved2; UInt32 nodeID; UInt32 forkID; UInt64 currentPosition; UInt64 logicalEOF; UInt64 physicalEOF; UInt64 process; }; typedef struct FSForkInfo FSForkInfo; typedef FSForkInfo * FSForkInfoPtr;
flags
Flags describing the status of the fork. See “FCB Flags” for a description of the bits in this field.
permissions
User and group permission information.
volume
A volume specification. This can be a volume reference number, drive number, or 0 for the default volume.
reserved2
Reserved.
nodeID
The file or directory ID of the file or directory with which the fork is associated.
forkID
The fork ID.
currentPosition
The current position within the fork.
logicalEOF
The logical size of the fork.
physicalEOF
The physical size of the fork.
process
The process which opened the fork.
This data type is used in the forkInfo
parameter of the FSGetForkCBInfo
function, and in the forkInfo
field of the FSForkCBInfoParam
parameter block passed to the PBGetForkCBInfoSync
and PBGetForkCBInfoAsync
functions. When these functions return, the FSForkInfo
structure contains information about the specified open fork.
Files.h
Defines a parameter block used by low-level HFS Plus fork I/O functions.
struct FSForkIOParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; void * reserved1; SInt16 reserved2; SInt16 forkRefNum; UInt8 reserved3; SInt8 permissions; const FSRef * ref; Ptr buffer; UInt32 requestCount; UInt32 actualCount; UInt16 positionMode; SInt64 positionOffset; FSAllocationFlags allocationFlags; UInt64 allocationAmount; UniCharCount forkNameLength; const UniChar * forkName; CatPositionRec forkIterator; HFSUniStr255 * outForkName; }; typedef struct FSForkIOParam FSForkIOParam; typedef FSForkIOParam * FSForkIOParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
reserved1
Reserved.
reserved2
Reserved.
forkRefNum
A reference number for a fork.
reserved3
Reserved.
permissions
The desired type of access to the specified fork. See “File Access Permission Constants” for a description of the types of access that you can request.
ref
An FSRef
for the file or directory to open.
buffer
A pointer to a data buffer.
requestCount
The number of bytes requested for the given operation.
actualCount
The actual number of bytes completed by the call.
positionMode
A constant indicating the base location within the file for the start of the operation. See “Position Mode Constants” for the meaning of the constants you can use in this field.
positionOffset
The offset from the base location specified in the positionMode
offset for the start of the operation.
allocationFlags
A set of bit flags used by the FSAllocateFork
function to control how space is allocated. See “Allocation Flags” for a description of the defined flags.
allocationAmount
For the FSAllocateFork
function, the amount of space, in bytes, to allocate.
forkNameLength
The length of the file or directory name passed in the forkName
field, in Unicode characters.
forkName
A pointer to the file or directory’s Unicode name. This field is an input parameter functions which return the file or directory name in the parameter block use the outForkName
field.
forkIterator
A fork iterator.
outForkName
A pointer to the file or directory’s Unicode name this is an output parameter. For functions which require the file or directory name as an input argument, you should pass a pointer to that name in the forkName
field and pass the length of the name in the forkNameLength
field.
Files.h
Refers to a position within the catalog, used when iterating over files and folders in a directory.
typedef struct OpaqueFSIterator * FSIterator;
This data type is like a file reference number because it maintains state internally to the File Manager and must be explicitly opened and closed.
An FSIterator
is returned by FSOpenIterator
and is passed as input to FSGetCatalogInfoBulk
, FSCatalogSearch
and FSCloseIterator
.
Files.h
typedef UInt32 FSMountStatus;
Files.h
struct FSPermissionInfo { UInt32 userID; UInt32 groupID; UInt8 reserved1; UInt8 userAccess; UInt16 mode; UInt32 reserved2; }; typedef struct FSPermissionInfo FSPermissionInfo;
Files.h
Defines a parameter block for use with 64-bit range locking functions.
struct FSRangeLockParam { QElemPtr qLink; SInt16 qType; SInt16 ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; FSIORefNum forkRefNum; UInt64 requestCount; UInt16 positionMode; SInt64 positionOffset; UInt64 rangeStart; }; typedef struct FSRangeLockParam FSRangeLockParam;
Files.h
Defines a pointer to a range lock parameter block.
typedef FSRangeLockParam *FSRangeLockParamPtr;
Files.h
Identifies a directory or file, including a volume’s root directory.
struct FSRef { UInt8 hidden[80]; }; typedef struct FSRef FSRef; typedef FSRef * FSRefPtr;
This data type’s purpose is similar to an FSSpec
except that an FSRef
is completely opaque. An FSRef
contains whatever information is needed to find the given object; the internal structure of an FSRef
is likely to vary based on the volume format, and may vary based on the particular object being identified.
The client of the File Manager cannot examine the contents of an FSRef
to extract information about the parent directory or the object’s name. Similarly, an FSRef
cannot be constructed directly by the client; the FSRef
must be constructed and returned via the File Manager. There is no need to call the File Manager to dispose an FSRef
.
To determine the volume, parent directory and name associated with an FSRef
, or to get an equivalent FSSpec
, use the FSGetCatalogInfo
call.
Files.h
Defines a parameter block used by low-level HFS Plus functions.
struct FSRefParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; ConstStringPtr ioNamePtr; short ioVRefNum; SInt16 reserved1; UInt8 reserved2; UInt8 reserved3; const FSRef * ref; FSCatalogInfoBitmap whichInfo; FSCatalogInfo * catInfo; UniCharCount nameLength; const UniChar * name; long ioDirID; FSSpec * spec; FSRef * parentRef; FSRef * newRef; TextEncoding textEncodingHint; HFSUniStr255 * outName; }; typedef struct FSRefParam FSRefParam; typedef FSRefParam * FSRefParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—you should set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, or 0 for the default volume.
reserved1
Reserved.
reserved2
Reserved.
reserved3
Reserved.
ref
The FSRef
describing the file or directory which is the target of the call.
whichInfo
An FSCatalogInfoBitmap
which describes the fields of the catalog information structure passed in the catInfo
field which are to be retrieved or set.
catInfo
A catalog information structure containing information about the specified file or directory.
nameLength
The length of the file or directory’s name, for the PBCreateSync
, PBCreateAsync
, PBRenameSync
, and PBRenameAsync
functions.
name
A pointer to the file or directory’s Unicode name, for the PBCreateSync
, PBCreateAsync
, PBRenameSync
, and PBRenameAsync
functions.
ioDirID
The directory ID of the specified file or directory’s parent directory.
spec
The target or source FSRef
.
parentRef
The secondary or destination FSRef
. (Or the ref of the directory to move another file or directory to).
newRef
The output FSRef
(ie, a new FSRef
).
textEncodingHint
A text encoding hint for the file or directory’s Unicode name, used by the PBMakeFSRefSync
, PBMakeFSRefAsync
, PBRenameSync
, and PBRenameAsync
functions.
outName
On output, a pointer to the Unicode name of the file or directory, used by the PBGetCatalogInfoSync
and PBGetCatalogInfoAsync
functions.
Files.h
Describes the search criteria for a catalog information search.
struct FSSearchParams { Duration searchTime; OptionBits searchBits; UniCharCount searchNameLength; const UniChar * searchName; FSCatalogInfo * searchInfo1; FSCatalogInfo * searchInfo2; }; typedef struct FSSearchParams FSSearchParams; typedef FSSearchParams * FSSearchParamsPtr;
searchTime
A Time Manager duration for the duration of the search. If you specify a non-zero value in this field, the search may terminate after the specified time, even if the maximum number of requested objects has not been returned and the entire catalog has not been scanned.
If this value is negative, the time is interpreted in microseconds; if positive, it is interpreted as milliseconds. If searchTime
is zero, there is no time limit on the search.
searchBits
A set of bits specifying which catalog information fields to search on. See “Catalog Search Constants” for the constants which you can use here.
searchNameLength
The length of the Unicode name to search by.
searchName
A pointer to the Unicode name to search by.
searchInfo1
An FSCatalogInfo
structure which specifies the values and lower bounds of a search.
searchInfo2
A FSCatalogInfo
structure which specifies the masks and upper bounds of a search.
Used by FSCatalogSearch
, PBCatalogSearchSync
, and PBCatalogSearchAsync
to specify the criteria for a catalog search.
Files.h
Specifies the name and location of a file or directory.
struct FSSpec { short vRefNum; long parID; StrFileName name; }; typedef struct FSSpec FSSpec; typedef FSSpec * FSSpecPtr;
vRefNum
The volume reference number of the volume containing the specified file or directory.
parID
The parent directory ID of the specified file or directory (the directory ID of the directory containing the given file or directory).
name
The name of the specified file or directory. In Carbon, this name must be a leaf name; the name cannot contain a semicolon.
The FSSpec
structure can describe only a file or a directory, not a volume. A volume can be identified by its root directory, although the system software never uses an FSSpec
structure to describe a volume. The directory ID of the root’s parent directory is fsRtParID
. The name of the root directory is the same as the name of the volume.
If you need to convert a file specification into an FSSpec
structure, call the function FSMakeFSSpec
. Do not fill in the fields of an FSSpec
structure yourself.
Files.h
Defines a pointer to an array of FSSpec
structures.
typedef FSSpecPtr FSSpecArrayPtr;
See FSSpec
.
Files.h
typedef UInt32 FSUnmountStatus;
Files.h
typedef FSVolumeEjectProcPtr FSVolumeEjectUPP;
For more information, see the description of the FSVolumeEjectProcPtr
callback function.
Files.h
Used when getting or setting information about a volume.
struct FSVolumeInfo { UTCDateTime createDate; UTCDateTime modifyDate; UTCDateTime backupDate; UTCDateTime checkedDate; UInt32 fileCount; UInt32 folderCount; UInt64 totalBytes; UInt64 freeBytes; UInt32 blockSize; UInt32 totalBlocks; UInt32 freeBlocks; UInt32 nextAllocation; UInt32 rsrcClumpSize; UInt32 dataClumpSize; UInt32 nextCatalogID; UInt8 finderInfo[32]; UInt16 flags; UInt16 filesystemID; UInt16 signature; UInt16 driveNumber; short driverRefNum; }; typedef struct FSVolumeInfo FSVolumeInfo; typedef FSVolumeInfo * FSVolumeInfoPtr;
createDate
The date and time the volume was created. A value of 0 means that the volume creation date is unknown.
modifyDate
The last time when the volume was modified in any way. A value of 0 means “never” or “unknown.
backupDate
Indicates when the volume was last backed up. This field is for use by backup utilities. A value of 0 means “never” or “unknown.
checkedDate
The last date and time that the volume was checked for consistency. A value of 0 means “never” or “unknown.
fileCount
The total number of files on the volume, or 0 if unknown.
folderCount
The total number of folders on the volume, or 0 if unknown. Note that no root directory counts.
totalBytes
The size of the volume in bytes.
freeBytes
The number of bytes of free space on the volume.
blockSize
The size of an allocation block, in bytes. This field is only appropriate for volume formats (such as HFS and HFS Plus) that allocate space in fixed-size pieces; other volume formats may not have a similar concept, and may set this field to zero.
totalBlocks
The total number of allocation blocks on the volume. This field is only appropriate for volume formats (such as HFS and HFS Plus) that allocate space in fixed-size pieces; other volume formats may not have a similar concept, and may set this field to zero.
freeBlocks
The number of unused allocation blocks on the volume. This field is only appropriate for volume formats (such as HFS and HFS Plus) that allocate space in fixed-size pieces; other volume formats may not have a similar concept, and may set this field to zero.
nextAllocation
A hint for where to start searching for free space during an allocation. This field is only appropriate for volume formats (such as HFS and HFS Plus) that allocate space in fixed-size pieces; other volume formats may not have a similar concept, and may set this field to zero.
rsrcClumpSize
Default resource fork clump size. When a fork is automatically grown as it is written, the File Manager attempts to allocate space that is a multiple of the clump size. This field is zero for volume formats that don’t support the notion of a clump size.
dataClumpSize
Default data fork clump size. When a fork is automatically grown as it is written, the File Manager attempts to allocate space that is a multiple of the clump size. This field is zero for volume formats that don’t support the notion of a clump size.
nextCatalogID
The next unused catalog node ID. Some volume formats (such as HFS and HFS Plus) use a monotonically increasing number for the catalog node ID (i.e. File ID or Directory ID) of newly created files and directories. For those volume formats, the nextCatalogID
is the next file/directory ID that will be assigned. For other volume formats, this field will be zero.
finderInfo
Information used by Finder, such as the Directory ID of the System Folder. Some volume formats do not support Finder information for a volume and will set this field to all zeroes.
flags
This field contains bit flags holding information about the volume. See “Volume Information Flags” for the attribute constants you can use here.
filesystemID
Identifies the filesystem implementation that is handling the volume; this is zero for HFS and HFS Plus volumes.
signature
This field is used to distinguish between volume formats supported by a single filesystem implementation.
driveNumber
The drive number for the drive (drive queue element) associated with the volume. Mac OS X does not support drive numbers; in Mac OS X, the File Manager always returns a value of 1 in this field.
driverRefNum
The driver reference number for the drive (drive queue element) associated with the volume.
This structure contains information about a volume as a whole information about a volume’s root directory would use the FSCatalogInfo
structure.
Files.h
Describes which fields of the FSVolumeInfo
structure you wish to retrieve or set.
typedef UInt32 FSVolumeInfoBitmap;
If the bit corresponding to a particular field is not set in the bitmap, then that field is not changed in the FSVolumeInfo
structure if it is an output parameter, and that field is ignored if the FSVolumeInfo
structure is an input parameter. See “Volume Information Bitmap Constants” for a description of the constants you should use with this data type.
Files.h
Defines a parameter block used by low-level HFS Plus volume manipulation functions.
struct FSVolumeInfoParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; FSVolumeRefNum ioVRefNum; UInt32 volumeIndex; FSVolumeInfoBitmap whichInfo; FSVolumeInfo * volumeInfo; HFSUniStr255 * volumeName; FSRef * ref; }; typedef struct FSVolumeInfoParam FSVolumeInfoParam; typedef FSVolumeInfoParam * FSVolumeInfoParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a volume name. This field is unused.
ioVRefNum
The volume reference number.
volumeIndex
The volume index. If this field is 0, the value in the ioVRefNum
field only is used to identify the target volume.
whichInfo
A bitmap indicating which volume information fields to retrieve or set in the FSVolumeInfo
structure passed in the volumeInfo
field. See “Volume Information Bitmap Constants” for the meaning of the bits in this field.
volumeInfo
A pointer to a volume information structure containing the requested volume information on return, or the new values of the volume information to set on input. See FSVolumeInfo
.
volumeName
On output, a pointer to the volume’s name.
ref
A pointer to an FSRef
for the specified volume’s root directory.
Files.h
typedef FSVolumeMountProcPtr FSVolumeMountUPP;
For more information, see the description of the FSVolumeMountProcPtr
callback function.
Files.h
typedef struct OpaqueFSVolumeOperation * FSVolumeOperation;
Files.h
Identifies a particular mounted volume.
typedef SInt16 FSVolumeRefNum;
This data type is the same as the 16-bit volume refnum previously passed in the ioVRefNum
fields of a parameter block; this is simply a new type name for the old data type.
Files.h
typedef FSVolumeUnmountProcPtr FSVolumeUnmountUPP;
For more information, see the description of the FSVolumeUnmountProcPtr
callback function.
Files.h
Defines a volume attributes buffer, used by the PBHGetVolParmsSync
and PBHGetVolParmAsync
functions to return volume information.
struct GetVolParmsInfoBuffer { short vMVersion; long vMAttrib; Handle vMLocalHand; long vMServerAdr; long vMVolumeGrade; short vMForeignPrivID; long vMExtendedAttributes; void * vMDeviceID; UniCharCount vMMaxNameLength; }; typedef struct GetVolParmsInfoBuffer GetVolParmsInfoBuffer;
vMVersion
The version number of the attributes buffer structure. Currently this field returns 1, 2, 3 or 4. Version 3 is introduced to support the HFS Plus APIs.
vMAttrib
A 32-bit quantity that encodes information about the volume attributes. See “Volume Attribute Constants” for the meaning of the bits in this field.
vMLocalHand
A handle to private data for shared volumes. On creation of the VCB (right after mounting), this field is a handle to a 2-byte block of memory. The Finder uses this for its local window list storage, allocating and deallocating memory as needed. It is disposed of when the volume is unmounted. Your application should treat this field as reserved.
vMServerAdr
For AppleTalk server volumes, this field contains the internet address of an AppleTalk server volume. Your application can inspect this field to tell which volumes belong to which server; the value of this field is 0 if the volume does not have a server.
vMVolumeGrade
The relative speed rating of the volume. The scale used to determine these values is currently uncalibrated. In general, lower values indicate faster speeds. A value of 0 indicates that the volume’s speed is unrated. The buffer version returned in the vMVersion
field must be greater than 1 for this field to be meaningful.
vMForeignPrivID
An integer representing the privilege model supported by the volume. Currently two values are defined for this field: 0 represents a standard HFS or HFS Plus volume that might or might not support the AFP privilege model; fsUnixPriv
represents a volume that supports the A/UX privilege model. The buffer version returned in the vMVersion
field must be greater than 1 for this field to be meaningful.
vMExtendedAttributes
Contains bits that describe a volume’s extended attributes. For this field to be meaningful, the vMVersion
must be greater than 2. See “Extended Volume Attributes” for the meaning of the bits in this field.
vMDeviceID
A device name identifying the device in /dev that corresponds to the volume. You can use this string to build a POSIX path to the device for use with IOKit APIs.
vMMaxNameLength
Volumes that implement the HFS Plus APIs must use version 3 (or newer) of the GetVolParmsInfoBuffer
. Volumes that don’t implement the HFS Plus APIs may still implement version 3 of the GetVolParmsInfoBuffer
. If the version of the GetVolParmsInfoBuffer
is 2 or less, or the bSupportsHFSPlusAPIs
bit is clear (zero), then the volume does not implement the HFS Plus APIs, and they are being emulated for that volume by the File Manager itself.
If a volume does not implement the HFS Plus APIs, and supports version 2 or earlier of the GetVolParmsInfoBuffer
, it cannot itself describe whether it supports the FSCatalogSearch
or FSExchangeObjects
calls. The compatibility layer will implement the FSCatalogSearch
call if the volume supports the PBCatSearch
call (i.e. the bHasCatSearch
bit of vMAttrib
is set). The compatibility layer will implement the FSExchangeObjects
call if the volume supports PBExchangeFiles
(i.e. the bHasFileIDs
bit of vMAttrib
is set).
Files.h
Defines a structure which holds catalog information about a file.
struct HFileInfo { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short ioFRefNum; SInt8 ioFVersNum; SInt8 filler1; short ioFDirIndex; SInt8 ioFlAttrib; SInt8 ioACUser; FInfo ioFlFndrInfo; long ioDirID; unsigned short ioFlStBlk; long ioFlLgLen; long ioFlPyLen; unsigned short ioFlRStBlk; long ioFlRLgLen; long ioFlRPyLen; unsigned long ioFlCrDat; unsigned long ioFlMdDat; unsigned long ioFlBkDat; FXInfo ioFlXFndrInfo; long ioFlParID; long ioFlClpSiz; }; typedef struct HFileInfo HFileInfo;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
ioFRefNum
The file reference number of an open file.
ioFVersNum
A file version number. This field is no longer used. File version numbers are an artifact of the obsolete MFS, and are not supported on HFS volumes. You should always set this field to 0.
filler1
Reserved.
ioFDirIndex
A file and directory index. If this field contains a positive number, PBGetCatInfoSync
and PBGetCatInfoAsync
return information about the file or directory having that directory index in the directory specified by the ioVRefNum
field. (If ioVRefNum
contains a volume reference number, the specified directory is that volume’s root directory.)
If this field contains 0, PBGetCatInfoSync
or PBGetCatInfoAsync
returns information about the file or directory whose name is specified in the ioNamePtr
field and that is located in the directory specified by the ioVRefNum
field. (Once again, if ioVRefNum
contains a volume reference number, the specified directory is that volume’s root directory.)
If this field contains a negative number, PBGetCatInfoSync
or PBGetCatInfoAsync
ignores the ioNamePtr
field and returns information about the directory specified in the ioDirID
field. If both ioDirID
and ioVRefNum
are set to 0, PBGetCatInfoSync
or PBGetCatInfoAsync
returns information about the current default directory.
ioFlAttrib
File or directory attributes. See “File Attribute Constants” for the meaning of the bits in this field.
ioACUser
The user’s access rights for the specified directory. See “User Privileges Constants” for the meaning of the bits in this field.
ioFlFndrInfo
Finder information.
ioDirID
A directory ID or file ID. On input to PBGetCatInfoSync
or PBGetCatInfoAsync
, this field contains a directory ID (which is used only if the ioFDirIndex
field is negative). On output, this field contains the file ID of the specified file.
ioFlStBlk
The first allocation block of the data fork. This field contains 0 if the file’s data fork is empty.
ioFlLgLen
The logical length (logical end-of-file) of the data fork.
ioFlPyLen
The physical length (physical end-of-file) of the data fork.
ioFlRStBlk
The first allocation block of the resource fork.
ioFlRLgLen
The logical length (logical end-of-file) of the resource fork.
ioFlRPyLen
The physical length (physical end-of-file) of the resource fork.
ioFlCrDat
The date and time of the file’s creation, in seconds since midnight, January 1, 1904. However, on Mac OS X, if you set the creation date to a date between January 1, 1904 and January 1, 1970, it will be clipped to January 1, 1970, and that is the value which will be returned if you later try to retrieve the creation date.
Note that file systems other than AFP, HFS and HFS Plus do not generally support creation dates.
ioFlMdDat
The date and time of the last modification to the file, in seconds since midnight, January 1, 1904. However, on Mac OS X, if you set the modification date to a date between January 1, 1904 and January 1, 1970, it will be clipped to January 1, 1970.
ioFlBkDat
The date and time that the file was last backed up, in seconds since midnight, January 1, 1904. However, on Mac OS X, if you set the backup date to a date between January 1, 1904 and January 1, 1970, it will be clipped to January 1, 1970.
Note that file systems other than AFP, HFS and HFS Plus do not generally support backup dates.
ioFlXFndrInfo
Additional Finder information.
ioFlParID
The directory ID of the file’s parent directory.
ioFlClpSiz
The clump size to be used when writing the file if it’s 0, the volume’s clump size is used when the file is opened.
Files.h
Defines a parameter block used by low-level HFS functions for file creation, deletion, and information retrieval.
struct HFileParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short ioFRefNum; SInt8 ioFVersNum; SInt8 filler1; short ioFDirIndex; SInt8 ioFlAttrib; SInt8 ioFlVersNum; FInfo ioFlFndrInfo; long ioDirID; unsigned short ioFlStBlk; long ioFlLgLen; long ioFlPyLen; unsigned short ioFlRStBlk; long ioFlRLgLen; long ioFlRPyLen; unsigned long ioFlCrDat; unsigned long ioFlMdDat; }; typedef struct HFileParam HFileParam; typedef HFileParam * HFileParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
ioFRefNum
The file reference number of an open file.
ioFVersNum
A file version number. This field is no longer used. File version numbers are an artifact of the obsolete MFS, and are not supported on HFS volumes. You should always set this field to 0.
filler1
Reserved.
ioFDirIndex
A directory index for use with the PBHGetFInfoSync
and PBHGetFInfoAsync
functions.
ioFlAttrib
File attributes. See “File Attribute Constants” for the meaning of the bits in this field.
ioFlVersNum
A file version number. This feature is no longer supported, and you must always set this field to 0.
ioFlFndrInfo
Information used by the Finder.
ioDirID
A directory ID.
ioFlStBlk
The first allocation block of the data fork. This field contains 0 if the file’s data fork is empty.
ioFlLgLen
The logical length (logical end-of-file) of the data fork.
ioFlPyLen
The physical length (physical end-of-file) of the data fork.
ioFlRStBlk
The first allocation block of the resource fork. This field contains 0 if the file’s resource fork is empty.
ioFlRLgLen
The logical length (logical end-of-file) of the resource fork.
ioFlRPyLen
The physical length (physical end-of-file) of the resource fork.
ioFlCrDat
The date and time of the file’s creation, specified in seconds since midnight, January 1, 1904.
ioFlMdDat
The date and time of the last modification to the file, specified in seconds since midnight, January 1, 1904.
Files.h
Used by the File Manager to return Unicode strings.
struct HFSUniStr255 { UInt16 length; UniChar unicode[255]; }; typedef struct HFSUniStr255 HFSUniStr255;
length
The number of unicode characters in the string.
unicode
The string, in unicode characters.
This data type is a string of up to 255 16-bit Unicode characters, with a preceding 16-bit length (number of characters). Note that only the first length characters have meaningful values; the remaining characters may be set to arbitrary values. A caller should always assume that the entire structure will be modified, even if the actual string length is less than 255.
Files.h
Defines a parameter block used by low-level HFS I/O functions.
struct HIOParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short ioRefNum; SInt8 ioVersNum; SInt8 ioPermssn; Ptr ioMisc; Ptr ioBuffer; long ioReqCount; long ioActCount; short ioPosMode; long ioPosOffset; }; typedef struct HIOParam HIOParam; typedef HIOParam * HIOParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
ioRefNum
The file reference number of an open file.
ioVersNum
A version number. This field is no longer used and you should always set it to 0.
ioPermssn
The access mode. See “File Access Permission Constants.”
ioMisc
Depending on the function called, this field contains either a logical end-of-file, a new version number, a pointer to an access path buffer, or a pointer to a new pathname. Because ioMisc
is of type Ptr
, you’ll need to perform type coercion to interpret the value of ioMisc
correctly when it contains an end-of-file (a LongInt
value) or version number (a SignedByte
value).
ioBuffer
A pointer to a data buffer into which data is written by PBReadSync
and PBReadAsync
calls, and from which data is read by PBWriteSync
and PBWriteAsync
calls.
ioReqCount
The requested number of bytes to be read, written, or allocated.
ioActCount
The number of bytes actually read, written, or allocated.
ioPosMode
The positioning mode (base location) for setting the mark. Bits 0 and 1 of this field indicate how to position the mark; you can use the constants described in “Position Mode Constants” to set or test their value.
You can also use the constants described in “Cache Constants” to indicate whether or not to cache the data.
ioPosOffset
The offset to be used in conjunction with the base location specified in the ioPosMode
field.
Files.h
Describes the HFS parameter block.
union HParamBlockRec { HIOParam ioParam; HFileParam fileParam; HVolumeParam volumeParam; AccessParam accessParam; ObjParam objParam; CopyParam copyParam; WDParam wdParam; FIDParam fidParam; CSParam csParam; ForeignPrivParam foreignPrivParam; }; typedef union HParamBlockRec HParamBlockRec; typedef HParamBlockRec * HParmBlkPtr;
ioParam
A parameter block used by low-level HFS I/O functions. See HIOParam
.
fileParam
A parameter block used by low-level HFS functions for file creation, deletion, and information retrieval. See HFileParam
.
volumeParam
A parameter block used by low-level HFS volume manipulation functions. See HVolumeParam
.
accessParam
A parameter block used by low-level HFS file and directory access rights manipulation functions. See AccessParam
.
objParam
A parameter block used by low-level HFS user and group information functions. See ObjParam
.
copyParam
A parameter block used by low-level HFS file copying functions. See CopyParam
.
wdParam
A parameter block used by low-level HFS working directory functions. See WDParam
.
fidParam
A parameter block used by low-level HFS file ID functions. See FIDParam
.
csParam
A parameter block used by low-level HFS catalog search functions. See CSParam
.
foreignPrivParam
A parameter block used by low-level HFS foreign privileges functions. See ForeignPrivParam
.
Files.h
Defines a parameter block used by low-level HFS volume manipulation functions.
struct HVolumeParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; long filler2; short ioVolIndex; unsigned long ioVCrDate; unsigned long ioVLsMod; short ioVAtrb; unsigned short ioVNmFls; unsigned short ioVBitMap; unsigned short ioAllocPtr; unsigned short ioVNmAlBlks; unsigned long ioVAlBlkSiz; unsigned long ioVClpSiz; unsigned short ioAlBlSt; unsigned long ioVNxtCNID; unsigned short ioVFrBlk; unsigned short ioVSigWord; short ioVDrvInfo; short ioVDRefNum; short ioVFSID; unsigned long ioVBkUp; short ioVSeqNum; unsigned long ioVWrCnt; unsigned long ioVFilCnt; unsigned long ioVDirCnt; long ioVFndrInfo[8]; }; typedef struct HVolumeParam HVolumeParam; typedef HVolumeParam * HVolumeParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
filler2
Reserved.
ioVolIndex
A volume index for use with the PBHGetVInfoSync
and PBHGetVInfoAsync
functions.
ioVCrDate
The date and time of the volume’s initialization.
ioVLsMod
The date and time the volume information was last modified. (This field is not changed when information is written to a file and does not necessarily indicate when the volume was flushed.
ioVAtrb
The volume attributes. See “Volume Information Attribute Constants” for the meanings of the bits in this field.
ioVNmFls
The number of files in the root directory of the volume. For performance reasons, the Carbon File Manager does not return the number of files in this field; instead, it sets ioVNmFls
to 0.
To determine the number of files in the root directory of a volume in Carbon, call PBGetCatInfoAsync
or PBGetCatInfoSync
for the root directory. The number of files in the root directory is returned in the ioDrNmFls
field.
ioVBitMap
The first block of the volume bitmap.
ioAllocPtr
The block at which the next new file starts. Used internally.
ioVNmAlBlks
The number of allocation blocks.
ioVAlBlkSiz
The size of allocation blocks.
ioVClpSiz
The clump size.
ioAlBlSt
The first block in the volume map.
ioVNxtCNID
The next unused catalog node ID.
ioVFrBlk
The number of unused allocation blocks.
ioVSigWord
A signature word identifying the type of volume it’s $D2D7 for MFS volumes and $4244 for volumes that support HFS calls.
ioVDrvInfo
The drive number of the drive containing the volume.
ioVDRefNum
For online volumes, the reference number of the I/O driver for the drive identified by the ioVDrvInfo
field.
ioVFSID
The file-system identifier. It indicates which file system is servicing the volume it’s zero for File Manager volumes and nonzero for volumes handled by an external file system.
ioVBkUp
The date and time the volume was last backed up; this is 0 if the volume has never been backed up.
ioVSeqNum
Used internally.
ioVWrCnt
The volume write count.
ioVFilCnt
The total number of files on the volume.
ioVDirCnt
The total number of directories (not including the root directory) on the volume.
ioVFndrInfo
Information used by the Finder.
Files.h
A universal procedure pointer to an application-defined completion function.
typedef IOCompletionProcPtr IOCompletionUPP;
See IOCompletionProcPtr
.
Files.h
Defines a parameter block used by low-level I/O functions.
struct IOParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short ioRefNum; SInt8 ioVersNum; SInt8 ioPermssn; Ptr ioMisc; Ptr ioBuffer; long ioReqCount; long ioActCount; short ioPosMode; long ioPosOffset; }; typedef struct IOParam IOParam; typedef IOParam * IOParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
ioRefNum
The file reference number of an open file.
ioVersNum
A version number. This field is no longer used and you should always set it to 0.
ioPermssn
The access mode. See “File Access Permission Constants.”
ioMisc
Depending on the function called, this field contains either a new logical end-of-file (for the PBGetEOFSync/ PBGetEOFAsync
and PBSetEOFSync/ PBSetEOFAsync
functions), a new version number, or a pointer to a new pathname (for the PBHRenameSync
/ PBHRenameAsync
functions). Because ioMisc
is of type Ptr
, you’ll need to perform type coercion to interpret the value of ioMisc
correctly when it contains an end-of-file (a LongInt
value) or version number (a SignedByte
value).
ioBuffer
A pointer to a data buffer into which data is written by PBReadSync
and PBReadAsync
calls; and from which data is read by PBWriteSync
and PBWriteAsync
calls.
ioReqCount
The requested number of bytes to be read, written, or allocated.
ioActCount
The number of bytes actually read, written, or allocated.
ioPosMode
The positioning mode (base location) for positioning the file mark. Bits 0 and 1 of this field indicate how to position the mark; you can use the constants described in “Position Mode Constants” to set or test their value.
You can also use the constants described in “Cache Constants” to indicate whether the data should be cached.
ioPosOffset
The offset to be used in conjunction with the base location specified in the ioPosMode
field.
Files.h
Defines a parameter block used by low-level functions in the classic Device Manager to access multiple devices.
struct MultiDevParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short ioMRefNum; SInt8 ioMVersNum; SInt8 ioMPermssn; Ptr ioMMix; short ioMFlags; Ptr ioSEBlkPtr; }; typedef struct MultiDevParam MultiDevParam; typedef MultiDevParam * MultiDevParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
ioMRefNum
The driver reference number.
ioMVersNum
The slot version number.
ioMPermssn
Permissions.
ioMMix
Reserved.
ioMFlags
Flags specifying the number of additional fields. You should set the fMulti
bit (bit 0) of this field and clear all of the other bits.
ioSEBlkPtr
A pointer to an external parameter block that is customized for the devices installed in the slot.
Files.h
Defines a parameter block used by low-level HFS user and group information functions.
struct ObjParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short filler7; short ioObjType; StringPtr ioObjNamePtr; long ioObjID; }; typedef struct ObjParam ObjParam; typedef ObjParam * ObjParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
filler7
Reserved.
ioObjType
A function code. The values passed in this field are determined by the function to which you pass this parameter block.
ioObjNamePtr
A pointer to the returned creator/group name.
ioObjID
The creator/group ID.
Files.h
Describes the basic File Manager parameter block.
union ParamBlockRec { IOParam ioParam; FileParam fileParam; VolumeParam volumeParam; CntrlParam cntrlParam; SlotDevParam slotDevParam; MultiDevParam multiDevParam; }; typedef union ParamBlockRec ParamBlockRec; typedef ParamBlockRec * ParmBlkPtr;
ioParam
fileParam
volumeParam
cntrlParam
slotDevParam
multiDevParam
Files.h
Defines a parameter block used by low-level functions in the classic Device Manager to access a single slot device.
struct SlotDevParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short ioSRefNum; SInt8 ioSVersNum; SInt8 ioSPermssn; Ptr ioSMix; short ioSFlags; SInt8 ioSlot; SInt8 ioID; }; typedef struct SlotDevParam SlotDevParam; typedef SlotDevParam * SlotDevParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
ioSRefNum
The driver reference number.
ioSVersNum
The slot version number.
ioSPermssn
Permissions.
ioSMix
Reserved.
ioSFlags
Flags determining the number of additional fields. You should clear all of the bits in this field.
ioSlot
The slot number.
ioID
The slot resource ID.
Files.h
Defines a volume control block.
struct VCB { QElemPtr qLink; short qType; short vcbFlags; unsigned short vcbSigWord; unsigned long vcbCrDate; unsigned long vcbLsMod; short vcbAtrb; unsigned short vcbNmFls; short vcbVBMSt; short vcbAllocPtr; unsigned short vcbNmAlBlks; long vcbAlBlkSiz; long vcbClpSiz; short vcbAlBlSt; long vcbNxtCNID; unsigned short vcbFreeBks; Str27 vcbVN; short vcbDrvNum; short vcbDRefNum; short vcbFSID; short vcbVRefNum; Ptr vcbMAdr; Ptr vcbBufAdr; short vcbMLen; short vcbDirIndex; short vcbDirBlk; unsigned long vcbVolBkUp; unsigned short vcbVSeqNum; long vcbWrCnt; long vcbXTClpSiz; long vcbCTClpSiz; unsigned short vcbNmRtDirs; long vcbFilCnt; long vcbDirCnt; long vcbFndrInfo[8]; unsigned short vcbVCSize; unsigned short vcbVBMCSiz; unsigned short vcbCtlCSiz; unsigned short vcbXTAlBlks; unsigned short vcbCTAlBlks; short vcbXTRef; short vcbCTRef; Ptr vcbCtlBuf; long vcbDirIDM; short vcbOffsM; }; typedef struct VCB VCB; typedef VCB * VCBPtr;
qLink
A pointer to the next entry in the VCB queue.
qType
The queue type. When the volume is mounted and the VCB is created, this field is cleared. Thereafter, bit 7 of this field is set whenever a file on that volume is opened.
vcbFlags
Volume flags. Bit 15 is set if the volume information has been changed by a File Manager call since the volume was last flushed by a FlushVol
call. See “Volume Control Block Flags.”
vcbSigWord
The volume signature.
vcbCrDate
The date and time of the volume’s creation (initialization).
vcbLsMod
The date and time of the volume’s last modification. This is not necessarily when the volume was last flushed.
vcbAtrb
The volume attributes.
vcbNmFls
The number of files in the root directory of the volume.
vcbVBMSt
The first block of the volume bitmap.
vcbAllocPtr
The start block of the next allocation search. This field is used internally.
vcbNmAlBlks
The number of allocation blocks in the volume.
vcbAlBlkSiz
The allocation block size, in bytes. This value must always be a multiple of 512 bytes.
vcbClpSiz
The default clump size.
vcbAlBlSt
The first allocation block in the volume.
vcbNxtCNID
The next unused catalog node ID (directory or file ID).
vcbFreeBks
The number of unused allocation blocks on the volume.
vcbVN
The volume name. Note that a volume name can occupy at most 27 characters; this is an exception to the normal file and directory name limit of 31 characters.
vcbDrvNum
The drive number of the drive on which the volume is located. When a mounted drive is placed offline or ejected, this field is set to 0.
vcbDRefNum
The driver reference number of the driver used to access the volume When a volume is ejected, this field is set to the previous value of the vcbDrvNum
field (and hence is a positive number). When a volume is placed offline, this field is set to the negative of the previous value of the vcbDrvNum
field (and hence is a negative number).
vcbFSID
An identifier for the file system handling the volume it’s zero for volumes handled by the File Manager and nonzero for volumes handled by other file systems.
vcbVRefNum
The volume reference number of the volume.
vcbMAdr
Used internally.
vcbBufAdr
Used internally.
vcbMLen
Used internally.
vcbDirIndex
Used internally.
vcbDirBlk
Used internally.
vcbVolBkUp
The date and time that the volume was last backed up.
vcbVSeqNum
Used internally.
vcbWrCnt
The volume write count.
vcbXTClpSiz
The clump size of the extents overflow file.
vcbCTClpSiz
The clump size of the catalog file.
vcbNmRtDirs
The number of directories in the root directory.
vcbFilCnt
The total number of files on the volume.
vcbDirCnt
The total number of directories on the volume.
vcbFndrInfo
Finder information.
vcbVCSize
Used internally.
vcbVBMCSiz
Used internally.
vcbCtlCSiz
Used internally.
vcbXTAlBlks
The size, in allocation blocks, of the extents overflow file.
vcbCTAlBlks
The size, in allocation blocks, of the catalog file.
vcbXTRef
The path reference number for the extents overflow file.
vcbCTRef
The path reference number for the catalog file.
vcbCtlBuf
A pointer to the extents and catalog caches.
vcbDirIDM
The directory last searched.
vcbOffsM
The offspring index at the last search.
The volume control block queue is a standard operating system queue that’s maintained in the system heap. It contains a volume control block for each mounted volume. A volume control block is a nonrelocatable block that contains volume-specific information.
Each time a volume is mounted, the File Manager reads its volume information from the master directory block and uses the information to build a new volume control block (VCB) in the volume control block queue (unless an ejected or offline volume is being remounted). The File Manager also creates a volume buffer in the system heap. When a volume is placed offline, its buffer is released. When a volume is unmounted, its VCB is removed from the VCB queue as well.
Files.h
Defines a volume mounting information header structure for remote volumes.
struct VolMountInfoHeader { short length; VolumeType media; }; typedef struct VolMountInfoHeader VolMountInfoHeader; typedef VolMountInfoHeader * VolMountInfoPtr;
length
The length of the VolMountInfoHeader
structure, which is the total length of the structure header described here, plus the variable-length location data which follows the header.
media
The volume type of the remote volume. The AppleShareMediaType
represents an AppleShare volume.
If you are adding support for the programmatic mounting functions to a non-Macintosh file system, you should register a four-character identifier for your volumes with DTS.
To mount a remote server, fill out an VolMountInfoHeader
structure using the PBGetVolMountInfo
function and then pass this structure to the PBVolumeMount
function to mount the volume.
Files.h
Defines an extended volume mounting information header structure for remote volumes.
struct VolumeMountInfoHeader { short length; VolumeType media; short flags; }; typedef struct VolumeMountInfoHeader VolumeMountInfoHeader; typedef VolumeMountInfoHeader * VolumeMountInfoHeaderPtr;
length
The length of the VolumeMountInfoHeader
structure, which is the total length of the structure header described here, plus the variable-length location data which follows the header.
media
The volume type of the remote volume. The AppleShareMediaType
represents an AppleShare volume.
If you are adding support for the programmatic mounting functions to a non-Macintosh file system, you should register a four-character identifier for your volumes with DTS.
flags
The volume mount flags. See “Volume Mount Flags.”
This volume mount info record supersedes the VolMountInfoHeader
structure; VolMountInfoHeader
is included for compatibility. The VolumeMountInfoHeader
record allows access to the volume mount flags by foreign filesystem writers.
To mount a remote server, fill out an VolumeMountInfoHeader
structure using the PBGetVolMountInfo
function and then pass this structure to the PBVolumeMount
function to mount the volume.
Files.h
Defines a parameter block used by low-level volume manipulation functions.
struct VolumeParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; long filler2; short ioVolIndex; unsigned long ioVCrDate; unsigned long ioVLsBkUp; unsigned short ioVAtrb; unsigned short ioVNmFls; unsigned short ioVDirSt; short ioVBlLn; unsigned short ioVNmAlBlks; unsigned long ioVAlBlkSiz; unsigned long ioVClpSiz; unsigned short ioAlBlSt; unsigned long ioVNxtFNum; unsigned short ioVFrBlk; }; typedef struct VolumeParam VolumeParam; typedef VolumeParam * VolumeParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
filler2
Reserved.
ioVolIndex
The volume index.
ioVCrDate
The date and time of the volume’s initialization.
ioVLsBkUp
The date and time the volume information was last modified. (This field is not changed when information is written to a file and does not necessarily indicate when the volume was flushed.
ioVAtrb
The volume attributes. See “Volume Information Attribute Constants” for the meanings of the bits in this field.
ioVNmFls
The number of files in the root directory.
ioVDirSt
The first block of the volume directory.
ioVBlLn
Length of directory in blocks.
ioVNmAlBlks
The number of allocation blocks.
ioVAlBlkSiz
The size of allocation blocks.
ioVClpSiz
The volume clump size.
ioAlBlSt
The first block in the volume map.
ioVNxtFNum
The next unused file number.
ioVFrBlk
The number of unused allocation blocks.
Files.h
Defines the “signature” of the file system.
typedef OSType VolumeType;
Files.h
Defines a parameter block used by low-level HFS working directory functions.
struct WDParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short ioWDCreated; short ioWDIndex; long ioWDProcID; short ioWDVRefNum; short filler10; long filler11; long filler12; long filler13; long ioWDDirID; }; typedef struct WDParam WDParam; typedef WDParam * WDParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
ioWDCreated
ioWDIndex
An index to working directories.
ioWDProcID
ioWDVRefNum
The volume reference number for the working directory.
filler10
Reserved.
filler11
Reserved.
filler12
Reserved.
filler13
The working directory’s directory ID.
ioWDDirID
The working directory’s directory ID.
Files.h
Defines a working directory parameter block.
struct WDPBRec { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short filler1; short ioWDIndex; long ioWDProcID; short ioWDVRefNum; short filler2[7]; long ioWDDirID; }; typedef struct WDPBRec WDPBRec; typedef WDPBRec * WDPBPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
filler1
Reserved.
ioWDIndex
An index.
ioWDProcID
An identifier that’s used to distinguish between working directories set up by different users you should set ioWDProcID
to your application’s signature.
ioWDVRefNum
The working directory’s volume reference number.
filler2
Reserved.
ioWDDirID
The working directory’s directory ID.
Files.h
Defines an extended catalog information parameter block.
struct XCInfoPBRec { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; ProcPtr ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; long filler1; StringPtr ioShortNamePtr; short filler2; short ioPDType; long ioPDAuxType; long filler3[2]; long ioDirID; }; typedef struct XCInfoPBRec XCInfoPBRec; typedef XCInfoPBRec * XCInfoPBPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
filler1
Reserved; set this field to 0.
ioShortNamePtr
A pointer to a Pascal string buffer, of a minimum 13 bytes, which holds the file or directory’s short name (MS-DOS format name). This field is required and cannot be NULL
.
filler2
Reserved; set this field to 0.
ioPDType
The ProDOS file type of the file or directory.
ioPDAuxType
The ProDOS auxiliary type of the file or directory.
filler3
Reserved; set this field to 0.
ioDirID
A directory ID.
The PBGetXCatInfoSync
and PBGetXCatInfoAsync
functions use this parameter block to return the short name and ProDOS information for files and directories.
Files.h
Defines an extended I/O parameter block structure.
struct XIOParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short ioRefNum; SInt8 ioVersNum; SInt8 ioPermssn; Ptr ioMisc; Ptr ioBuffer; long ioReqCount; long ioActCount; short ioPosMode; wide ioWPosOffset; }; typedef struct XIOParam XIOParam; typedef XIOParam * XIOParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
ioRefNum
The file reference number of an open file.
ioVersNum
A version number. This field is no longer used and you should always set it to 0.
ioPermssn
The access mode. See “File Access Permission Constants.”
ioMisc
Depending on the function called, this field contains either a logical end-of-file, a new version number, a pointer to an access path buffer, or a pointer to a new pathname. Because ioMisc
is of type Ptr
, you’ll need to perform type coercion to interpret the value of ioMisc
correctly when it contains an end-of-file (a LongInt
value) or version number (a SignedByte
value).
ioBuffer
A pointer to a data buffer into which data is written by _Read
calls and from which data is read by _Write
calls.
ioReqCount
The requested number of bytes to be read or written.
ioActCount
The number of bytes actually read or written.
ioPosMode
The positioning mode (base location) for setting the mark. Bits 0 and 1 of this field indicate how to position the mark; you can use the constants described in “Position Mode Constants” to set or test their value. For the functions which use this parameter block, you must have the kUseWidePositioning
bit set. See “Large Volume Constants” for a description of this and other constants.
You can also use the constants described in “Cache Constants” to indicate whether or not to cache the data.
ioWPosOffset
The wide positioning offset to be used in conjunction with the positioning mode specified in the ioPosMode
field.
Files.h
Defines an extended volume information parameter block.
struct XVolumeParam { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; IOCompletionUPP ioCompletion; volatile OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; unsigned long ioXVersion; short ioVolIndex; unsigned long ioVCrDate; unsigned long ioVLsMod; short ioVAtrb; unsigned short ioVNmFls; unsigned short ioVBitMap; unsigned short ioAllocPtr; unsigned short ioVNmAlBlks; unsigned long ioVAlBlkSiz; unsigned long ioVClpSiz; unsigned short ioAlBlSt; unsigned long ioVNxtCNID; unsigned short ioVFrBlk; unsigned short ioVSigWord; short ioVDrvInfo; short ioVDRefNum; short ioVFSID; unsigned long ioVBkUp; short ioVSeqNum; unsigned long ioVWrCnt; unsigned long ioVFilCnt; unsigned long ioVDirCnt; long ioVFndrInfo[8]; UInt64 ioVTotalBytes; UInt64 ioVFreeBytes; }; typedef struct XVolumeParam XVolumeParam; typedef XVolumeParam * XVolumeParamPtr;
qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.
qType
The queue type. This field is used internally by the File Manager.
ioTrap
The trap number of the function that was called. This field is used internally by the File Manager.
ioCmdAddr
The address of the function that was called. This field is used internally by the File Manager.
ioCompletion
A universal procedure pointer to a completion routine to be executed at the end of an asynchronous call. It should be 0 for asynchronous calls with no completion routine and is automatically set to 0 for all synchronous calls. See IOCompletionProcPtr
for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field it’s set to a positive number when the call is made and receives the actual result code when the call is completed.
ioNamePtr
A pointer to a pathname. Whenever a function description specifies that ioNamePtr
is used—whether for input, output, or both—it’s very important that you set this field to point to storage for a Str255
value (if you’re using a pathname) or to NULL
(if you’re not).
ioVRefNum
A volume reference number, 0 for the default volume, or a drive number.
ioXVersion
The version of the XVolumeParam
parameter block; currently, this is 0.
ioVolIndex
A volume index for use with the PBXGetVolInfoSync
and PBXGetVolInfoAsync
functions.
ioVCrDate
The date and time that the volume was created (initialized).
ioVLsMod
The date and time that the volume information was last modified. This field is not changed when information is written to a file and does not necessarily indicate when the volume was flushed.
ioVAtrb
The volume attributes. See “Volume Information Attribute Constants” for the meanings of the bits in this field.
ioVNmFls
The number of files in the root directory.
ioVBitMap
The first block of the volume bitmap.
ioAllocPtr
The block at which the next new file starts. Used internally.
ioVNmAlBlks
The number of allocation blocks.
ioVAlBlkSiz
The size of the allocation blocks.
ioVClpSiz
The clump size.
ioAlBlSt
The first block in the volume map.
ioVNxtCNID
The next unused catalog node ID.
ioVFrBlk
The number of unused allocation blocks.
ioVSigWord
A signature word identifying the type of volume it’s $D2D7 for MFS volumes and $4244 for volumes that support HFS calls.
ioVDrvInfo
The drive number of the drive containing the volume.
ioVDRefNum
For online volumes, the reference number of the I/O driver for the drive identified by the ioVDrvInfo
field.
ioVFSID
The file-system identifier. It indicates which file system is servicing the volume it’s zero for File Manager volumes and nonzero for volumes handled by an external file system.
ioVBkUp
The date and time that the volume was last backed up; this is 0 if the volume has never been backed up.
ioVSeqNum
Used internally.
ioVWrCnt
The volume write count.
ioVFilCnt
The total number of files on the volume.
ioVDirCnt
The total number of directories (not including the root directory) on the volume.
ioVFndrInfo
Information used by the Finder.
ioVTotalBytes
The total number of bytes on the volume.
ioVFreeBytes
The number of free bytes on the volume.
The functions PBXGetVolInfoSync
and PBXGetVolInfoAsync
use this parameter block structure to pass arguments and return values.
Files.h
Specify the length of tagged address information for AppleShare volumes.
enum { kAFPTagLengthIP = 0x06, kAFPTagLengthIPPort = 0x08, kAFPTagLengthDDP = 0x06 };
kAFPTagLengthIP
The length of a 4 byte IP address.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kAFPTagLengthIPPort
The length of a 4 byte IP address and a 2 byte port.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kAFPTagLengthDDP
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
These constants are used in the fLength
field of the AFPTagData
structure to indicate the length, in bytes, of the tagged address information. This length includes the fLength field itself.
Specify the type of tagged address information for AppleShare clients.
enum { kAFPTagTypeIP = 0x01, kAFPTagTypeIPPort = 0x02, kAFPTagTypeDDP = 0x03, kAFPTagTypeDNS = 0x04 };
kAFPTagTypeIP
A basic 4 byte IP address, most significant byte first.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kAFPTagTypeIPPort
A 4 byte IP address and a 2 byte port number, most significant byte first.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kAFPTagTypeDDP
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kAFPTagTypeDNS
The address is a DNS name in address:port format. The total length of the DNS name is variable up to 254 characters.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
These constants are used in the fType
field of the tagged address structure, AFPTagData
, to specify the type of address represented by the structure.
Indicate how new space is to be allocated.
typedef UInt16 FSAllocationFlags; enum { kFSAllocDefaultFlags = 0x0000, kFSAllocAllOrNothingMask = 0x0001, kFSAllocContiguousMask = 0x0002, kFSAllocNoRoundUpMask = 0x0004, kFSAllocReservedMask = 0xFFF8 };
kFSAllocDefaultFlags
Allocate as much as possible, not necessarily contiguous.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSAllocAllOrNothingMask
This bit is set when an allocation must allocate the total requested amount, or else fail with nothing allocated; when this bit is not set, the allocation may complete successfully but allocate less than requested.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSAllocContiguousMask
This bit is set when an allocation should allocate one contiguous range of space on the volume. If this bit is clear, multiple discontiguous extents may be allocated to fulfill the request.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSAllocNoRoundUpMask
This bit is set when an allocation should no round up to the clump size. If this bit is clear, then additional space beyond the amount requested may be allocated; this is done by some volume formats (including HFS and HFS Plus) to avoid many small allocation requests. If the bit is set, no additional allocation is done (except where required by the volume format, such as rounding up to a multiple of the allocation block size).
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSAllocReservedMask
Reserved; set to zero.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
If the kFSAllocContiguousMask
bit is set, then then any newly allocated space must be in one contiguous extent (preferably contiguous with any space already allocated). If kFSAllocAllOrNothingMask
is set, then the entire requestCount
bytes must be allocated for the call to succeed; if not set, as many bytes as possible will be allocated (without error). If kFSAllocNoRoundUpMask
is set, then no additional space is allocated (such as rounding up to a multiple of a clump size); if clear, the volume format may allocate more space than requested as an attempt to reduce fragmentation.
Defines the volume signature for AppleShare volumes.
enum { AppleShareMediaType = 'afpm' };
Define the login methods for remote volumes.
enum { kNoUserAuthentication = 1, kPassword = 2, kEncryptPassword = 3, kTwoWayEncryptPassword = 6 };
kNoUserAuthentication
No password.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kPassword
8-byte password.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kEncryptPassword
Encrypted 8-byte password.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kTwoWayEncryptPassword
Two-way random encryption.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
These constants are used in the uamType
field of an AFPVolMountInfo
structure and in the ioObjType
field of the parameter block passed to the PBHGetLogInInfoSync
and PBHGetLogInInfoAsync
functions to specify the type of user authentication used by a remote volume.
Indicate whether or not data should be cached.
enum { pleaseCacheBit = 4, pleaseCacheMask = 0x0010, noCacheBit = 5, noCacheMask = 0x0020, rdVerifyBit = 6, rdVerifyMask = 0x0040, rdVerify = 64, forceReadBit = 6, forceReadMask = 0x0040, newLineBit = 7, newLineMask = 0x0080, newLineCharMask = 0xFF00 };
pleaseCacheBit
Indicates that the data should be cached.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
pleaseCacheMask
Requests that the data be cached, if possible. You should cache reads and writes if you read or write the same portion of a file multiple times.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
noCacheBit
Indicates that data should not be cached.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
noCacheMask
Requests that the data not be cached, if possible. You should not cache reads and writes if you read or write data from a file only once.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
rdVerifyBit
Indicates that all reads should come from the source and be verified against the data in memory.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
rdVerifyMask
Requests that all reads (not writes) come directly from the source and be verified against the data in memory. This flushes the cache and sends all read requests to the data source.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
rdVerify
This is the old name of rdVerifyMask
. Both request that all reads come directly from the source of the data and be compared against the data in memory.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
forceReadBit
Indicates that reads should come from the disk.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
forceReadMask
Forces reads from disk, bypassing all caches. Clients can use this to verify that data is stored correctly on the media (for example, to verify after writing) by reading the data into a different buffer while setting the bit, and then comparing the newly read data with the previously written data.
The forceReadMask
is the same as the rdVerifyMask
used in the older APIs. The actual implementation of the rdVerifyMask
in the older APIs actually caused the “force read” behavior, and only compared the data in partial sectors. FSReadFork
cleans up this behavior by always letting the client do all of the compares.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
newLineBit
Indicates that newline mode should be used for reads.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
newLineMask
Requests that newline mode be used for reads. In newline mode, the read stops when one of the following conditions is met:
The requested number of bytes have been read.
The end-of-file is reached.
The newline character has been read. If the newline character is found, it will be the last character put into the buffer and the number of bytes read will include it.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
newLineCharMask
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
For the FSReadFork
and FSWriteFork
functions, and their parameter block equivalents, you may add either of the pleaseCacheMask
or noCacheMask
constants to one of the “Position Mode Constants” to hint whether the data should be cached or not.
The pleaseCacheBit
and the noCacheBit
are mutually exclusive and only one should be set at a time. If neither bit is set, the program has indicated that it doesn’t care if the data is cached or not.
Specify what file or fork information to get or set.
enum { kFSCatInfoNone = 0x00000000, kFSCatInfoTextEncoding = 0x00000001, kFSCatInfoNodeFlags = 0x00000002, kFSCatInfoVolume = 0x00000004, kFSCatInfoParentDirID = 0x00000008, kFSCatInfoNodeID = 0x00000010, kFSCatInfoCreateDate = 0x00000020, kFSCatInfoContentMod = 0x00000040, kFSCatInfoAttrMod = 0x00000080, kFSCatInfoAccessDate = 0x00000100, kFSCatInfoBackupDate = 0x00000200, kFSCatInfoPermissions = 0x00000400, kFSCatInfoFinderInfo = 0x00000800, kFSCatInfoFinderXInfo = 0x00001000, kFSCatInfoValence = 0x00002000, kFSCatInfoDataSizes = 0x00004000, kFSCatInfoRsrcSizes = 0x00008000, kFSCatInfoSharingFlags = 0x00010000, kFSCatInfoUserPrivs = 0x00020000, kFSCatInfoUserAccess = 0x00080000, kFSCatInfoSetOwnership = 0x00100000, kFSCatInfoAllDates = 0x000003E0, kFSCatInfoGettableInfo = 0x0003FFFF, kFSCatInfoSettableInfo = 0x00001FE3, kFSCatInfoReserved = 0xFFFC0000 };
kFSCatInfoNone
No catalog information.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoTextEncoding
Retrieve or set the text encoding hint, in the textEncodingHint
field.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoNodeFlags
Retrieve or set the catalog node flags. Currently, you can only set bits 0 and 4. See “Catalog Information Node Flags” for more information on these flags.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoVolume
Retrieve the volume reference number of the volume on which the file or directory resides.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoParentDirID
Retrieve the parent directory ID.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoNodeID
Retrieve the file or directory ID.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoCreateDate
Retrieve or set the creation date.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoContentMod
Retrieve or set the date that the resource or data fork was last modified.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoAttrMod
Retrieve or set the date that an attribute or named fork was last modified.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoAccessDate
Retrieve or set the date that the fork or file was last accessed.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoBackupDate
Retrieve or set the date that the fork or file was last backed up.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoPermissions
Retrieve or set the file or fork’s permissions.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoFinderInfo
Retrieve or set the file or fork’s Finder information.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoFinderXInfo
Retrieve or set the file or fork’s extended Finder information.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoValence
For folders only, retrieve the valence of the folder. For files, this is zero.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoDataSizes
Retrieve the logical and physical size of the data fork.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoRsrcSizes
Retrieve the logical and physical size of the resource fork.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoSharingFlags
Retrieve the fork or file’s sharing flags: kioFlAttribMountedBit
, kioFlAttribSharePointBit
. See “File Attribute Constants” for more information on these bits.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoUserPrivs
Retrieve the file’s user privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoUserAccess
Available in Mac OS X v10.1 and later.
Declared in Files.h
.
kFSCatInfoSetOwnership
Attempt to set the file’s user and group (UID and GID). If the File Manager cannot set the the user or group ID, the call fails. (Mac OS X only).
Available in Mac OS X v10.3 and later.
Declared in Files.h
.
kFSCatInfoAllDates
Retrieve or set all of the date information for the fork or file: creation date, modification dates, access date, backup date, etc.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoGettableInfo
Retrieve all gettable data.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoSettableInfo
Set all settable data. This includes the flags, dates, permissions, Finder info, and text encoding hint.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSCatInfoReserved
Represents bits that are currently reserved.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
These constants are used in the FSCatalogInfoBitmap
type to specify what file or fork information to get or set. If used with the FSGetCatalogInfo
or FSGetCatalogInfoBulk
functions, these constants tell the File Manager which fields to return information in. If used with the FSSetCatalogInfo
function, these constants tell the File Manager which fields you’ve filled out with values that it should use to change the fork or file’s catalog information.
Define the values used in the nodeFlags
field of the FSCatalogInfo
structure.
enum { kFSNodeLockedBit = 0, kFSNodeLockedMask = 0x0001, kFSNodeResOpenBit = 2, kFSNodeResOpenMask = 0x0004, kFSNodeDataOpenBit = 3, kFSNodeDataOpenMask = 0x0008, kFSNodeIsDirectoryBit = 4, kFSNodeIsDirectoryMask = 0x0010, kFSNodeCopyProtectBit = 6, kFSNodeCopyProtectMask = 0x0040, kFSNodeForkOpenBit = 7, kFSNodeForkOpenMask = 0x0080, kFSNodeHardLinkBit = 8, kFSNodeHardLinkMask = 0x00000100 };
kFSNodeLockedBit
Set if the file or directory is locked.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSNodeLockedMask
Indicates that the file or directory is locked.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSNodeResOpenBit
Set if the resource fork is open.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSNodeResOpenMask
Indicates that the resource fork is open.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSNodeDataOpenBit
Set if the data fork is open.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSNodeDataOpenMask
Indicates that the data fork is open.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSNodeIsDirectoryBit
Set if the object is a directory.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSNodeIsDirectoryMask
Indicates that the object is a directory.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSNodeCopyProtectBit
Set of the file or directory is copy protected.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSNodeCopyProtectMask
Indicates that the file or directory is copy protected.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSNodeForkOpenBit
Set if the file or directory has any open fork.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSNodeForkOpenMask
Indicates that the file or directory has an open fork of any type.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSNodeHardLinkBit
Available in Mac OS X v10.2 and later.
Declared in Files.h
.
kFSNodeHardLinkMask
Available in Mac OS X v10.2 and later.
Declared in Files.h
.
Indicate the status of a shared directory.
enum { kFSNodeInSharedBit = 2, kFSNodeInSharedMask = 0x0004, kFSNodeIsMountedBit = 3, kFSNodeIsMountedMask = 0x0008, kFSNodeIsSharePointBit = 5, kFSNodeIsSharePointMask = 0x0020 };
kFSNodeInSharedBit
Set if a directory is within a share point.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSNodeInSharedMask
Indicates that the directory is within a share point.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSNodeIsMountedBit
Set if a directory is a share point currently mounted by some user.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSNodeIsMountedMask
Indicates that the directory is a share point currently mounted by some user.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSNodeIsSharePointBit
Set if a directory is a share point (an exported volume).
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSNodeIsSharePointMask
Indicates that the directory is a share point (an exported volume).
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
The FSCatalogInfo
structure uses these constants in its sharingFlags
field.
Indicate the criteria for a catalog search.
enum { fsSBPartialNameBit = 0, fsSBFullNameBit = 1, fsSBFlAttribBit = 2, fsSBFlFndrInfoBit = 3, fsSBFlLgLenBit = 5, fsSBFlPyLenBit = 6, fsSBFlRLgLenBit = 7, fsSBFlRPyLenBit = 8, fsSBFlCrDatBit = 9, fsSBFlMdDatBit = 10, fsSBFlBkDatBit = 11, fsSBFlXFndrInfoBit = 12, fsSBFlParIDBit = 13, fsSBNegateBit = 14, fsSBDrUsrWdsBit = 3, fsSBDrNmFlsBit = 4, fsSBDrCrDatBit = 9, fsSBDrMdDatBit = 10, fsSBDrBkDatBit = 11, fsSBDrFndrInfoBit = 12, fsSBDrParIDBit = 13 };
fsSBPartialNameBit
Indicates a search by a substring of the name.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFullNameBit
Indicates a search by the full name.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlAttribBit
Indicates a search by the file or directory attributes.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlFndrInfoBit
For files only indicates a search by the file’s Finder info.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlLgLenBit
For files only; indicates a search by the logical length of the data fork.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlPyLenBit
For files only; indicates a search by the physical length of the data fork.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlRLgLenBit
For files only; indicates a search for the logical length of the resource fork.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlRPyLenBit
For files only; indicates a search by the physical length of the resource fork.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlCrDatBit
For files only indicates a search by the file’s creation date.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlMdDatBit
For files only indicates a search by the date of the file’s last modification.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlBkDatBit
For files only indicates a search by the date of the file’s last backup.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlXFndrInfoBit
For files only indicates a search by the file’s extended Finder info.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlParIDBit
For files only indicates a search by the file’s parent ID.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBNegateBit
Indicates a search for all non-matches. That is, if a file or directory matches one of the other specified criteria, it is not returned; if it does not match any of the specified criteria, it is returned.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBDrUsrWdsBit
For directories only indicates a search by the directory’s Finder info.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBDrNmFlsBit
For directories only; indicates a search by the number of files in the directory.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBDrCrDatBit
For directories only indicates a search by the directory’s creation date.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBDrMdDatBit
For directories only indicates a search by the date of the directory’s last modification.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBDrBkDatBit
For directories only indicates a search by the date of the directory’s last backup.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBDrFndrInfoBit
For directories only indicates a search by the directory’s additional Finder info.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBDrParIDBit
For directories only indicates a search by the directory’s parent ID.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
Specify the which catalog information fields to use as search criteria.
enum { fsSBNodeID = 0x00008000, fsSBAttributeModDate = 0x00010000, fsSBAccessDate = 0x00020000, fsSBPermissions = 0x00040000, fsSBNodeIDBit = 15, fsSBAttributeModDateBit = 16, fsSBAccessDateBit = 17, fsSBPermissionsBit = 18 };
fsSBNodeID
Search by a range of catalog node ID.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBAttributeModDate
Search by a range of attribute (fork) modification date.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBAccessDate
Search by a range of access date.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBPermissions
Search by a value or mask of permissions.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBNodeIDBit
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBAttributeModDateBit
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBAccessDateBit
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBPermissionsBit
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
Specify the criteria for a catalog search.
enum { fsSBPartialName = 1, fsSBFullName = 2, fsSBFlAttrib = 4, fsSBFlFndrInfo = 8, fsSBFlLgLen = 32, fsSBFlPyLen = 64, fsSBFlRLgLen = 128, fsSBFlRPyLen = 256, fsSBFlCrDat = 512, fsSBFlMdDat = 1024, fsSBFlBkDat = 2048, fsSBFlXFndrInfo = 4096, fsSBFlParID = 8192, fsSBNegate = 16384, fsSBDrUsrWds = 8, fsSBDrNmFls = 16, fsSBDrCrDat = 512, fsSBDrMdDat = 1024, fsSBDrBkDat = 2048, fsSBDrFndrInfo = 4096, fsSBDrParID = 8192 };
fsSBPartialName
Search by a substring of the name.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFullName
Search by the full name.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlAttrib
Search by the file or directory attributes. You can use the attributes to specify that you are searching for a directory, or for a file or directory that is locked by software.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlFndrInfo
For files only search by the file’s Finder info.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlLgLen
For files only; search by the logical length of the data fork.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlPyLen
For files only; search by the physical length of the data fork.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlRLgLen
For files only; search for the logical length of the resource fork.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlRPyLen
For files only; search by the physical length of the resource fork.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlCrDat
For files only search by the file’s creation date.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlMdDat
For files only search by the date of the file’s last modification.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlBkDat
For files only search by the date of the file’s last backup.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlXFndrInfo
For files only search by the file’s extended Finder info.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBFlParID
For files only search by the file’s parent ID.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBNegate
Search for all non-matches. That is, if a file or directory matches one of the other specified criteria, it is not returned; if it does not match any of the specified criteria, it is returned.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBDrUsrWds
For directories only search by the directory’s Finder info.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBDrNmFls
For directories only; search by the number of files in the directory.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBDrCrDat
For directories only search by the directory’s creation date.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBDrMdDat
For directories only search by the date of the directory’s last modification.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBDrBkDat
For directories only search by the date of the directory’s last backup.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBDrFndrInfo
For directories only search by the directory’s additional Finder info.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsSBDrParID
For directories only search by the directory’s parent ID.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
Use these constants in the ioSearchBits
field of the PBCatSearchSync
and PBCatSearchAsync
functions to specify the criteria for your search.
Specifies a flag used in the extendedFlags
field of the AFPXVolMountInfo
structure.
enum { kAFPExtendedFlagsAlternateAddressMask = 1 };
kAFPExtendedFlagsAlternateAddressMask
Indicates that the alternateAddressOffset
field in the AFPXVolMountInfo
record is used.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
See the AFPXVolMountInfo
structure for more information.
Describe a volume’s extended attributes.
enum { bIsEjectable = 0, bSupportsHFSPlusAPIs = 1, bSupportsFSCatalogSearch = 2, bSupportsFSExchangeObjects = 3, bSupports2TBFiles = 4, bSupportsLongNames = 5, bSupportsMultiScriptNames = 6, bSupportsNamedForks = 7, bSupportsSubtreeIterators = 8, bL2PCanMapFileBlocks = 9 bParentModDateChanges = 10, bAncestorModDateChanges = 11 bSupportsSymbolicLinks = 13, bIsAutoMounted = 14, bAllowCDiDataHandler = 17, bSupportsExclusiveLocks = 18 bSupportsJournaling = 19, bNoVolumeSizes = 20, bIsCaseSensitive = 22, bIsCasePreserving = 23, bDoNotDisplay = 24 };
bIsEjectable
The volume is in an ejectable disk drive .
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bSupportsHFSPlusAPIs
The volume supports the HFS Plus APIs directly, i.e., the File Manager does not emulate them.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bSupportsFSCatalogSearch
The volume supports the FSCatalogSearch
operation.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bSupportsFSExchangeObjects
The volume supports the FSExchangeObjects
function.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bSupports2TBFiles
The volume supports 2 terabyte files.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bSupportsLongNames
The volume supports file, directory, and volume names longer than 31 characters.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bSupportsMultiScriptNames
The volume supports file, directory, and volume names with characters from multiple script systems.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bSupportsNamedForks
The volume supports named forks other than the data and resource forks.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bSupportsSubtreeIterators
The volume supports recursive iterators, not at the volume root.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bL2PCanMapFileBlocks
The volume supports the Lg2Phys
SPI correctly.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bParentModDateChanges
On this volume, changing a file or folder causes its parent's modification date to change.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bAncestorModDateChanges
On this volume, changing a file or folder causes all ancestor modification dates to change.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bSupportsSymbolicLinks
The volume supports the creation and use of symbolic links (Mac OS X only).
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bIsAutoMounted
The volume was mounted automatically (Mac OS X only).
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bAllowCDiDataHandler
QuickTime's CDi data handler is allowed to examine the volume.
Available in Mac OS X v10.1 and later.
Declared in Files.h
.
bSupportsExclusiveLocks
The volume supports exclusive access to files opened for writing.
Available in Mac OS X v10.2 and later.
Declared in Files.h
.
bSupportsJournaling
The volume supports journaling. This does not indicate whether journaling is currently enabled on the volume.
Available in Mac OS X v10.3 and later.
Declared in Files.h
.
bNoVolumeSizes
The volume is unable to report volume size or free space.
Available in Mac OS X v10.3 and later.
Declared in Files.h
.
bIsCaseSensitive
The volume is case-sensitive.
Available in Mac OS X v10.3 and later.
Declared in Files.h
.
bIsCasePreserving
The volume is preserves case.
Available in Mac OS X v10.3 and later.
Declared in Files.h
.
bDoNotDisplay
The volume should not be displayed in the user interface.
Available in Mac OS X v10.3 and later.
Declared in Files.h
.
The GetVolParmsInfoBuffer
structure uses these constants in its vMExtendedAttributes
field.
Specify flags that describe the state of a file.
enum { kioFCBWriteBit = 8, kioFCBWriteMask = 0x0100, kioFCBResourceBit = 9, kioFCBResourceMask = 0x0200, kioFCBWriteLockedBit = 10, kioFCBWriteLockedMask = 0x0400, kioFCBLargeFileBit = 11, kioFCBLargeFileMask = 0x0800, kioFCBSharedWriteBit = 12, kioFCBSharedWriteMask = 0x1000, kioFCBFileLockedBit = 13, kioFCBFileLockedMask = 0x2000, kioFCBOwnClumpBit = 14, kioFCBOwnClumpMask = 0x4000, kioFCBModifiedBit = 15, kioFCBModifiedMask = 0x8000 };
kioFCBWriteBit
Set if data can be written to this file.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFCBWriteMask
Tests if data can be written to this file.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFCBResourceBit
Set if this FCB describes a resource fork.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFCBResourceMask
Tests if this FCB describes a resource fork.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFCBWriteLockedBit
Set if this file has a locked byte range.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFCBWriteLockedMask
Tests if this file has a locked byte range.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFCBLargeFileBit
Set if this file may grow beyond 2GB and the cache uses file blocks, not bytes.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFCBLargeFileMask
Tests if this file may grow beyond 2GB and the cache uses file blocks, not bytes.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFCBSharedWriteBit
Set if this file has shared write permissions.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFCBSharedWriteMask
Tests if this file has shared write permissions.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFCBFileLockedBit
Set if this file is locked (write-protected).
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFCBFileLockedMask
Tests if this file is locked (write-protected).
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFCBOwnClumpBit
Set if this file’s clump size is specified in the FCB.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFCBOwnClumpMask
Tests if this file’s clump size is specified in the FCB.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFCBModifiedBit
Set if this file has changed since it was last flushed.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFCBModifiedMask
Tests if this file has changed since it was last flushed.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
These constants are used in the ioFCBFlags
field of the FCBPBRec
returned by the functions PBGetFCBInfoSync
and PBGetFCBInfoAsync
.
Specify the type of read and write access to a file or fork.
enum { fsCurPerm = 0x00, fsRdPerm = 0x01, fsWrPerm = 0x02, fsRdWrPerm = 0x03, fsRdWrShPerm = 0x04, fsRdDenyPerm = 0x10, fsWrDenyPerm = 0x20 };
fsCurPerm
Requests whatever permissions are currently allowed. If write access in unavailable (because the file is locked or the file is already open with write permission), then read permission is granted. Otherwise read/write permission is granted.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsRdPerm
Requests permission to read the file.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsWrPerm
Requests permission to write to the file. If write permission is granted, no other access paths are granted write permission. Note, however, that the File Manager does not support write-only access to a file. Thus, fsWrPerm
is synonymous with fsRdWrPerm
.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsRdWrPerm
Requests exclusive read and write permission. If exclusive read/ write permission is granted, no other users are granted permission to write to the file. Other users may, however, be granted permission to read the file.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsRdWrShPerm
Requests shared read and write permission. Shared read and write permission allows multiple access paths for reading and writing. This is safe only if there is some way of locking portions of the file before writing to them. On volumes that support range locking, you can use the functions PBLockRangeSync
and PBUnlockRangeSync
to lock and unlock ranges of bytes within a file. Applications running in Mac OS X version 10.4 or later should use the functions FSLockRange
and FSUnlockRange
for this purpose.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsRdDenyPerm
Requests that any other paths be prevented from having read access. A path cannot be opened if you request read permission (with the fsRdPerm
constant) but some other path has requested deny-read access. Similarly, the path cannot be opened if you request deny-read permission, but some other path already has read access. This constant is only supported on volumes which return the bHasOpenDeny
attribute when you call FSGetVolumeParms
.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsWrDenyPerm
Requests that any other paths be prevented from having write access. A path cannot be opened if you request write permission (with the fsWrPerm
constant) but some other path has requested deny-write access. Similarly, the path cannot be opened if you request deny-write permission, but some other path already has write access. This constant is only supported on volumes which return the bHasOpenDeny
attribute when you call FSGetVolumeParms
.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
Use these constants to request a type of access to a file or fork, or to deny a type of access to a file or fork to other paths that may request access.
Note that it is possible, in Mac OS 8 and 9, to open a file residing on read-only media with write access. In Mac OS X, however, you cannot open a file with write access on read-only media; the attempt to open the file fails with a wrPermErr
error.
Specify access privileges for files and directories in the ioACAccess
field of the AccessParam
data type.
enum { kioACAccessOwnerBit = 31, kioACAccessOwnerMask = 0x80000000, kioACAccessBlankAccessBit = 28, kioACAccessBlankAccessMask = 0x10000000, kioACAccessUserWriteBit = 26, kioACAccessUserWriteMask = 0x04000000, kioACAccessUserReadBit = 25, kioACAccessUserReadMask = 0x02000000, kioACAccessUserSearchBit = 24, kioACAccessUserSearchMask = 0x01000000, kioACAccessEveryoneWriteBit = 18, kioACAccessEveryoneWriteMask = 0x00040000, kioACAccessEveryoneReadBit = 17, kioACAccessEveryoneReadMask = 0x00020000, kioACAccessEveryoneSearchBit = 16, kioACAccessEveryoneSearchMask = 0x00010000, kioACAccessGroupWriteBit = 10, kioACAccessGroupWriteMask = 0x00000400, kioACAccessGroupReadBit = 9, kioACAccessGroupReadMask = 0x00000200, kioACAccessGroupSearchBit = 8, kioACAccessGroupSearchMask = 0x00000100, kioACAccessOwnerWriteBit = 2, kioACAccessOwnerWriteMask = 0x00000004, kioACAccessOwnerReadBit = 1, kioACAccessOwnerReadMask = 0x00000002, kioACAccessOwnerSearchBit = 0, kioACAccessOwnerSearchMask = 0x00000001, kfullPrivileges = 0x00070007, kownerPrivileges = 0x00000007 };
kioACAccessOwnerBit
Indicates that the user is the owner of the directory.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessOwnerMask
The user is the owner of the directory.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessBlankAccessBit
Indicates that the directory has blank access privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessBlankAccessMask
The directory has blank access privileges. A directory with blank access privileges set ignores the other access privilege bits and uses the access privilege bits of its parent directory.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessUserWriteBit
Indicates that the user has write privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessUserWriteMask
The user has write privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessUserReadBit
Indicates that the user has read privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessUserReadMask
The user has read privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessUserSearchBit
Indicates that the user has search privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessUserSearchMask
The user has search privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessEveryoneWriteBit
Indicates that everyone has write privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessEveryoneWriteMask
Everyone has write privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessEveryoneReadBit
Indicates that everyone has read privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessEveryoneReadMask
Everyone has read privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessEveryoneSearchBit
Indicates that everyone has search privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessEveryoneSearchMask
Everyone has search privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessGroupWriteBit
Indicates that the group has write privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessGroupWriteMask
The group has write privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessGroupReadBit
Indicates that the group has read privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessGroupReadMask
The group has read privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessGroupSearchBit
Indicates that the group has search privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessGroupSearchMask
The group has search privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessOwnerWriteBit
Indicates that the owner has write privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessOwnerWriteMask
The owner has write privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessOwnerReadBit
Indicates that the owner has read privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessOwnerReadMask
The owner has read privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessOwnerSearchBit
Indicates that the owner has search privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACAccessOwnerSearchMask
The owner has search privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kfullPrivileges
Indicates that everyone, including the owner, have all privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kownerPrivileges
Indicates that only the owner has all privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
See AccessParam
.
Define file and directory attributes returned by the PBGetCatInfoSync
and PBGetCatInfoAsync
functions.
enum { kioFlAttribLockedBit = 0, kioFlAttribLockedMask = 0x01, kioFlAttribResOpenBit = 2, kioFlAttribResOpenMask = 0x04, kioFlAttribDataOpenBit = 3, kioFlAttribDataOpenMask = 0x08, kioFlAttribDirBit = 4, kioFlAttribDirMask = 0x10, ioDirFlg = 4, ioDirMask = 0x10, kioFlAttribCopyProtBit = 6, kioFlAttribCopyProtMask = 0x40, kioFlAttribFileOpenBit = 7, kioFlAttribFileOpenMask = 0x80, kioFlAttribInSharedBit = 2, kioFlAttribInSharedMask = 0x04, kioFlAttribMountedBit = 3, kioFlAttribMountedMask = 0x08, kioFlAttribSharePointBit = 5, kioFlAttribSharePointMask = 0x20 };
kioFlAttribLockedBit
Indicates that the file or directory is locked. Use the functions PBHSetFLockSync
and PBHSetFLockAsync
to lock a file or directory. Use the functions PBHRstFLockSync
and PBHRstFLockAsync
to unlock a file or directory.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFlAttribLockedMask
Tests if the file or directory is locked.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFlAttribResOpenBit
Indicates that the resource fork is open. On Mac OS X, this bit is not set if the resource fork of the file has been opened by a process other than the process making the call to PBHGetCatInfo
or PBHGetFInfo
.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFlAttribResOpenMask
Tests if the resource fork is open.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFlAttribDataOpenBit
Indicates that the data fork is open. On Mac OS X, this bit is not set if the data fork of the file has been opened by a process other than the process making the call to PBHGetCatInfo
or PBHGetFInfo
.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFlAttribDataOpenMask
Tests if the data fork is open.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFlAttribDirBit
Indicates that this is a directory, not a file. This bit is always clear for files, and is always set for directories.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFlAttribDirMask
Tests if this is a directory.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
ioDirFlg
Indicates that this is a directory; this is the old name of the kioFlAttribDirBit
.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
ioDirMask
Tests if this is a directory; this is the old name of the kioFlAttribDirMask
.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFlAttribCopyProtBit
Indicates that the file is “copy-protected” by the AppleShare server.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFlAttribCopyProtMask
Tests if the file is “copy-protected” by the AppleShare server.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFlAttribFileOpenBit
Indicates that the file is open. This bit is set if either the data or the resource fork are open. On Mac OS X, this bit is not set if the file has been opened by a process other than the process making the call to PBHGetCatInfo
or PBHGetFInfo
.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFlAttribFileOpenMask
Tests if the file is open. The file is open if either the data or the resource fork are open.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFlAttribInSharedBit
Indicates that the directory is within a shared area of the directory hierarchy.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFlAttribInSharedMask
Tests if the directory is within a shared area of the directory hierarchy.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFlAttribMountedBit
Indicates that the directory is a share point that is mounted by a user.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFlAttribMountedMask
Tests if the directory is a share point that is mounted by a user.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFlAttribSharePointBit
Indicates that the directory is a share point.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioFlAttribSharePointMask
Tests if the directory is a share point.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
These constants are used in the ioFlAttrib
fields of the HFileInfo
and DirInfo
structures returned by the functions PBGetCatInfoSync
and PBGetCatInfoAsync
.
Flags you can use to specify how to perform a file operation.
enum { kFSFileOperationDefaultOptions = 0, kFSFileOperationOverwrite = 0x01, kFSFileOperationSkipSourcePermissionErrors = 0x02, kFSFileOperationDoNotMoveAcrossVolumes = 0x04, kFSFileOperationSkipPreflight = 0x08 };
kFSFileOperationDefaultOptions
Use the following default options:
If the destination directory contains an object with the same name as a source object, abort the operation.
If a source object cannot be read, abort the operation.
If asked to move an object across volume boundaries, perform the operation.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
kFSFileOperationOverwrite
If the destination directory contains an object with the same name as a source object, overwrite the destination object.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
kFSFileOperationSkipSourcePermissionErrors
If a source object cannot be read, skip the object and continue the operation.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
kFSFileOperationDoNotMoveAcrossVolumes
If asked to move an object across volume boundaries, abort the operation.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
kFSFileOperationSkipPreflight
Skip the preflight stage for a directory move or copy operation. This option limits the status information that can be returned during the operation.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
These flags may be passed to any of the functions that initiate a file operation. For more information, see “Copying and Moving Objects Using Asynchronous High-Level File Operations.”
Constants used by the File Manager to indicate the current stage of an asynchronous file operation.
typedef UInt32 FSFileOperationStage; enum { kFSOperationStageUndefined = 0, kFSOperationStagePreflighting = 1, kFSOperationStageRunning = 2, kFSOperationStageComplete = 3 };
kFSOperationStageUndefined
The File Manager has not started the file operation.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
kFSOperationStagePreflighting
The File Manager is performing tasks such as calculating the sizes and number of objects in the operation, and checking to make sure there is enough space on the destination volume to complete the operation.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
kFSOperationStageRunning
The File Manager is copying or moving the file or directory.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
kFSOperationStageComplete
The file operation is complete.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
These constants are passed back to your file operation status callback function. For more information, see “File Operation Callbacks.” You can also get the current stage of a file operation by calling a status accessor function such as FSFileOperationCopyStatus
.
Keys used to determine the status of a file operation as reported in a status dictionary.
const CFStringRef kFSOperationTotalBytesKey; const CFStringRef kFSOperationBytesCompleteKey; const CFStringRef kFSOperationBytesRemainingKey; const CFStringRef kFSOperationTotalObjectsKey; const CFStringRef kFSOperationObjectsCompleteKey; const CFStringRef kFSOperationObjectsRemainingKey; const CFStringRef kFSOperationTotalUserVisibleObjectsKey; const CFStringRef kFSOperationUserVisibleObjectsCompleteKey; const CFStringRef kFSOperationUserVisibleObjectsRemainingKey; const CFStringRef kFSOperationThroughputKey;
kFSOperationTotalBytesKey
The value for this key is a CFNumber that represents the total number of bytes that will be moved or copied by this file operation. This value is not available for a directory operation if the kFSFileOperationSkipPreflight
option flag is specified.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
kFSOperationBytesCompleteKey
The value for this key is a CFNumber that represents the total number of bytes that have already been moved or copied by this file operation.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
kFSOperationBytesRemainingKey
The value for this key is a CFNumber that represents the total number of bytes that remain to be moved or copied by this file operation.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
kFSOperationTotalObjectsKey
The value for this key is a CFNumber that represents the total number of objects that will be moved or copied by this file operation.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
kFSOperationObjectsCompleteKey
The value for this key is a CFNumber that represents the total number of objects that have already been moved or copied by this file operation.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
kFSOperationObjectsRemainingKey
The value for this key is a CFNumber that represents the total number of objects that remain to be moved or copied by this file operation.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
kFSOperationTotalUserVisibleObjectsKey
The value for this key is a CFNumber that represents the total number of user-visible objects that will be moved or copied by this file operation. In general, an object is user-visible if it is displayed in a Finder window. For example, a package is counted as a single user-visible object even though it typically contains many other objects.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
kFSOperationUserVisibleObjectsCompleteKey
The value for this key is a CFNumber that represents the total number of user-visible objects that have already been moved or copied by this file operation.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
kFSOperationUserVisibleObjectsRemainingKey
The value for this key is a CFNumber that represents the total number of user-visible objects that remain to be moved or copied by this file operation.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
kFSOperationThroughputKey
The value for this key is a CFNumber that represents the current throughput of this file operation in bytes per second.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
The status dictionary for a file operation is passed back to your status callback function. For more information, see “File Operation Callbacks.” You can also get the status dictionary for a file operation by calling a status accessor function such as FSFileOperationCopyStatus
.
typedef UInt32 FNMessage; enum { kFNDirectoryModifiedMessage = 1 };
Identifies the A/UX privilege model.
enum { fsUnixPriv = 1 };
fsUnixPriv
Represents a volume that supports the A/UX privilege model.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
Used in the vMForeignPrivID
field of the GetVolParmsInfoBuffer
.
enum { knoGroup = 0 };
Specify the sizes of the desktop database icon types.
enum { kLargeIconSize = 256, kLarge4BitIconSize = 512, kLarge8BitIconSize = 1024, kSmallIconSize = 64, kSmall4BitIconSize = 128, kSmall8BitIconSize = 256 };
kLargeIconSize
Large black-and-white icon with mask. Corresponding resource type: 'ICN#
'.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kLarge4BitIconSize
Large 4-bit color icon. Corresponding resource type: 'icl4
’.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kLarge8BitIconSize
Large 8-bit color icon. Corresponding resource type: 'icl8
'.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kSmallIconSize
Small black-and-white icon with mask. Corresponding resource type: 'ics#
'.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kSmall4BitIconSize
Small 4-bit color icon. Corresponding resource type: 'ics4
'.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kSmall8BitIconSize
Small 8-bit color icon. Corresponding resource type: 'ics8
'.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
These constants indicate the amount of storage you should allocate for the icon data for each of the icon types specified by the “Icon Type Constants.” The desktop database functions which set or retrieve icon data–namely, PBDTAddIconSync
, PBDTAddIconAsync
, PBDTGetIconSync
, PBDTGetIconAsync
, PBDTGetIconInfoSync
, and PBDTGetIconInfoAsync
–expect a pointer to the the storage in the ioDTBuffer
field of the DTPBRec
parameter block and the appropriate constant in the ioDTReqCount
field.
Specify the icon types for the desktop database.
enum { kLargeIcon = 1, kLarge4BitIcon = 2, kLarge8BitIcon = 3, kSmallIcon = 4, kSmall4BitIcon = 5, kSmall8BitIcon = 6, kicnsIconFamily = 239 };
kLargeIcon
Large black-and-white icon with mask. Corresponding resource type: 'ICN#
'.
Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.
Declared in Files.h
.
kLarge4BitIcon
Large 4-bit color icon. Corresponding resource type: 'icl4
’.
Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.
Declared in Files.h
.
kLarge8BitIcon
Large 8-bit color icon. Corresponding resource type: 'icl8
'.
Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.
Declared in Files.h
.
kSmallIcon
Small black-and-white icon with mask. Corresponding resource type: 'ics#
'.
Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.
Declared in Files.h
.
kSmall4BitIcon
Small 4-bit color icon. Corresponding resource type: 'ics4
'.
Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.
Declared in Files.h
.
kSmall8BitIcon
Small 8-bit color icon. Corresponding resource type: 'ics8
'.
Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.
Declared in Files.h
.
kicnsIconFamily
Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.
Declared in Files.h
.
These constants are used in the ioIconType
field of the DTPBRec
parameter block.
Represents an invalid volume reference number.
enum { kFSInvalidVolumeRefNum = 0 };
kFSInvalidVolumeRefNum
Invalid volume reference number.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
Indicate whether an iterator iterates over subtrees or just the immediate children of the container.
enum { kFSIterateFlat = 0, kFSIterateSubtree = 1, kFSIterateDelete = 2, kFSIterateReserved = 0xFFFFFFFC }; typedef OptionBits FSIteratorFlags;
kFSIterateFlat
Iterate over the immediate children of the container only.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSIterateSubtree
Iterate over the entire subtree rooted at the container.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSIterateDelete
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSIterateReserved
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
enum { kAsyncMountInProgress = 1, kAsyncMountComplete = 2, kAsyncUnmountInProgress = 3, kAsyncUnmountComplete = 4, kAsyncEjectInProgress = 5, kAsyncEjectComplete = 6 };
kAsyncMountInProgress
Available in Mac OS X v10.2 and later.
Declared in Files.h
.
kAsyncMountComplete
Available in Mac OS X v10.2 and later.
Declared in Files.h
.
kAsyncUnmountInProgress
Available in Mac OS X v10.2 and later.
Declared in Files.h
.
kAsyncUnmountComplete
Available in Mac OS X v10.2 and later.
Declared in Files.h
.
kAsyncEjectInProgress
Available in Mac OS X v10.2 and later.
Declared in Files.h
.
kAsyncEjectComplete
Available in Mac OS X v10.2 and later.
Declared in Files.h
.
Options that can be specified at subscription time.
enum { kFNNoImplicitAllSubscription = (1 << 0), kFNNotifyInBackground = (1 << 1) };
kFNNoImplicitAllSubscription
Specify this option if you do not want to receive notifications on this subscription when FNNotifyAll
is called. By default, any subscription is also implicitly a subscription to wildcard notifications.
Available in Mac OS X v10.1 and later.
Declared in Files.h
.
kFNNotifyInBackground
Specify this option if you want to receive notifications on this subscription when your application is in background. By default, notifications will be coalesced and and delivered when your application becomes foreground.
Available in Mac OS X v10.3 and later.
Declared in Files.h
.
enum { kHFSCatalogNodeIDsReusedBit = 12, kHFSCatalogNodeIDsReusedMask = 1 << kHFSCatalogNodeIDsReusedBit };
kHFSCatalogNodeIDsReusedBit
Available in Mac OS X v10.0 through Mac OS X v10.3.
Declared in HFSVolumes.h
.
kHFSCatalogNodeIDsReusedMask
Available in Mac OS X v10.0 through Mac OS X v10.3.
Declared in HFSVolumes.h
.
enum { kWidePosOffsetBit = 8, kUseWidePositioning = (1 << kWidePosOffsetBit), kMaximumBlocksIn4GB = 0x007FFFFF };
kWidePosOffsetBit
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kUseWidePositioning
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kMaximumBlocksIn4GB
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
Specify the type of object to map or return.
enum { kOwnerID2Name = 1, kGroupID2Name = 2, kOwnerName2ID = 3, kGroupName2ID = 4, kReturnNextUser = 1, kReturnNextGroup = 2, kReturnNextUG = 3 };
kOwnerID2Name
Map a user ID to the user name. Used with the PBHMapIDSync
or PBHMapIDAsync
functions.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kGroupID2Name
Map a group ID to the group name. Used with the PBHMapIDSync
or PBHMapIDAsync
functions.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kOwnerName2ID
Map a user name to the user ID. Used with the PBHMapNameSync
or PBHMapNameAsync
functions.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kGroupName2ID
Map a group name to the group ID. Used with the PBHMapNameSync
or PBHMapNameAsync
functions.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kReturnNextUser
Return the next user entry.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kReturnNextGroup
Return the next group entry.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kReturnNextUG
Return the next user or group entry.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
These constants are used in the ioObjType
field of the ObjParam
parameter block. The first four constants are passed to the PBHMapIDSync
, PBHMapIDAsync
, PBHMapNameSync
, and PBHMapNameAsync
functions to specify the mapping to be performed. The last three constants are passed to the PBGetUGEntrySync
or PBGetUGEntryAsync
functions to specify the type of object to be returned.
Specify how a pathname is converted to an FSRef
structure by the function FSPathMakeRefWithOptions
.
enum { kFSPathMakeRefDefaultOptions = 0, kFSPathMakeRefDoNotFollowLeafSymlink = 0x01 };
kFSPathMakeRefDefaultOptions
Use the default options.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
kFSPathMakeRefDoNotFollowLeafSymlink
When converting a path that refers to a symbolic link, do not follow the link. The new FSRef
should refer to the link itself.
Available in Mac OS X v10.4 and later.
Declared in Files.h
.
Together with an offset, specify a position within a fork.
enum { fsAtMark = 0, fsFromStart = 1, fsFromLEOF = 2, fsFromMark = 3 };
fsAtMark
The starting point is the access path’s current position. The offset is ignored.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsFromStart
The starting point is offset bytes from the start of the fork. The offset must be non-negative.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsFromLEOF
The starting point is offset bytes from the logical end of the fork. The offset must not be positive.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsFromMark
The starting point is offset bytes from the access path’s current position. The offset may be positive or negative.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
These constants are used in the ioPosMode
and positionMode
fields and parameters of the HFS and HFS Plus file access functions. These functions include those for reading from and writing to files or forks, changing the current position within a file or fork, changing the size of a file or fork, and allocating space to a file or fork.
For the FSReadFork
and FSWriteFork
calls, you may also add either of the pleaseCacheMask
or noCacheMask
constants to hint whether the data should be cached or not. See “Cache Constants.”
Specify the directory IDs of the root directory of a volume and its parent.
enum { fsRtParID = 1, fsRtDirID = 2 };
fsRtParID
Represents the directory ID of the root directory’s parent directory. The root directory has no parent this constant is used when specifying the root directory to functions which require the parent directory ID to identify directories.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
fsRtDirID
Represents the directory ID of the volume’s root directory.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
Specify basic user IDs for shared directories.
enum { knoUser = 0, kadministratorUser = 1 };
knoUser
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kadministratorUser
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
Specify the user privileges for a directory on a remote volume.
enum { kioACUserNoSeeFolderBit = 0, kioACUserNoSeeFolderMask = 0x01, kioACUserNoSeeFilesBit = 1, kioACUserNoSeeFilesMask = 0x02, kioACUserNoMakeChangesBit = 2, kioACUserNoMakeChangesMask = 0x04, kioACUserNotOwnerBit = 7, kioACUserNotOwnerMask = 0x80 };
kioACUserNoSeeFolderBit
Set if the user does not have “See Folders” privileges. Without “See Folders” privileges, the user cannot see other directories in the specified directory.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACUserNoSeeFolderMask
Tests if the user has “See Folders” privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACUserNoSeeFilesBit
Set if the user does not have “See Files” privileges. Without “See Files” privileges, the user cannot open documents or applications in the specified directory.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACUserNoSeeFilesMask
Tests if the user has “See Files” privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACUserNoMakeChangesBit
Set if the user does not have “Make Changes” privileges. Without “Make Changes” privileges, the user cannot create, modify, rename, or delete any file or directory within the specified directory.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACUserNoMakeChangesMask
Tests if the user has “Make Changes” privileges.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACUserNotOwnerBit
Set if the user is not the owner of the directory.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioACUserNotOwnerMask
Tests whether the user is the owner of the directory.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
These constants are used in the ioACUser
field of the HFileInfo
and DirInfo
structures returned by the PBGetCatInfoSync
and PBGetCatInfoAsync
functions.
Bit position constants that specify volume attributes.
enum { bLimitFCBs = 31, bLocalWList = 30, bNoMiniFndr = 29, bNoVNEdit = 28, bNoLclSync = 27, bTrshOffLine = 26, bNoSwitchTo = 25, bNoDeskItems = 20, bNoBootBlks = 19, bAccessCntl = 18, bNoSysDir = 17, bHasExtFSVol = 16, bHasOpenDeny = 15, bHasCopyFile = 14, bHasMoveRename = 13, bHasDesktopMgr = 12, bHasShortName = 11, bHasFolderLock = 10, bHasPersonalAccessPrivileges = 9, bHasUserGroupList = 8, bHasCatSearch = 7, bHasFileIDs = 6, bHasBTreeMgr = 5, bHasBlankAccessPrivileges = 4, bSupportsAsyncRequests = 3, bSupportsTrashVolumeCache = 2 }; enum { bHasDirectIO = 1 };
bLimitFCBs
The Finder limits the number of file control blocks used during copying to 8 instead of 16.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bLocalWList
The Finder uses the returned shared volume handle for its local window list.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bNoMiniFndr
Reserved; always set to 1.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bNoVNEdit
This volume’s name cannot be edited.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bNoLclSync
Don’t let the Finder change the modification date.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bTrshOffLine
Any time this volume goes offline, it is zoomed to the Trash and unmounted.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bNoSwitchTo
The Finder will not switch launch to any application on this volume.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bNoDeskItems
Don’t place objects in this volume on the Finder desktop.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bNoBootBlks
This volume is not a startup volume. The Startup menu item is disabled. Boot blocks are not copied during copy operations.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bAccessCntl
This volume supports AppleTalk AFP access-control interfaces. The following functions are supported:
PBHGetLogInInfoSync
PBHGetLogInInfoAsync
PBHGetDirAccessSync
PBHGetDirAccessAsync
PBHSetDirAccessSync
PBHSetDirAccessAsync
PBHMapIDSync
PBHMapIDAsync
PBHMapNameSync
PBHMapNameAsync
Special folder icons are used. The Access Privileges menu command is enabled for disk and folder items. The ioFlAttrib
field of the parameter block passed to the PBGetCatInfoSync
and PBGetCatInfoSync
functions is assumed to be valid.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bNoSysDir
This volume doesn’t support a system directory. Do not switch launch to this volume.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bHasExtFSVol
This volume is an external file system volume.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bHasOpenDeny
This volume supports the PBHOpenDenySync
, PBHOpenDenyAsync
, PBHOpenRFDenySync
and PBHOpenRFDenyAsync
functions.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bHasCopyFile
This volume supports the PBHCopyFileSync
and PBHCopyFileAsync
functions, which is used in copy and duplicate operations if both source and destination volumes have the same server address.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bHasMoveRename
This volume supports the PBHMoveRenameSync
and PBHMoveRenameAsync
functions.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bHasDesktopMgr
This volume supports all of the desktop functions.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bHasShortName
This volume supports AFP short names.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bHasFolderLock
Folders on the volume can be locked, and so they cannot be deleted or renamed.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bHasPersonalAccessPrivileges
This volume has local file sharing enabled.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bHasUserGroupList
This volume supports the Users and Groups file and thus the AFP privilege functions.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bHasCatSearch
This volume supports the PBCatSearchSync
and PBCatSearchAsync
functions.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bHasFileIDs
This volume supports the file ID functions, including the PBExchangeFilesSync
and PBExchangeFilesAsync
functions.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bHasBTreeMgr
Reserved for internal use.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bHasBlankAccessPrivileges
This volume supports inherited access privileges for folders (blank access privileges).
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bSupportsAsyncRequests
This volume correctly handles asynchronous requests at any time.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
bSupportsTrashVolumeCache
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
These constants correspond to bit positions in the vMAttrib
field of the GetVolParmsInfoBuffer
structure returned by the PBHGetVolParmsSync
and PBHGetVolParmsAsync
functions.
Used in the vcbFlags
field of a volume control block to specify information about a volume.
enum { kVCBFlagsIdleFlushBit = 3, kVCBFlagsIdleFlushMask = 0x0008, kVCBFlagsHFSPlusAPIsBit = 4, kVCBFlagsHFSPlusAPIsMask = 0x0010, kVCBFlagsHardwareGoneBit = 5, kVCBFlagsHardwareGoneMask = 0x0020, kVCBFlagsVolumeDirtyBit = 15, kVCBFlagsVolumeDirtyMask = 0x8000 };
kVCBFlagsIdleFlushBit
Indicates that the volume should be flushed at idle time.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kVCBFlagsIdleFlushMask
Flushes the volume at idle time.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kVCBFlagsHFSPlusAPIsBit
Indicates that the volume directly implements the HFS Plus APIs (rather than emulating them).
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kVCBFlagsHFSPlusAPIsMask
The volume directly implements the HFS Plus APIs.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kVCBFlagsHardwareGoneBit
Indicates that the disk driver returned a hardwareGoneErr
in response to a read or write call.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kVCBFlagsHardwareGoneMask
Tests if the disk driver returned a hardwareGoneErr
in response to a read or write call.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kVCBFlagsVolumeDirtyBit
Indicates that the volume information has changed since the last time the volume was flushed.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kVCBFlagsVolumeDirtyMask
The volume has changed since the last time the volume was flushed.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
See VCB
for a description of the volume control block.
Define volume attributes returned by the functions PBHGetVInfoSync
, PBHGetVInfoAsync
, PBXGetVolInfoSync
, and PBXGetVolInfoAsync
.
enum { kioVAtrbDefaultVolumeBit = 5, kioVAtrbDefaultVolumeMask = 0x0020, kioVAtrbFilesOpenBit = 6, kioVAtrbFilesOpenMask = 0x0040, kioVAtrbHardwareLockedBit = 7, kioVAtrbHardwareLockedMask = 0x0080, kioVAtrbSoftwareLockedBit = 15, kioVAtrbSoftwareLockedMask = 0x8000 };
kioVAtrbDefaultVolumeBit
Indicates that the volume is the default volume.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioVAtrbDefaultVolumeMask
Tests if the volume is the default volume.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioVAtrbFilesOpenBit
Indicates that there are open files or iterators.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioVAtrbFilesOpenMask
Tests if there are open files or iterators.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioVAtrbHardwareLockedBit
Indicates that the volume is locked by a hardware setting. On Mac OS X, the File Manager only sets the software locked bit for CDs and other read-only media; it does not set the hardware locked bit.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioVAtrbHardwareLockedMask
Tests if the volume is locked by a hardware setting.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioVAtrbSoftwareLockedBit
Indicates that the volume is locked by software.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kioVAtrbSoftwareLockedMask
Tests if the volume is locked by software.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
These constants are used in the ioVAtrb
field of the HVolumeParam
parameter block returned by the PBHGetVInfoSync
and PBHGetVInfoAsync
functions, and in the ioVAtrb
field of the XVolumeParam
parameter block returned by the PBXGetVolInfoSync
and PBXGetVolInfoAsync
functions.
Indicate what volume information to set or retrieve.
enum { kFSVolInfoNone = 0x0000, kFSVolInfoCreateDate = 0x0001, kFSVolInfoModDate = 0x0002, kFSVolInfoBackupDate = 0x0004, kFSVolInfoCheckedDate = 0x0008, kFSVolInfoFileCount = 0x0010, kFSVolInfoDirCount = 0x0020, kFSVolInfoSizes = 0x0040, kFSVolInfoBlocks = 0x0080, kFSVolInfoNextAlloc = 0x0100, kFSVolInfoRsrcClump = 0x0200, kFSVolInfoDataClump = 0x0400, kFSVolInfoNextID = 0x0800, kFSVolInfoFinderInfo = 0x1000, kFSVolInfoFlags = 0x2000, kFSVolInfoFSInfo = 0x4000, kFSVolInfoDriveInfo = 0x8000, kFSVolInfoGettableInfo = 0xFFFF, kFSVolInfoSettableInfo = 0x3004 };
kFSVolInfoNone
No volume information.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoCreateDate
Retrieve the creation date of the volume.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoModDate
Retrieve the date of the volume’s last modification.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoBackupDate
Retrieve or set the date of the volume’s last backup.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoCheckedDate
Retrieve the date that the volume was last checked for consistency.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoFileCount
Retrieve the number of files on the volume.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoDirCount
Retrieve the number of directories on the volume.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoSizes
Retrieve the total number of bytes on the volume and the number of unused bytes on the volume (in the totalBytes
and freeBytes
fields).
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoBlocks
Retrieve the block information: the block size, the number of total blocks on the volume, and the number of free blocks on the volume.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoNextAlloc
Retrieve the address at which to start the next allocation.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoRsrcClump
Retrieve the resource fork clump size.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoDataClump
Retrieve the data fork clump size.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoNextID
Retrieve the next available catalog node ID.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoFinderInfo
Retrieve or set the volume’s Finder information.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoFlags
Retrieve or set the volume’s flags. See “Volume Information Flags” for more information on the volume’s flags.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoFSInfo
Retrieve the filesystem ID and signature.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoDriveInfo
Retrieve the drive information: the drive number and driver reference number.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoGettableInfo
Retrieve all of the gettable information.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolInfoSettableInfo
Set all of the settable information. Currently, this is the backup date, Finder information, and flags.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
These constants are used with the FSVolumeInfoBitmap
data type to indicate what volume information to set or retrieve with the functions FSSetVolumeInfo
and FSGetVolumeInfo
, and their corresponding parameter block calls.
Used by the FSVolumeInfo
structure to specify characteristics of a volume.
enum { kFSVolFlagDefaultVolumeBit = 5, kFSVolFlagDefaultVolumeMask = 0x0020, kFSVolFlagFilesOpenBit = 6, kFSVolFlagFilesOpenMask = 0x0040, kFSVolFlagHardwareLockedBit = 7, kFSVolFlagHardwareLockedMask = 0x0080, kFSVolFlagSoftwareLockedBit = 15, kFSVolFlagSoftwareLockedMask = 0x8000 };
kFSVolFlagDefaultVolumeBit
Set if the volume is the default volume.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolFlagDefaultVolumeMask
Indicates that the volume is the default volume.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolFlagFilesOpenBit
Set if there are open files or iterators.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolFlagFilesOpenMask
Indicates that there are open files or iterators.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolFlagHardwareLockedBit
Set if the volume is locked by a hardware setting. On Mac OS X, the File Manager only sets the software locked bit for CDs and other read-only media; it does not set the hardware locked bit.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolFlagHardwareLockedMask
Indicates that the volume is locked by a hardware setting.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolFlagSoftwareLockedBit
Set if the volume is locked by software.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
kFSVolFlagSoftwareLockedMask
Indicates that the volume is locked by software.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
See the flags
field of the FSVolumeInfo
structure.
Define flags used by the volume mounting information structures.
enum { volMountNoLoginMsgFlagBit = 0, volMountNoLoginMsgFlagMask = 0x0001, volMountExtendedFlagsBit = 7, volMountExtendedFlagsMask = 0x0080, volMountInteractBit = 15, volMountInteractMask = 0x8000, volMountChangedBit = 14, volMountChangedMask = 0x4000, volMountFSReservedMask = 0x00FF, volMountSysReservedMask = 0xFF00 };
volMountNoLoginMsgFlagBit
Indicates that any log-in message or greeting dialog will be suppressed.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
volMountNoLoginMsgFlagMask
Tells the file system to suppress any log-in message or greeting dialog.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
volMountExtendedFlagsBit
Indicates that the mounting information is a AFPXVolMountInfo
record for AppleShare Client version 3.7 and later.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
volMountExtendedFlagsMask
Tells the file system that the mounting information is an AFPXVolMountInfo
record for AppleShare Client version 3.7 and later.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
volMountInteractBit
Indicates that it's safe for the file system to perform user interaction to mount the volume.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
volMountInteractMask
Tells the file system that it’s safe to perform user interaction to mount the volume.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
volMountChangedBit
Indicates that the volume was mounted, but the volume mounting information record needs to be updated.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
volMountChangedMask
Tests if the volume mounting information record needs to be updated.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
volMountFSReservedMask
Reserved.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
volMountSysReservedMask
Reserved.
Available in Mac OS X v10.0 and later.
Declared in Files.h
.
Bits 0-7 are defined by each file system for its own use; bits 8-15 are reserved for Apple system use. These constants are used in the flags
fields of the AFPVolMountInfo
, AFPXVolMountInfo
, and VolumeMountInfoHeader
structures.
The most common result codes returned by File Manager functions are listed below.
© 2001, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-07-13)