Mac Developer Library

Developer

CoreServices Framework Reference File Manager Reference

Options
Deployment Target:

On This Page
Language:

File Manager Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreServices

Objective-C

@import CoreServices;

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

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

Functions

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

    Deprecation Statement

    At the Foundation layer, use getResourceValue:forKey:error: or resourceValuesForKeys:error: instead. At the Core Foundation layer, use CFURLCopyResourcePropertyForKey or CFURLCopyResourcePropertiesForKeys instead.

    Declaration

    Objective-C

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

    Parameters

    ref

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

    whichInfo

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

    catalogInfo

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

    outName

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

    fsSpec

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

    parentRef

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

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

    Return Value

    A result code. See File Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Returns catalog information about a file or directory.

    Deprecation Statement

    At the Foundation layer, use getResourceValue:forKey:error: or resourceValuesForKeys:error: instead. At the Core Foundation layer, use CFURLCopyResourcePropertyForKey or CFURLCopyResourcePropertiesForKeys instead.

    Declaration

    Objective-C

    OSErr PBGetCatInfoSync ( CInfoPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to an HFS catalog information parameter block. See CInfoPBRec for a description of the CInfoPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The PBGetCatInfoSync function returns information about a file or directory, depending on the values you specify in the ioFDirIndex, ioNamePtr, ioVRefNum, and ioDirID or ioDrDirID fields. If you need to determine whether the information returned is for a file or a directory, you can test bit 4 of the ioFlAttrib field; if that bit is set, the information returned describes a directory.

    The PBGetCatInfoSync function selects a file or directory according to these rules:

    • If the value of ioFDirIndex is positive, ioNamePtr is not used as an input parameter and PBGetCatInfoSync returns information about the file or directory whose directory index is ioFDirIndex in the directory specified by ioDirID (or ioDrDirID) on the volume specified by ioVRefNum (this will be the root directory if ioVRefNum is a volume reference number or a drive number and ioDirID is 0). If ioNamePtr is not NULL, then it must point to a Str31 buffer where the file or directory name will be returned.

    • If the value of ioFDirIndex is 0, PBGetCatInfoSync returns information about the file or directory specified by ioNamePtr in the directory specified by ioDirID (or ioDrDirID) on the volume specified by ioVRefNum (again, this will be the root directory if ioVRefNum is a volume reference number or a drive number and ioDirID is 0).

    • If the value of ioFDirIndex is negative, PBGetCatInfoSync ignores the ioNamePtr field and returns information about the directory specified in the ioDrDirID field. If ioNamePtr is not NULL, then it must point to a Str31 buffer where the directory name will be returned.

    With files, PBGetCatInfoSync is similar to PBHGetFInfoSync but returns some additional information. If the object is a file, the relevant fields of the parameter block are:

    ioNamePtr

    On input, a pointer to a pathname. On output, the name of the file is returned in this field, if the file is open. If you do not want the name of the file returned, pass NULL in this field.

    ioVRefNum

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

    ioFRefNum

    On output, a file reference number. If the file is open, the reference number of the first access path found is returned here.

    ioFDirIndex

    On input, a directory index.

    ioFlAttrib

    On output, the file attributes. See File Attribute Constants for the meaning of the file attributes.

    ioFlFndrInfo

    On output, information used by the Finder.

    ioDirID

    On input, a directory ID. On output, the file ID. You might need to save the value of ioDirID before calling PBGetCatInfoSync if you make subsequent calls with the same parameter block.

    ioFlStBlk

    On output, the first allocation block of the data fork.

    ioFlLgLen

    On output, the logical size (the logical end-of-file) of the data fork, in bytes.

    ioFlPyLen

    On output, the physical size (the physical end-of-file) of the data fork, in bytes.

    ioFlRStBlk

    On output, the first allocation block of the resource fork.

    ioFlRLgLen

    On output, the logical size of the resource fork, in bytes.

    ioFlRPyLen

    On output, the physical size of the resource fork, in bytes.

    ioFlCrDat

    On output, the date and time of the file’s creation. 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, the File Manager sets the ioFlCrDat field to 0.

    ioFlMdDat

    On output, the date and time of the file’s last modification.

    ioFlBkDat

    On output, the date and time of the file’s last backup. 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, the File Manager sets the ioFlBkDat field to 0.

    ioFlXFndrInfo

    On output, additional information used by the Finder.

    ioFlParID

    On output, the directory ID of the file’s parent directory.

    ioFlClpSiz

    On output, the file’s clump size.

    You can also use PBGetCatInfoSync to determine whether a file has a file ID reference. The value of the file ID is returned in the ioDirID field. Because that parameter could also represent a directory ID, call PBResolveFileIDRefSync to see if the value is a real file ID. If you want to determine whether a file ID reference exists for a file and create one if it doesn’t, use PBCreateFileIDRefSync , which will either create a file ID or return fidExists.

    If the object is a directory, the relevant fields of the parameter block are:

    ioNamePtr

    On input, a pointer to a pathname. On output, a pointer to the directory’s name.

    ioVRefNum

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

    ioFDirIndex

    On input, a directory index.

    ioFlAttrib

    On output, the directory attributes. See File Attribute Constants for the meaning of the bits in this field. The bits in this field for directories are read-only. You cannot alter directory attributes by setting these bits using the functions PBSetCatInfoSync or PBSetCatInfoAsync. Instead, you can call the PBHSetFLockSync and PBHRstFLockSync functions to lock and unlock a directory, and the PBShareSync and PBUnshareSync functions to enable and disable file sharing on local directories.

    ioACUser

    On output, the directory access rights. The PBGetCatInfoSync function returns the information in this field only for shared volumes. As a result, you should set this field to 0 before calling PBGetCatInfoSync. PBGetCatInfoSync does not return the blank access privileges bit in this field; to determine whether a directory has blank access privileges, use the PBHGetDirAccessSync function. See User Privileges Constants for a description of the constants that may be returned here.

    ioDrUsrWds

    On output, information used by the Finder.

    ioDrDirID

    On input, if you wish to obtain information about a specific directory, that directory’s ID. Otherwise, if the object returned is a directory, this field contains the directory ID on output.

    ioDrNmFls

    On output, the number of files in the directory.

    ioDrCrDat

    On output, the date and time of the directory’s creation. 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, the File Manager sets the ioDrCrDat field to 0.

    ioDrMdDat

    On output, the date and time of the directory’s last modification.

    ioDrBkDat

    On output, the date and time of the directory’s last backup. 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, the File Manager sets the ioDrBkDat field to 0.

    ioDrFndrInfo

    On output, additional information used by the Finder.

    ioDrParID

    On output, the directory ID of the directory’s parent directory.

    To get information on a file or directory with named forks, or on a file larger than 2GB, use one of the FSGetCatalogInfo , PBGetCatalogInfoSync , or PBGetCatalogInfoAsync functions.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

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

    Deprecation Statement

    At the Foundation layer, use getResourceValue:forKey:error: or resourceValuesForKeys:error: instead. At the Core Foundation layer, use CFURLCopyResourcePropertyForKey or CFURLCopyResourcePropertiesForKeys instead.

    Declaration

    Objective-C

    OSErr PBGetCatalogInfoSync ( FSRefParam *paramBlock );

    Parameters

    paramBlock

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

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    ref

    On input, a pointer to an FSRef 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Returns catalog information about a file or directory.

    Deprecation Statement

    At the Foundation layer, use getResourceValue:forKey:error: or resourceValuesForKeys:error: instead. At the Core Foundation layer, use CFURLCopyResourcePropertyForKey or CFURLCopyResourcePropertiesForKeys instead.

    Declaration

    Objective-C

    OSErr PBGetCatInfoAsync ( CInfoPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to an HFS catalog information parameter block. See CInfoPBRec for a description of the CInfoPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The PBGetCatInfoAsync function returns information about a file or directory, depending on the values you specify in the ioFDirIndex, ioNamePtr, ioVRefNum, and ioDirID or ioDrDirID fields. If you need to determine whether the information returned is for a file or a directory, you can test bit 4 of the ioFlAttrib field; if that bit is set, the information returned describes a directory.

    The PBGetCatInfoAsync function selects a file or directory according to these rules:

    • If the value of ioFDirIndex is positive, ioNamePtr is not used as an input parameter and PBGetCatInfoAsync returns information about the file or directory whose directory index is ioFDirIndex in the directory specified by ioDirID (or ioDrDirID) on the volume specified by ioVRefNum (this will be the root directory if ioVRefNum is a volume reference number or a drive number and ioDirID is 0). If ioNamePtr is not NULL, then it must point to a Str31 buffer where the file or directory name will be returned.

    • If the value of ioFDirIndex is 0, PBGetCatInfoAsync returns information about the file or directory specified by ioNamePtr in the directory specified by ioDirID (or ioDrDirID) on the volume specified by ioVRefNum (again, this will be the root directory if ioVRefNum is a volume reference number or a drive number and ioDirID is 0).

    • If the value of ioFDirIndex is negative, PBGetCatInfoAsync ignores the ioNamePtr field and returns information about the directory specified in the ioDrDirID field. If ioNamePtr is not NULL, then it must point to a Str31 buffer where the directory name will be returned.

    With files, PBGetCatInfoAsync is similar to PBHGetFInfoAsync but returns some additional information. If the object is a file, 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.

    ioNamePtr

    On input, a pointer to a pathname. On output, the name of the file is returned in this field, if the file is open. If you do not want the name of the file returned, pass NULL in this field.

    ioVRefNum

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

    ioFRefNum

    On output, a file reference number. If the file is open, the reference number of the first access path found is returned here .

    ioFDirIndex

    On input, a directory index.

    ioFlAttrib

    On output, the file attributes. See File Attribute Constants for the meaning of the file attributes.

    ioFlFndrInfo

    On output, information used by the Finder.

    ioDirID

    On input, a directory ID. On output, the file ID. You might need to save the value of ioDirID before calling PBGetCatInfoAsync if you make subsequent calls with the same parameter block.

    ioFlStBlk

    On output, the first allocation block of the data fork.

    ioFlLgLen

    On output, the logical size (the logical end-of-file) of the data fork, in bytes.

    ioFlPyLen

    On output, the physical size (the physical end-of-file) of the data fork, in bytes.

    ioFlRStBlk

    On output, the first allocation block of the resource fork.

    ioFlRLgLen

    On output, the logical size of the resource fork, in bytes.

    ioFlRPyLen

    On output, the physical size of the resource fork, in bytes.

    ioFlCrDat

    On output, the date and time of the file’s creation. 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, the File Manager sets the ioFlCrDat field to 0.

    ioFlMdDat

    On output, the date and time of the file’s last modification.

    ioFlBkDat

    On output, the date and time of the file’s last backup. 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, the File Manager sets the ioFlBkDat field to 0.

    ioFlXFndrInfo

    On output, additional information used by the Finder.

    ioFlParID

    On output, the directory ID of the file’s parent directory.

    ioFlClpSiz

    On output, the file’s clump size.

    You can also use PBGetCatInfoAsync to determine whether a file has a file ID reference. The value of the file ID is returned in the ioDirID field. Because that parameter could also represent a directory ID, call PBResolveFileIDRefAsync to see if the value is a real file ID. If you want to determine whether a file ID reference exists for a file and create one if it doesn’t, use PBCreateFileIDRefAsync , which will either create a file ID or return fidExists.

    If the object is a directory, 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.

    ioNamePtr

    On input, a pointer to a pathname. On output, a pointer to the directory name.

    ioVRefNum

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

    ioFDirIndex

    On input, a directory index.

    ioFlAttrib

    On output, the directory attributes. See File Attribute Constants for the meaning of the bits in this field. The bits in this field for directories are read-only. You cannot alter directory attributes by setting these bits using the functions PBSetCatInfoSync or PBSetCatInfoAsync. Instead, you can call the PBHSetFLockSync and PBHRstFLockSync functions to lock and unlock a directory, and the PBShareSync and PBUnshareSync functions to enable and disable file sharing on local directories.

    ioACUser

    On output, the directory access rights. The PBGetCatInfoAsync function returns the information in this field only for shared volumes. As a result, you should set this field to 0 before calling PBGetCatInfoAsync.PBGetCatInfoAsync does not return the blank access privileges bit in this field; to determine whether a directory has blank access privileges, use the PBHGetDirAccessAsync function. See User Privileges Constants for a description of the constants that may be returned in this field.

    ioDrUsrWds

    On output, information used by the Finder.

    ioDrDirID

    On input, if you wish to obtain information about a specific directory, that directory’s ID. Otherwise, if the object returned is a directory, this field contains the directory ID on output.

    ioDrNmFls

    On output, the number of files in the directory.

    ioDrCrDat

    On output, the date and time of the directory’s creation. 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, the File Manager sets the ioDrCrDat field to 0.

    ioDrMdDat

    On output, the date and time of the directory’s last modification.

    ioDrBkDat

    On output, the date and time of the directory’s last backup. 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, the File Manager sets the ioDrBkDat field to 0.

    ioDrFndrInfo

    On output, additional information used by the Finder.

    ioDrParID

    On output, the directory ID of the directory’s parent directory.

    To get information on a file or directory with named forks, or on a file larger than 2GB, use one of the FSGetCatalogInfo , PBGetCatalogInfoSync , or PBGetCatalogInfoAsync functions.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

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

    Deprecation Statement

    At the Foundation layer, use getResourceValue:forKey:error: or resourceValuesForKeys:error: instead. At the Core Foundation layer, use CFURLCopyResourcePropertyForKey or CFURLCopyResourcePropertiesForKeys instead.

    Declaration

    Objective-C

    void PBGetCatalogInfoAsync ( FSRefParam *paramBlock );

    Parameters

    paramBlock

    A pointer to a file system reference parameter block. See FSRefParam fro s description of the FSRefParam data type.

    Discussion

    The relevant fields of the parameter block are:

    ioCompletion

    On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.

    ioResult

    On output, the result code of the function.

    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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Modifies catalog information for a file or directory.

    Deprecation Statement

    Use PBSetCatalogInfoSync instead.

    Declaration

    Objective-C

    OSErr PBSetCatInfoSync ( CInfoPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to an HFS catalog information parameter block. See CInfoPBRec for a description of the CInfoPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The PBSetCatInfoSync function sets information about a file or directory. When used to set information about a file, it works much as PBHSetFInfoSync does, but lets you set some additional information.

    If the object is a file, the relevant fields of the parameter block are:

    ioNamePtr

    On input, a pointer to a pathname.

    ioVRefNum

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

    ioFlFndrInfo

    On input, Finder information for the file.

    ioDirID

    On input, the parent directory ID of the file.

    ioFlCrDat

    On input, the date and time of the file’s creation.

    ioFlMdDat

    On input, the date and time of the file’s last modification.

    ioFlBkDat

    On input, the date and time of the file’s last backup.

    ioFlXFndrInfo

    On input, extended Finder information.

    If the object is a directory, the relevant fields of the parameter block are:

    ioNamePtr

    On input, a pointer to a pathname.

    ioVRefNum

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

    ioDrUsrWds

    On input, information used by the Finder.

    ioDrDirID

    On input, the directory ID.

    ioDrCrDat

    On input, the date and time of the directory’s creation.

    ioDrMdDat

    On input, the date and time of the directory’s last modification.

    ioDrBkDat

    On input, the date and time of the directory’s last backup.

    ioDrFndrInfo

    On input, additional information used by the Finder.

    To modify the catalog information for a named fork other than the data and resource fork, or to modify other catalog information maintained on HFS Plus volumes that is not modifiable through PBSetCatInfoSync, use one of the functions, FSSetCatalogInfo , PBSetCatalogInfoSync , or PBSetCatalogInfoAsync.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Sets catalog information about a file or directory.

    Deprecation Statement

    At the Foundation layer, use setResourceValue:forKey:error: or setResourceValues:error: instead. At the Core Foundation layer, use CFURLSetResourcePropertyForKey or CFURLSetResourcePropertiesForKeys instead.

    Declaration

    Objective-C

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

    Parameters

    ref

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

    whichInfo

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

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

    catalogInfo

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

    • createDate

    • contentModDate

    • attributeModDate

    • accessDate

    • backupDate

    • permissions

    • finderInfo

    • extFinderInfo

    • textEncodingHint

    Return Value

    A result code. See File Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Modifies catalog information for a file or directory.

    Deprecation Statement

    Use PBSetCatalogInfoAsync instead.

    Declaration

    Objective-C

    OSErr PBSetCatInfoAsync ( CInfoPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to an HFS catalog information parameter block. See CInfoPBRec for a description of the CInfoPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The PBSetCatInfoAsync function sets information about a file or directory. When used to set information about a file, it works much as PBHSetFInfoAsync does, but lets you set some additional information.

    If the object is a file, 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.

    ioNamePtr

    On input, a pointer to a pathname.

    ioVRefNum

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

    ioFlFndrInfo

    On input, Finder information for the file.

    ioDirID

    On input, the parent directory ID of the file.

    ioFlCrDat

    On input, the date and time of the file’s creation.

    ioFlMdDat

    On input, the date and time of the file’s last modification.

    ioFlBkDat

    On input, the date and time of the file’s last backup.

    ioFlXFndrInfo

    On input, extended Finder information.

    If the object is a directory, 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.

    ioNamePtr

    On input, a pointer to a pathname.

    ioVRefNum

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

    ioDrUsrWds

    On input, information used by the Finder.

    ioDrDirID

    On input, the directory ID.

    ioDrCrDat

    On input, the date and time of the directory’s creation.

    ioDrMdDat

    On input, the date and time of the directory’s last modification.

    ioDrBkDat

    On input, the date and time of the directory’s last backup.

    ioDrFndrInfo

    On input, additional information used by the Finder.

    To modify the catalog information for a named fork other than the data and resource fork, or to modify other catalog information maintained on HFS Plus volumes that is not modifiable through PBSetCatInfoAsync, use one of the functions, FSSetCatalogInfo , PBSetCatalogInfoSync , or PBSetCatalogInfoAsync.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Sets the catalog information about a file or directory.

    Deprecation Statement

    At the Foundation layer, use setResourceValue:forKey:error: or setResourceValues:error: instead. At the Core Foundation layer, use CFURLSetResourcePropertyForKey or CFURLSetResourcePropertiesForKeys instead.

    Declaration

    Objective-C

    OSErr PBSetCatalogInfoSync ( FSRefParam *paramBlock );

    Parameters

    paramBlock

    A pointer to a file system reference parameter block. See FSRefParam fro s description of the FSRefParam data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    ref

    On input, a pointer to an FSRef 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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Sets the catalog information about a file or directory.

    Deprecation Statement

    At the Foundation layer, use setResourceValue:forKey:error: or setResourceValues:error: instead. At the Core Foundation layer, use CFURLSetResourcePropertyForKey or CFURLSetResourcePropertiesForKeys instead.

    Declaration

    Objective-C

    void PBSetCatalogInfoAsync ( FSRefParam *paramBlock );

    Parameters

    paramBlock

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

    Discussion

    The relevant fields of the parameter block are:

    ioCompletion

    On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.

    ioResult

    On output, the result code of the function.

    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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • FSpGetFInfo FSpGetFInfo (OS X v10.4)

    Obtains the Finder information for a file.

    Deprecation Statement

    Use FSGetCatalogInfo instead.

    Declaration

    Objective-C

    OSErr FSpGetFInfo ( const FSSpec *spec, FInfo *fndrInfo );

    Parameters

    spec

    A pointer to an FSSpec structure specifying the file. See FSSpec for a description of the FSSpec data type.

    fndrInfo

    On return, a pointer to information used by the Finder. The FSpGetFInfo function returns the Finder information from the volume catalog entry for the specified file. The function provides only the original Finder information—the information in the FInfo or DInfo structures, not the information in the FXInfo or DXInfo structures. For a description of the FInfo structure, see the Finder Interface Reference.

    Return Value

    A result code. If the specified object is a folder, this function returns fnfErr. For other possible return values, see File Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • HGetFInfo HGetFInfo (OS X v10.4)

    Obtains the Finder information for a file.

    Deprecation Statement

    Use FSGetCatalogInfo instead.

    Declaration

    Objective-C

    OSErr HGetFInfo ( FSVolumeRefNum vRefNum, SInt32 dirID, ConstStr255Param fileName, FInfo *fndrInfo );

    Parameters

    vRefNum

    The volume reference number, drive number, or 0 for the default volume.

    dirID

    The parent directory ID of the file.

    fileName

    The name of the file.

    fndrInfo

    On return, a pointer to the Finder information stored in the specified volume’s catalog. The function returns only the original Finder information—that contained in an FInfo structure, not that in an FXInfo structure.

    Return Value

    A result code. See File Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Obtains information about a file.

    Deprecation Statement

    Use PBGetCatalogInfoSync instead.

    Declaration

    Objective-C

    OSErr PBHGetFInfoSync ( HParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to the HFileParam variant of the basic HFS parameter block. See HParamBlockRec for a description of the HParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    ioNamePtr

    On input, a pointer to a pathname. If the value of the ioFDirIndex field is negative or 0, PBHGetFInfoSync returns information about the file in the volume specified by the reference number in the ioVRefNum field and having the name given here. On output, a pointer to the name of the file, if the file is open. If you do not wish the name returned, pass NULL here.

    ioVRefNum

    On input, a volume reference number or drive number for the volume containing the file, or 0 for the default volume.

    ioFRefNum

    On output, the reference number of the first access path found, if the file is open and if the ioFDirIndex field is negative or 0; if the ioFDirIndex field is positive...

    ioFDirIndex

    On input, a directory index. If this value is positive, the function returns information about the file having the directory index specified here, on the volume specified in the ioVRefNum field and in the directory specified in the ioDirID field. If this value is negative or 0, the function returns information about the file on the specified volume, having the name pointed to in the ioNamePtr field.

    ioFlAttrib

    On output, the file attributes. See File Attribute Constants for a description of the file attributes.

    ioFlFndrInfo

    On output, Finder information about the file. For a description of the FInfo data type, see the Finder Interface Reference .

    ioDirID

    On input, the parent directory ID of the file. On output, the file’s file ID.

    ioFVersNum

    On input, this field should be initialized to zero; if this field is not zero, the call will fall through to the now-obsolete Macintosh File System (MFS) code if the volume accessed is an MFS volume.

    ioFlStBlk

    On output, the first allocation block of the data fork.

    ioFlLgLen

    On output, the logical size (the logical end-of-file) of the file’s data fork, in bytes.

    ioFlPyLen

    On output, the physical size (the physical end-of-file) of the file’s data fork, in bytes.

    ioFlRStBlk

    On output, the first allocation block of the resource fork.

    ioFlRLgLen

    On output, the logical size of the resource fork, in bytes.

    ioFlRPyLen

    On output, the physical size of the resource fork, in bytes.

    ioFlCrDat

    On output, the date and time of the file’s creation.

    ioFlMdDat

    On output, the date and time of the file’s last modification.

    You should call PBHGetFInfoSync just before PBHSetFInfoSync , so that the current information is present in the parameter block.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Obtains information about a file.

    Deprecation Statement

    Use PBGetCatalogInfoAsync instead.

    Declaration

    Objective-C

    OSErr PBHGetFInfoAsync ( HParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to the HFileParam variant of the basic HFS parameter block. See HParamBlockRec for a description of the HParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    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.

    ioNamePtr

    On input, a pointer to a pathname. If the value of the ioFDirIndex field is negative or 0, PBHGetFInfoAsync returns information about the file in the volume specified by the reference number in the ioVRefNum field and having the name given here. On output, a pointer to the name of the file, if the file is open. If you do not wish the name returned, pass NULL here.

    ioVRefNum

    On input, a volume reference number or drive number for the volume containing the file, or 0 for the default volume.

    ioFRefNum

    On output, the reference number of the first access path found, if the file is open and if the ioFDirIndex field is negative or 0; if the ioFDirIndex field is positive...

    ioFDirIndex

    On input, a directory index. If this value is positive, the function returns information about the file having the directory index specified here, on the volume specified in the ioVRefNum field and in the directory specified in the ioDirID field. If this value is negative or 0, the function returns information about the file on the specified volume, having the name pointed to in the ioNamePtr field.

    ioFlAttrib

    On output, the file attributes. See File Attribute Constants for a description of the file attributes.

    ioFlFndrInfo

    On output, Finder information about the file. For a description of the FInfo structure, see the Finder Interface Reference .

    ioDirID

    On input, the parent directory ID of the file. On output, the file’s file ID.

    ioFVersNum

    On input, this field should be initialized to zero; if this field is not zero, the call will fall through to the now-obsolete Macintosh File System (MFS) code if the volume accessed is an MFS volume.

    ioFlStBlk

    On output, the first allocation block of the data fork.

    ioFlLgLen

    On output, the logical size (the logical end-of-file) of the file’s data fork, in bytes.

    ioFlPyLen

    On output, the physical size (the physical end-of-file) of the file’s data fork, in bytes.

    ioFlRStBlk

    On output, the first allocation block of the resource fork.

    ioFlRLgLen

    On output, the logical size of the file’s resource fork, in bytes.

    ioFlRPyLen

    On output, the physical size of the file’s resource fork, in bytes.

    ioFlCrDat

    On output, the date and time of the file’s creation.

    ioFlMdDat

    On output, the date and time of the file’s last modification.

    You should call PBHGetFInfoAsync just before PBHSetFInfoAsync , so that the current information is present in the parameter block.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • FSpSetFInfo FSpSetFInfo (OS X v10.4)

    Sets the Finder information about a file.

    Deprecation Statement

    Use FSSetCatalogInfo instead.

    Declaration

    Objective-C

    OSErr FSpSetFInfo ( const FSSpec *spec, const FInfo *fndrInfo );

    Parameters

    spec

    A pointer to an FSSpec structure specifying the file for which to set the Finder information. See FSSpec for a description of the FSSpec data type.

    fndrInfo

    A pointer to the new Finder information. For a description of the FInfo data type, see the Finder Interface Reference.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The FSpSetFInfo function changes the Finder information in the volume catalog entry for the specified file. FSpSetFInfo allows you to set only the original Finder information—the information in the FInfo or DInfo structures, not the information in the FXInfo or DXInfo structures.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • HSetFInfo HSetFInfo (OS X v10.4)

    Sets the Finder information for a file.

    Deprecation Statement

    Use FSSetCatalogInfo instead.

    Declaration

    Objective-C

    OSErr HSetFInfo ( FSVolumeRefNum vRefNum, SInt32 dirID, ConstStr255Param fileName, const FInfo *fndrInfo );

    Parameters

    vRefNum

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

    dirID

    The parent directory ID of the file.

    fileName

    The name of the file.

    fndrInfo

    A pointer to the new Finder information. The function changes the Finder information stored in the volume’s catalog. HSetFInfo changes only the original Finder information—that contained in an FInfo structure, not that contained in an FXInfo structure. For a description of the FInfo data type, see the Finder Interface Reference.

    Return Value

    A result code. See File Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Sets information for a file.

    Deprecation Statement

    Use PBSetCatalogInfoSync instead.

    Declaration

    Objective-C

    OSErr PBHSetFInfoSync ( HParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to the HFileParam variant of the basic HFS parameter block. See HParamBlockRec for a description of the HParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    ioNamePtr

    On input, a pointer to the name of the file.

    ioVRefNum

    On input, the volume reference number or drive number for the volume containing the file; or 0 for the default volume.

    ioFlFndrInfo

    On input, Finder information for the file. For a description of the FInfo data type, see the Finder Interface Reference .

    ioDirID

    On input, the parent directory ID of the file.

    ioFVersNum

    On input, this field should be initialized to zero; if this field is not zero, the call will fall through to the now-obsolete Macintosh File System (MFS) code if the volume accessed is an MFS volume.

    ioFlCrDat

    On input, the date and time of the file’s creation.

    ioFlMdDat

    On input, the date and time of the file’s last modification.

    You should call the PBHGetFInfoSync function just before calling PBHSetFInfoSync, so that the current information is present in the parameter block.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Sets information for a file.

    Deprecation Statement

    Use PBSetCatalogInfoAsync instead.

    Declaration

    Objective-C

    OSErr PBHSetFInfoAsync ( HParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to the HFileParam variant of the basic HFS parameter block. See HParamBlockRec for a description of the HParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    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.

    ioNamePtr

    On input, a pointer to the name of the file.

    ioVRefNum

    On input, the volume reference number or drive number for the volume containing the file; or 0 for the default volume.

    ioFlFndrInfo

    On input, Finder information for the file. For a description of the FInfo data type, see the Finder Interface Reference .

    ioDirID

    On input, the parent directory ID for the file.

    ioFVersNum

    On input, this field should be initialized to zero; if this field is not zero, the call will fall through to the now-obsolete Macintosh File System (MFS) code if the volume accessed is an MFS volume.

    ioFlCrDat

    On input, the date and time of the file’s creation.

    ioFlMdDat

    On input, the date and time of the file’s last modification.

    You should call the PBHGetFInfoAsync function just before calling PBHSetFInfoAsync, so that the current information is present in the parameter block.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Adds an icon definition to the desktop database.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTAddIconSync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function are:

    ioDTRefNum

    On input, the desktop database reference number of the database to which you wish to add an icon.

    ioTagInfo

    Reserved; on input, this field must be set to 0.

    ioDTBuffer

    On input, a pointer to the buffer holding the icon’s bitmap.

    ioDTReqCount

    On input, the size in bytes of the buffer that you’ve allocated for the icon’s bitmap. This value depends on the icon type. Be sure to allocate enough storage for the icon data 1024 bytes is the largest amount required for any icon in System 7 For a description of the values you can use to indicate the icon’s size, see Icon Size Constants.

    ioIconType

    On input, the icon type. See Icon Type Constants for a description of the values you can use in this field.

    ioFileCreator

    On input, the icon’s file creator.

    ioFileType

    On input, the icon’s file type.

    If the database already contains an icon definition for an icon of that type, file type, and file creator, the new definition replaces the old.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Adds an icon definition to the desktop database.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTAddIconAsync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function 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”.

    ioDTRefNum

    On input, the desktop database reference number of the database to which you wish to add an icon.

    ioTagInfo

    Reserved; on input, this field must be set to 0.

    ioDTBuffer

    On input, a pointer to the buffer holding the icon’s bitmap.

    ioDTReqCount

    On input, the size in bytes of the buffer that you’ve allocated for the icon’s bitmap. This value depends on the icon type. Be sure to allocate enough storage for the icon data 1024 bytes is the largest amount required for any icon in System 7. For a description of the values you can use to indicate the icon’s size, see Icon Size Constants.

    ioIconType

    On input, the icon type. See Icon Type Constants for a description of the values you can use in this field.

    ioFileCreator

    On input, the icon’s file creator.

    ioFileType

    On input, the icon’s file type.

    If the database already contains an icon definition for an icon of that type, file type, and file creator, the new definition replaces the old.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Adds an application to the desktop database.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTAddAPPLSync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function are:

    ioNamePtr

    On input, a pointer to the application’s name.

    ioDTRefNum

    On input, the desktop database reference number of the desktop database to which you wish to add an application.

    ioTagInfo

    Reserved; on input, this field must be set to 0.

    ioDirID

    On input, the ID of the application’s parent directory.

    ioFileCreator

    On input, the application’s signature.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Adds an application to the desktop database.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTAddAPPLAsync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function 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”.

    ioNamePtr

    On input, a pointer to the application’s name.

    ioDTRefNum

    On input, the desktop database reference number of the desktop database to which you wish to add an application.

    ioTagInfo

    Reserved; on input, this field must be set to 0.

    ioDirID

    On input, the ID of the application’s parent directory.

    ioFileCreator

    On input, the application’s signature.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Closes the desktop database, though your application should never do this itself.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTCloseDown ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant field of the parameter block for this function is:

    ioDTRefNum

    On input, the desktop database reference number.

    System software uses the PBDTCloseDown function to close the desktop database; your application should never use this function, which is described here only for completeness. The system software closes the database when the volume is unmounted.

    PBDTCloseDown runs synchronously only, and though it will not close down the desktop databases of remote volumes, it will invalidate all local desktop database reference values for remote desktop databases.

    When the PBDTCloseDown function closes the database, it frees all resources allocated by PBDTOpenInform or PBDTGetPath.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Removes the desktop database. Unless you are manipulating the desktop database in the absence of the Finder, you should never use this function.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTDeleteSync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The PBDTDeleteSync function removes the desktop database from a local volume. You can call PBDTDeleteSync only when the database is closed. Your application should not call PBDTDeleteSync unless absolutely necessary.

    The relevant fields of the parameter block for this function are:

    ioVRefNum

    On input, the volume reference number of the desktop database to remove.

    ioIndex

    Reserved; on input, this field must be set to 0.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Removes the desktop database. Unless you are manipulating the desktop database in the absence of the Finder, you should never use this function.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTDeleteAsync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The PBDTDeleteAsync function removes the desktop database from a local volume. You can call PBDTDeleteAsync only when the database is closed. Your application should not call PBDTDeleteAsync unless absolutely necessary.

    The relevant fields of the parameter block for this function 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”.

    ioVRefNum

    On input, the volume reference number of the desktop database to remove.

    ioIndex

    Reserved; on input, this field must be set to 0.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Saves your changes to the desktop database.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTFlushSync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    If your application adds information to or removes information from the desktop database, use the PBDTFlushSync function to save your changes. The PBDTFlushSync function writes the contents of the desktop database specified in the ioDTRefNum field to the volume.

    The relevant field of the parameter block for this function is:

    ioDTRefNum

    On input, the desktop database reference number of the desktop database to flush.

    You must call PBDTFlushSync or PBDTFlushAsync to update the copy of the desktop database stored on the volume if your application has manipulated information in the database using any of the following functions:

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Saves your changes to the desktop database.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTFlushAsync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    If your application adds information to or removes information from the desktop database, use the PBDTFlushAsync function to save your changes. The PBDTFlushAsync function writes the contents of the desktop database specified in the ioDTRefNum field to the volume.

    The relevant fields of the parameter block for this function 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”.

    ioDTRefNum

    On input, the desktop database reference number of the desktop database to flush.

    You must call PBDTFlushAsync or PBDTFlushSync to update the copy of the desktop database stored on the volume if your application has manipulated information in the database using any of the following functions:

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Identifies the application that can open a file with a given creator.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTGetAPPLSync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function are:

    ioNamePtr

    On output, a pointer to the application’s name.

    ioDTRefNum

    On input, the desktop database reference number of the desktop database containing the specified application.

    ioIndex

    On input, an index into the application list.

    ioTagInfo

    On output, the application’s creation date.

    ioFileCreator

    On input, the signature of the application.

    ioAPPLParID

    On output, the application’s parent directory.

    A single call, with the ioIndex field set to 0, finds the application file with the most recent creation date. If you want to retrieve information about all copies of the application with the given signature, start with ioIndex set to 1 and increment this value by 1 with each call to PBDTGetAPPLSync until the result code afpItemNotFound is returned in the ioResult field; when called multiple times in this fashion, PBDTGetAPPLSync returns information about all the application’s copies, including the file with the most recent creation date, in arbitrary order.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Identifies the application that can open a file with a given creator.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTGetAPPLAsync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function are:

    ioCompletion

    On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.

    ioResult

    On output, the result code. See “File Manager Result Codes”.

    ioNamePtr

    On output, a pointer to the application’s name.

    ioDTRefNum

    On input, the desktop database reference number of the desktop database containing the specified application.

    ioIndex

    On input, an index into the application list.

    ioTagInfo

    On output, the application’s creation date.

    ioFileCreator

    On input, the signature of the application.

    ioAPPLParID

    On output, the application’s parent directory.

    A single call, with the ioIndex field set to 0, finds the application file with the most recent creation date. If you want to retrieve information about all copies of the application with the given signature, start with ioIndex set to 1 and increment this value by 1 with each call to PBDTGetAPPLAsync until the result code afpItemNotFound is returned in the ioResult field; when called multiple times in this fashion, PBDTGetAPPLAsync returns information about all the application’s copies, including the file with the most recent creation date, in arbitrary order.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Retrieves the user comments for a file or directory.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTGetCommentSync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function are:

    ioNamePtr

    On input, a pointer to the name of the file or directory for which you want to retrieve comments.

    ioDTRefNum

    On input, the desktop database reference number of the database in which the specified file or directory is found.

    ioDTBuffer

    On input, a pointer to a buffer allocated to hold the comment text. On output, a pointer to the comment text. Allocate a buffer at least 255 bytes in size. The PBDTGetCommentSync function places up to ioDTReqCount bytes of the comment into the buffer as a plain text string and places the actual length of the comment in the ioDTActCount field.

    ioDTReqCount

    On input, the size of the buffer allocated to hold the comment.

    ioDTActCount

    On output, the comment size.

    ioDirID

    On input, the parent directory of the file or directory.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Retrieves the user comments for a file or directory.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTGetCommentAsync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function 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”.

    ioNamePtr

    On input, a pointer to the name of the file or directory for which you want to retrieve comments.

    ioDTRefNum

    On input, the desktop database reference number of the database in which the specified file or directory is found.

    ioDTBuffer

    On input, a pointer to a buffer allocated to hold the comment text. On output, a pointer to the comment text. Allocate a buffer at least 255 bytes in size. The PBDTGetCommentAsync function places up to ioDTReqCount bytes of the comment into the buffer as a plain text string and places the actual length of the comment in the ioDTActCount field.

    ioDTReqCount

    On input, the size of the buffer allocated to hold the comment.

    ioDTActCount

    On output, the comment size.

    ioDirID

    On input, the parent directory of the file or directory.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Retrieves an icon definition.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTGetIconSync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The PBDTGetIconSync function returns the bitmap for an icon that represents a file of a given type and creator. For example, to get the icon for a file of file type 'SFWR' created by the application with a signature of 'WAVE', specify these two values in the ioFileType and ioFileCreator fields.

    The relevant fields of the parameter block for this function are:

    ioDTRefNum

    On input, the desktop database reference number.

    ioTagInfo

    Reserved; on input, this field must be set to 0.

    ioDTBuffer

    On input, a pointer to a buffer to hold the icon’s data. On return, a pointer to the bitmap returned in the buffer.

    ioDTReqCount

    On input, the requested size of the icon’s bitmap. Pass the size in bytes of the buffer that you’ve allocated for the icon’s bitmap, pointed to by the ioDTBuffer field; this value depends on the icon type. Be sure to allocate enough storage for the icon data; 1024 bytes is the largest amount required for any icon in System 7. You can use the constants described in Icon Size Constants to indicate the amount of memory you have provided for the icon’s data.

    ioDTActCount

    On output, the actual size of the icon’s bitmap. If this value is larger than the value specified in the ioDTReqCount field, only the amount of data allowed by ioDTReqCount is valid.

    ioIconType

    On input, the icon type. For a description of the constants which you can use in this field, see Icon Type Constants.

    ioFileCreator

    On input, the icon’s file creator.

    ioFileType

    On input, the icon’s file type.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Retrieves an icon definition.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTGetIconAsync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The PBDTGetIconAsync function returns the bitmap for an icon that represents a file of a given type and creator. For example, to get the icon for a file of file type 'SFWR' created by the application with a signature of 'WAVE', specify these two values in the ioFileType and ioFileCreator fields.

    The relevant fields of the parameter block for this function 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”.

    ioDTRefNum

    On input, the desktop database reference number.

    ioTagInfo

    Reserved; on input, this field must be set to 0.

    ioDTBuffer

    On input, a pointer to a buffer to hold the icon’s data. On return, a pointer to the bitmap returned in the buffer.

    ioDTReqCount

    On input, the requested size of the icon’s bitmap. Pass the size in bytes of the buffer that you’ve allocated for the icon’s bitmap pointed to by the ioDTBuffer field; this value depends on the icon type. Be sure to allocate enough storage for the icon data; 1024 bytes is the largest amount required for any icon in System 7. You can use the constants described in Icon Size Constants to indicate the amount of memory you have provided for the icon’s data.

    ioDTActCount

    On return, the actual size of the icon’s bitmap. If this value is larger than the value specified in the ioDTReqCount field, only the amount of data allowed by the value in the ioDTReqCount field is valid.

    ioIconType

    On input, the icon type. For a description of the constants which you can use in this field, see Icon Type Constants.

    ioFileCreator

    On input, the icon’s file creator.

    ioFileType

    On input, the icon’s file type.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Retrieves an icon type and the associated file type supported by a given creator in the desktop database.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTGetIconInfoSync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function are:

    ioDTRefNum

    On input, the desktop database reference number.

    ioIndex

    On input, an index into the icon list.

    ioTagInfo

    Reserved; on input, this field must be set to 0.

    ioDTActCount

    On output, the size of the icon’s bitmap.

    ioIconType

    On output, the icon type, including the icon size and color depth. For a description of the values which may be returned in this field, see Icon Type Constants. Ignore any values returned in ioIconType that are not listed there; they represent special icons and information used only by the Finder.

    ioFileCreator

    On input, the icon’s file creator.

    ioFileType

    On output, the icon’s file type.

    To step through a list of the icon types and file types supported by an application, make repeated calls to PBDTGetIconInfoSync, specifying a creator and an index value in the ioIndex field for each call. Set the index to 1 on the first call, and increment it on each subsequent call until the result code afpItemNotFound is returned in the ioResult field.

    To get a list of file types that an application can natively open, you can use the Translation Manager function, GetFileTypesThatAppCanNativelyOpen. For a description of this function, see the Translation Manager Reference .

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Retrieves an icon type and the associated file type supported by a given creator in the desktop database.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTGetIconInfoAsync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function 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”.

    ioDTRefNum

    On input, the desktop database reference number.

    ioIndex

    On input, an index into the icon list.

    ioTagInfo

    Reserved; on input, this field must be set to 0.

    ioDTActCount

    On output, the size of the icon’s bitmap.

    ioIconType

    On output, the icon type, including the icon size and color depth. For a description of the values which may be returned in this field, see Icon Type Constants. Ignore any values returned in ioIconType that are not listed there; they represent special icons and information used only by the Finder.

    ioFileCreator

    On input, the icon’s file creator.

    ioFileType

    On output, the icon’s file type.

    To step through a list of the icon types and file types supported by an application, make repeated calls to PBDTGetIconInfoAsync, specifying a creator and an index value in the ioIndex field for each call. Set the index to 1 on the first call, and increment it on each subsequent call until the result code afpItemNotFound is returned in the ioResult field.

    To get a list of file types that an application can natively open, you can use the Translation Manager function, GetFileTypesThatAppCanNativelyOpen. For a description of this function, see the Translation Manager Reference .

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Determines information about the location and size of the desktop database on a particular volume.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTGetInfoSync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function are:

    ioVRefNum

    On output, the volume reference number of the volume where the database files are stored.

    ioDTRefNum

    On input, the desktop database reference number of the database which you wish to obtain information about.

    ioIndex

    On output, the number of files comprising the desktop database on the volume.

    ioDirID

    On output, the parent directory ID of the desktop database.

    ioDTLgLen

    On output, the logical length of the database files (the sum of the logical lengths of the files that constitute the desktop database for a given volume).

    ioDTPyLen

    On output, the physical length of the database files (the sum of the physical lengths of the files that constitute the desktop database for a given volume).

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Determines information about the location and size of the desktop database on a particular volume.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTGetInfoAsync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function are:

    ioCompletion

    On input, a pointer to a completion function. For more information on completion functions, see IOCompletionProcPtr.

    ioResult

    On output, the result code of the function. See “File Manager Result Codes”.

    ioVRefNum

    On output, the volume reference number of the volume where the database files are stored.

    ioDTRefNum

    On input, the desktop database reference number of the database which you wish to obtain information about.

    ioIndex

    On output, the number of files comprising the desktop database on the volume.

    ioDirID

    On output, the parent directory ID of the desktop database.

    ioDTLgLen

    On output, the logical length of the database files (the sum of the logical lengths of the files that constitute the desktop database for a given volume).

    ioDTPyLen

    On output, the physical length of the database files (the sum of the physical lengths of the files that constitute the desktop database for a given volume).

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • PBDTGetPath PBDTGetPath (OS X v10.4)

    Gets the reference number of the specified desktop database.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTGetPath ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function are:

    ioNamePtr

    On input, a pointer to the name of the volume associated with the desktop database or the full pathname of the desktop database.

    ioVRefNum

    On input, the volume reference number of the volume associated with the desktop database.

    ioDTRefNum

    On output, the desktop database reference number, which represents the access path to the database. You cannot use the desktop reference number as a file reference number in any File Manager functions other than the desktop database functions. If PBDTGetPath fails, it sets this field to 0.

    If the desktop database is not already open, PBDTGetPath opens it and then returns the reference number. If the desktop database doesn’t exist, PBDTGetPath creates it .

    Special Considerations

    PBDTGetPath allocates memory in the system heap; do not call it at interrupt time.

    This function executes synchronously only.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Gets the reference number of the specified desktop database, reporting whether the desktop database was empty when it was opened.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTOpenInform ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function are:

    ioNamePtr

    On input, a pointer to the name of the volume associated with the desktop database or the full pathname of the desktop database.

    ioVRefNum

    On input, the volume reference number of the volume associated with the desktop database.

    ioDTRefNum

    On output, the desktop database reference number, which represents the access path to the database. You cannot use the desktop reference number as a file reference number in any File Manager functions other than the desktop database functions. If PBDTOpenInform fails, it sets this field to 0.

    ioTagInfo

    On output, the return flag (in the low bit of this field). If the desktop database was just created in response to PBDTOpenInform (and is therefore empty), PBDTOpenInform sets the low bit in this field to 0. If the desktop database had been created before you called PBDTOpenInform, PBDTOpenInform sets the low bit in this field to 1.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    This function executes synchronously only.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Removes an application from the desktop database.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTRemoveAPPLSync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The PBDTRemoveAPPLSync function removes the mapping information for an application from the database specified in the ioDTRefNum field. You can call PBDTRemoveAPPLSync even if the application is not present on the volume.

    The relevant fields of the parameter block for this function are:

    ioNamePtr

    On input, a pointer to the application’s name.

    ioDTRefNum

    On input, the desktop database reference number of the desktop database containing the application.

    ioDirID

    On input, the application’s parent directory.

    ioFileCreator

    On input, the application’s signature.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Removes an application from the desktop database.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTRemoveAPPLAsync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes. When called on an HFS CD volume, PBDTRemoveAPPL returns an afpItemNotFound error, instead of the expected volume locked error (wPrErr).

    Discussion

    The PBDTRemoveAPPLAsync function removes the mapping information for an application from the database specified in the ioDTRefNum field. You can call PBDTRemoveAPPLAsync even if the application is not present on the volume.

    The relevant fields of the parameter block for this function 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”.

    ioNamePtr

    On input, a pointer to the application’s name.

    ioDTRefNum

    On input, the desktop database reference number of the desktop database containing the application.

    ioDirID

    On input, the application’s parent directory.

    ioFileCreator

    On input, the application’s signature.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Removes a user comment associated with a file or directory from the desktop database.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTRemoveCommentSync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function are:

    ioNamePtr

    On input, a pointer to the filename or directory name.

    ioDTRefNum

    On input, the desktop database reference number of the database in which the specified file or directory is found.

    ioDirID

    On input, the parent directory ID of the file or directory.

    You cannot remove a comment if the file or directory it is associated with is not present on the volume. If no comment was stored for the file, PBDTRemoveCommentSync returns an error.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Removes a user comment associated with a file or directory from the desktop database.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTRemoveCommentAsync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function 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”.

    ioNamePtr

    On input, a pointer to the filename or directory name.

    ioDTRefNum

    On input, the desktop database reference number of the database in which the specified file or directory is found.

    ioDirID

    On input, the parent directory ID of the file or directory.

    You cannot remove a comment if the file or directory it is associated with is not present on the volume. If no comment was stored for the file, PBDTRemoveCommentAsync returns an error.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Removes information from the desktop database. Unless you are manipulating the desktop database in the absence of the Finder, you should never use this function.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTResetSync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The PBDTResetSync function removes all icons, application mappings, and comments from the desktop database specified in the ioDTRefNum field. You can call PBDTResetSync only when the database is open. It remains open after the data is cleared. Your application should not call PBDTResetSync unless absolutely necessary.

    The relevant fields of the parameter block for this function are:

    ioDTRefNum

    On input, the desktop database reference number of the desktop database to clear.

    ioIndex

    Reserved; on input, this field must be set to 0.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Removes information from the desktop database. Unless you are manipulating the desktop database in the absence of the Finder, you should never use this function.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTResetAsync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The PBDTResetAsync function removes all icons, application mappings, and comments from the desktop database specified in the ioDTRefNum field. You can call PBDTResetAsync only when the database is open. It remains open after the data is cleared. Your application should not call PBDTResetAsync unless absolutely necessary.

    The relevant fields of the parameter block for this function 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”.

    ioDTRefNum

    On input, the desktop database reference number of the desktop database to clear.

    ioIndex

    Reserved; on input, this field must be set to 0.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Adds a user comment for a file or a directory to the desktop database.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTSetCommentSync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function are:

    ioNamePtr

    On input, a pointer to the name of the file or directory.

    ioDTRefNum

    On input, the desktop database reference number for the desktop database to which to add the user comment.

    ioDTBuffer

    On input, a pointer to the buffer containing the comment text. Put the comment in the buffer as a plain text string.

    ioDTReqCount

    On input, the length of the buffer containing the comment text, in bytes. The maximum length of a comment is 200 bytes; longer comments are truncated. Since the comment is a plain text string and not a Pascal string, the File Manager relies on the value in the ioDTReqCount field for determining the length of the buffer.

    ioDirID

    On input, the parent directory ID of the file or directory.

    If the specified object already has a comment in the database, the new comment replaces the old.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Adds a user comment for a file or a directory to the desktop database.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBDTSetCommentAsync ( DTPBPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a desktop database parameter block. See DTPBRec for a description of the DTPBRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block for this function 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”.

    ioNamePtr

    On input, a pointer to the name of the file or directory.

    ioDTRefNum

    On input, the desktop database reference number for the desktop database to which to add the user comment.

    ioDTBuffer

    On input, a pointer to the buffer containing the comment text. Put the comment in the buffer as a plain text string.

    ioDTReqCount

    On input, the length of the buffer (in bytes) containing the comment text. The maximum length of a comment is 200 bytes; longer comments are truncated. Since the comment is a plain text string and not a Pascal string, the File Manager relies on the value in the ioDTReqCount field for determining the length of the buffer.

    ioDirID

    On input, the parent directory ID of the file or directory.

    If the specified object already has a comment in the database, the new comment replaces the old.

    Special Considerations

    All of the desktop database functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Allocates space on a volume to an open fork.

    Deprecation Statement

    At the POSIX/BSD layer, use fcntl with F_PREALLOCATE instead.

    Declaration

    Objective-C

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

    Parameters

    forkRefNum

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

    flags

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

    positionMode

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

    positionOffset

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

    requestCount

    The number of bytes to allocate.

    actualCount

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

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

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

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

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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Allocates space on a volume to an open fork.

    Deprecation Statement

    At the POSIX/BSD layer, use fcntl(2) OS X Developer Tools Manual Page with F_PREALLOCATE instead.

    Declaration

    Objective-C

    OSErr PBAllocateForkSync ( FSForkIOParam *paramBlock );

    Parameters

    paramBlock

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

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    forkRefNum

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

    allocationFlags

    On input, a constant indicating how the new space should be allocated. See Allocation Flags for a description of the constants you can use in this field.

    positionMode

    On input, a constant specifying the base location within the fork for the start of the allocation. See Position Mode Constants for more information on the constants which you can use to specify the base location.

    positionOffset

    On input, the offset from the base location of the start of the allocation.

    allocationAmount

    On input, the number of bytes to allocate. On output, the number of bytes actually allocated to the file. The number of bytes allocated may be smaller than the requested amount if some of the space was already allocated. The value returned in this field does not reflect any additional bytes that may have been allocated because space is allocated in terms of fixed units such as allocation blocks, or the use of a clump size to reduce fragmentation.

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

    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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Allocates space on a volume to an open fork.

    Deprecation Statement

    At the POSIX/BSD layer, use fcntl(2) OS X Developer Tools Manual Page with F_PREALLOCATE instead.

    Declaration

    Objective-C

    void PBAllocateForkAsync ( FSForkIOParam *paramBlock );

    Parameters

    paramBlock

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

    Discussion

    The relevant fields of the parameter block are:

    ioCompletion

    On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.

    ioResult

    On output, the result code of the function.

    forkRefNum

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

    allocationFlags

    On input, a constant indicating how the new space should be allocated. See Allocation Flags for a description of the constants which you can use in this field.

    positionMode

    On input, a constant specifying the base location within the fork for the start of the allocation. See Position Mode Constants for more information on the constants which you can use to specify the base location.

    positionOffset

    On input, the offset from the base location of the start of the allocation.

    allocationAmount

    On input, the number of bytes to allocate. On output, the number of bytes actually allocated to the file. The number of bytes allocated may be smaller than the requested amount if some of the space was already allocated. The value returned in this field does not reflect any additional bytes that may have been allocated because space is allocated in terms of fixed units such as allocation blocks, or the use of a clump size to reduce fragmentation.

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

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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Allocate Allocate (OS X v10.4)

    Allocates additional space on a volume to an open file.

    Deprecation Statement

    Use FSAllocateFork instead.

    Declaration

    Objective-C

    OSErr Allocate ( FSIORefNum refNum, SInt32 *count );

    Parameters

    refNum

    The file reference number of the open file.

    count

    On input, a pointer to the number of additional bytes to allocate to the file. On return, a pointer to the number of bytes actually allocated, rounded up to the nearest multiple of the allocation block size.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The Allocate function adds the specified number of bytes to the file and sets the physical end-of-file to 1 byte beyond the last block allocated. If there isn’t enough empty space on the volume to satisfy the allocation request, Allocate allocates the rest of the space on the volume and returns dskFulErr as its function result.

    The Allocate function always attempts to allocate contiguous blocks. If the total number of requested bytes is unavailable, Allocate allocates whatever space, contiguous or not, is available. To force the allocation of the entire requested space as a contiguous piece, call AllocContig instead.

    The File Manager automatically allocates file blocks if you move the logical end-of-file past the physical end-of-file, and it automatically deallocates unneeded blocks from a file if you move the logical end-of-file to a position more than one allocation block before the current physical end-of-file. Consequently, you do not in general need to be concerned with allocating or deallocating file blocks. However, you can improve file block contiguity if you use the Allocate or AllocContig function to preallocate file blocks. This is most useful if you know in advance how big a file is likely to become.

    When the File Manager allocates (or deallocates) file blocks automatically, it always adds (or removes) blocks in clumps. The Allocate function allows you to add blocks in allocation blocks, which may be smaller than clumps.

    The space allocated with this function is not permanently assigned to the file until the file’s logical end-of-file is changed to include the allocated space. When a file (or volume) is closed, the space beyond the file’s logical EOF is made available for other purposes, even if previously allocated to the file with a call to this function. You can change the end-of-file by setting it with the SetEOF function, or by writing data to the file with the FSWrite function.

    This function is not supported by all file systems; for example, volumes mounted by the AppleShare file system do not support this function. To allocate space for a file on any volume, use the SetEOF function, or one of the related parameter block calls, PBSetEOFSync and PBSetEOFAsync.

    To allocate space for a file beyond 2 GB, use the FSAllocateFork function, or one of the corresponding parameter block functions, PBAllocateForkSync and PBAllocateForkAsync.

    Special Considerations

    In Mac OS 7.5.5 through Mac OS 8.5, if there is not enough space left on the volume to allocate the requested number of bytes, the Allocate function does not return the number of bytes actually allocated. Your application should not rely on the value returned in the count parameter.

    To determine the remaining space on a volume before calling Allocate, use the functions PBXGetVolInfoSync or PBXGetVolInfoAsync.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Allocates additional space on a volume to an open file.

    Deprecation Statement

    Use PBAllocateForkSync instead.

    Declaration

    Objective-C

    OSErr PBAllocateSync ( ParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to the IOParam variant of the basic File Manager parameter block. See ParamBlockRec for a description of the ParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    ioRefNum

    On input, a file reference number for the file to which to allocate additional blocks.

    ioReqCount

    On input, the number of bytes to allocate.

    ioActCount

    On output, the number of bytes actually allocated, rounded up to the nearest multiple of the allocation block size.

    The PBAllocateSync function adds ioReqCount bytes to the specified file and sets the physical end-of-file to 1 byte beyond the last block allocated. If there isn’t enough empty space on the volume to satisfy the allocation request, PBAllocateSync allocates the rest of the space on the volume and returns dskFulErr as its function result.

    If the total number of requested bytes is unavailable, PBAllocateSync allocates whatever space, contiguous or not, is available. To force the allocation of the entire requested space as a contiguous piece, call PBAllocContigSync instead.

    The File Manager automatically allocates file blocks if you move the logical end-of-file past the physical end-of-file, and it automatically deallocates unneeded blocks from a file if you move the logical end-of-file to a position more than one allocation block before the current physical end-of-file. Consequently, you do not in general need to be concerned with allocating or deallocating file blocks. However, you can improve file block contiguity if you use the PBAllocateSync function to preallocate file blocks. This is most useful if you know in advance how big a file is likely to become.

    The space allocated with this function is not permanently assigned to the file until the file’s logical end-of-file is changed to include the allocated space. When a file (or volume) is closed, the space beyond the file’s logical EOF is made available for other purposes, even if previously allocated to the file with a call to this function. You can change the end-of-file by setting it with the SetEOF function, or by writing data to the file with the FSWrite function.

    This function is not supported by all file systems; for example, volumes mounted by the AppleShare file system do not support this function. To allocate space for a file on any volume, use the SetEOF function, or one of the related parameter block calls, PBSetEOFSync and PBSetEOFAsync.

    To allocate space for a file beyond 2 GB, use the FSAllocateFork function, or one of the corresponding parameter block functions, PBAllocateForkSync and PBAllocateForkAsync.

    Special Considerations

    In Mac OS 7.5.5 through Mac OS 8.5, if there is not enough space left on the volume to allocate the requested number of bytes, the PBAllocateSync function does not return the number of bytes actually allocated in the ioActCount field.

    To determine the remaining space on a volume before calling PBAllocateSync, use the functions PBXGetVolInfoSync or PBXGetVolInfoAsync.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Allocates additional space on a volume to an open file.

    Deprecation Statement

    Use PBAllocateForkAsync instead.

    Declaration

    Objective-C

    OSErr PBAllocateAsync ( ParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to the IOParam variant of the basic File Manager parameter block. See ParamBlockRec for a description of the ParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    ioCompletion

    On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.

    ioResult

    On output, the result code of the function.

    ioRefNum

    On input, a file reference number for the file to which to allocate additional blocks.

    ioReqCount

    On input, the number of bytes to allocate.

    ioActCount

    On output, the number of bytes actually allocated, rounded up to the nearest multiple of the allocation block size.

    The PBAllocateAsync function adds ioReqCount bytes to the specified file and sets the physical end-of-file to 1 byte beyond the last block allocated. If there isn’t enough empty space on the volume to satisfy the allocation request, PBAllocateAsync allocates the rest of the space on the volume and returns dskFulErr as its function result.

    If the total number of requested bytes is unavailable, PBAllocateAsync allocates whatever space, contiguous or not, is available. To force the allocation of the entire requested space as a contiguous piece, call PBAllocContigAsync instead.

    The File Manager automatically allocates file blocks if you move the logical end-of-file past the physical end-of-file, and it automatically deallocates unneeded blocks from a file if you move the logical end-of-file to a position more than one allocation block before the current physical end-of-file. Consequently, you do not in general need to be concerned with allocating or deallocating file blocks. However, you can improve file block contiguity if you use the PBAllocateAsync function to preallocate file blocks. This is most useful if you know in advance how big a file is likely to become.

    The space allocated with this function is not permanently assigned to the file until the file’s logical end-of-file is changed to include the allocated space. When a file (or volume) is closed, the space beyond the file’s logical EOF is made available for other purposes, even if previously allocated to the file with a call to this function. You can change the end-of-file by setting it with the SetEOF function, or by writing data to the file with the FSWrite function.

    This function is not supported by all file systems; for example, volumes mounted by the AppleShare file system do not support this function. To allocate space for a file on any volume, use the SetEOF function, or one of the related parameter block calls, PBSetEOFSync and PBSetEOFAsync.

    To allocate space for a file beyond 2 GB, use the FSAllocateFork function, or one of the corresponding parameter block functions, PBAllocateForkSync and PBAllocateForkAsync.

    Special Considerations

    In Mac OS 7.5.5 through Mac OS 8.5, if there is not enough space left on the volume to allocate the requested number of bytes, the PBAllocateAsync function does not return the number of bytes actually allocated in the ioActCount field.

    To determine the remaining space on a volume before calling PBAllocateAsync, use the functions PBXGetVolInfoSync or PBXGetVolInfoAsync.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • AllocContig AllocContig (OS X v10.4)

    Allocates additional contiguous space on a volume to an open file.

    Deprecation Statement

    Use FSAllocateFork instead.

    Declaration

    Objective-C

    OSErr AllocContig ( FSVolumeRefNum refNum, SInt32 *count );

    Parameters

    refNum

    The file reference number of an open file.

    count

    On input, a pointer to the number of additional bytes to allocate to the file; on return, a pointer to the number of bytes allocated, rounded up to the nearest multiple of the allocation block size.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The AllocContig function is identical to the Allocate function except that if there isn’t enough contiguous empty space on the volume to satisfy the allocation request, AllocContig does nothing and returns dskFulErr as its function result. If you want to allocate whatever space is available, even when the entire request cannot be filled by the allocation of a contiguous piece, call Allocate instead.

    The File Manager automatically allocates file blocks if you move the logical end-of-file past the physical end-of-file, and it automatically deallocates unneeded blocks from a file if you move the logical end-of-file to a position more than one allocation block before the current physical end-of-file. Consequently, you do not in general need to be concerned with allocating or deallocating file blocks. However, you can improve file block contiguity if you use the AllocContig function to preallocate file blocks. This is most useful if you know in advance how big a file is likely to become.

    When the File Manager allocates (or deallocates) file blocks automatically, it always adds (or removes) blocks in clumps. The AllocContig function allows you to add blocks in allocation blocks, which may be smaller than clumps.

    The space allocated with this function is not permanently assigned to the file until the file’s logical end-of-file is changed to include the allocated space. When a file (or volume) is closed, the space beyond the file’s logical EOF is made available for other purposes, even if previously allocated to the file with a call to this function. You can change the end-of-file by setting it with the SetEOF function, or by writing data to the file with the FSWrite function.

    This function is not supported by all file systems; for example, volumes mounted by the AppleShare file system do not support this function. To allocate space for a file on any volume, use the SetEOF function, or one of the related parameter block calls, PBSetEOFSync and PBSetEOFAsync.

    To allocate space for a file beyond 2 GB, use the FSAllocateFork function, or one of the corresponding parameter block functions, PBAllocateForkSync and PBAllocateForkAsync.

    Special Considerations

    In Mac OS 7.5.5 through Mac OS 8.5, when there is not enough space to allocate the requested number of bytes, AllocContig does not return 0 in the count parameter, so your application cannot rely upon this value.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Allocates additional contiguous space on a volume to an open file.

    Deprecation Statement

    Use PBAllocateForkSync instead.

    Declaration

    Objective-C

    OSErr PBAllocContigSync ( ParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to the IOParam variant of the basic File Manager parameter block. See ParamBlockRec for a description of the ParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    ioRefNum

    On input, a file reference number for the open file.

    ioReqCount

    On input, the number of bytes to allocate.

    ioActCount

    On output, the number of bytes actually allocated, rounded up to the nearest multiple of the allocation block size.

    The PBAllocContigSync function is identical to the PBAllocateSync function except that if there isn’t enough contiguous empty space on the volume to satisfy the allocation request, PBAllocContigSync does nothing and returns dskFulErr as its function result. If you want to allocate whatever space is available, even when the entire request cannot be filled by the allocation of a contiguous piece, call PBAllocateSync instead.

    The File Manager automatically allocates file blocks if you move the logical end-of-file past the physical end-of-file, and it automatically deallocates unneeded blocks from a file if you move the logical end-of-file to a position more than one allocation block before the current physical end-of-file. Consequently, you do not in general need to be concerned with allocating or deallocating file blocks. However, you can improve file block contiguity if you use the PBAllocContigSync function to preallocate file blocks. This is most useful if you know in advance how big a file is likely to become.

    The space allocated with this function is not permanently assigned to the file until the file’s logical end-of-file is changed to include the allocated space. When a file (or volume) is closed, the space beyond the file’s logical EOF is made available for other purposes, even if previously allocated to the file with a call to this function. You can change the end-of-file by setting it with the SetEOF function, or by writing data to the file with the FSWrite function.

    This function is not supported by all file systems; for example, volumes mounted by the AppleShare file system do not support this function. To allocate space for a file on any volume, use the SetEOF function, or one of the related parameter block calls, PBSetEOFSync and PBSetEOFAsync.

    To allocate space for a file beyond 2 GB, use the FSAllocateFork function, or one of the corresponding parameter block functions, PBAllocateForkSync and PBAllocateForkAsync.

    Special Considerations

    In Mac OS 7.5.5 through Mac OS 8.5, when there is not enough space to allocate the requested number of bytes, PBAllocContigSync does not return 0 in the ioActCount field, so your application cannot rely upon this value.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Allocates additional contiguous space on a volume to an open file.

    Deprecation Statement

    Use PBAllocateForkAsync instead.

    Declaration

    Objective-C

    OSErr PBAllocContigAsync ( ParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to the IOParam variant of the basic File Manager parameter block. See ParamBlockRec for a description of the ParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    ioCompletion

    On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.

    ioResult

    On output, the result code of the function.

    ioRefNum

    On input, a file reference number for the open file.

    ioReqCount

    On input, the number of bytes to allocate.

    ioActCount

    On output, the number of bytes actually allocated, rounded up to the nearest multiple of the allocation block size.

    The PBAllocContigAsync function is identical to the PBAllocateAsync function except that if there isn’t enough contiguous empty space on the volume to satisfy the allocation request, PBAllocContigAsync does nothing and returns dskFulErr as its function result. If you want to allocate whatever space is available, even when the entire request cannot be filled by the allocation of a contiguous piece, call PBAllocateAsync instead.

    The File Manager automatically allocates file blocks if you move the logical end-of-file past the physical end-of-file, and it automatically deallocates unneeded blocks from a file if you move the logical end-of-file to a position more than one allocation block before the current physical end-of-file. Consequently, you do not in general need to be concerned with allocating or deallocating file blocks. However, you can improve file block contiguity if you use the PBAllocContigAsync function to preallocate file blocks. This is most useful if you know in advance how big a file is likely to become.

    The space allocated with this function is not permanently assigned to the file until the file’s logical end-of-file is changed to include the allocated space. When a file (or volume) is closed, the space beyond the file’s logical EOF is made available for other purposes, even if previously allocated to the file with a call to this function. You can change the end-of-file by setting it with the SetEOF function, or by writing data to the file with the FSWrite function.

    This function is not supported by all file systems; for example, volumes mounted by the AppleShare file system do not support this function. To allocate space for a file on any volume, use the SetEOF function, or one of the related parameter block calls, PBSetEOFSync and PBSetEOFAsync.

    To allocate space for a file beyond 2 GB, use the FSAllocateFork function, or one of the corresponding parameter block functions, PBAllocateForkSync and PBAllocateForkAsync.

    Special Considerations

    In Mac OS 7.5.5 through Mac OS 8.5, when there is not enough space to allocate the requested number of bytes, PBAllocContigAsync does not return 0 in the ioActCount field, so your application cannot rely upon this value.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Sets the group ID associated with the given FSFileSecurityRef object.

    Deprecation Statement

    Use CFFileSecuritySetGroup instead.

    Declaration

    Objective-C

    OSStatus FSFileSecuritySetGroup ( FSFileSecurityRef fileSec, UInt32 group );

    Parameters

    fileSec

    The FSFileSecurityRef object.

    group

    The group UUID to set.

    Return Value

    Returns success if the group UUID was set.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.8.

  • Sets the mode associated with the given FSFileSecurityRef object.

    Deprecation Statement

    Use CFFileSecuritySetMode instead.

    Declaration

    Objective-C

    OSStatus FSFileSecuritySetMode ( FSFileSecurityRef fileSec, UInt16 mode );

    Parameters

    fileSec

    The FSFileSecurityRef object.

    mode

    The file mode associated with the FSFileSecurityRef object.

    Return Value

    Returns success if the mode was set.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.8.

  • Sets the owner ID associated with the given FSFileSecurityRef object.

    Deprecation Statement

    Use CFFileSecuritySetOwner instead.

    Declaration

    Objective-C

    OSStatus FSFileSecuritySetOwner ( FSFileSecurityRef fileSec, UInt32 owner );

    Parameters

    fileSec

    The FSFileSecurityRef object.

    owner

    The owner UUID to set.

    Return Value

    Returns success if the owner UUID was set.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.8.

  • Sets the owner UUID associated with the given FSFileSecurityRef object.

    Deprecation Statement

    Use CFFileSecuritySetOwnerUUID instead.

    Declaration

    Objective-C

    OSStatus FSFileSecuritySetOwnerUUID ( FSFileSecurityRef fileSec, const CFUUIDBytes *owner );

    Parameters

    fileSec

    The FSFileSecurityRef object.

    owner

    The owner UUID to set.

    Return Value

    Returns success if the owner UUID was set.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.8.

  • Sets the group UUID associated with the given FSFileSecurityRef object.

    Deprecation Statement

    Use CFFileSecuritySetGroupUUID instead.

    Declaration

    Objective-C

    OSStatus FSFileSecuritySetGroupUUID ( FSFileSecurityRef fileSec, const CFUUIDBytes *group );

    Parameters

    fileSec

    The FSFileSecurityRef object.

    group

    The group UUID to set.

    Return Value

    Returns success if the group UUID was set.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.8.

  • Sets the access control list (ACL) associated with the given FSFileSecurityRef object.

    Deprecation Statement

    Use CFFileSecuritySetAccessControlList instead.

    Declaration

    Objective-C

    OSStatus FSFileSecuritySetAccessControlList ( FSFileSecurityRef fileSec, acl_t accessControlList );

    Parameters

    fileSec

    The FSFileSecurityRef object.

    accessControlList

    The access control list to set or kFSFileSecurityRemoveACL to request removal of an ACL from the given FSFileSecurityRef object, or NULL to unset the property.

    Return Value

    Returns success if the ACL was set.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.8.

  • FSCloseFork FSCloseFork (OS X v10.8)

    Closes an open fork.

    Deprecation Statement

    At the POSIX/BSD layer, use close(2) OS X Developer Tools Manual Page instead. To close the data fork at the Foundation layer, use NSFileHandle APIs instead.

    Declaration

    Objective-C

    OSErr FSCloseFork ( FSIORefNum forkRefNum );

    Parameters

    forkRefNum

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

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Closes an open fork.

    Deprecation Statement

    At the POSIX/BSD layer, use close(2) OS X Developer Tools Manual Page instead. To close the data fork at the Foundation layer, use NSFileHandle APIs instead.

    Declaration

    Objective-C

    OSErr PBCloseForkSync ( FSForkIOParam *paramBlock );

    Parameters

    paramBlock

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

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant field of the parameter block is:

    forkRefNum

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

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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Closes an open fork.

    Deprecation Statement

    At the POSIX/BSD layer, use close(2) OS X Developer Tools Manual Page instead. To close the data fork at the Foundation layer, use NSFileHandle APIs instead.

    Declaration

    Objective-C

    void PBCloseForkAsync ( FSForkIOParam *paramBlock );

    Parameters

    paramBlock

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

    Discussion

    The relevant fields of the parameter block are:

    ioCompletion

    On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.

    ioResult

    On output, the result code of the function.

    forkRefNum

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

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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • FSClose FSClose (OS X v10.4)

    Closes an open file.

    Deprecation Statement

    Use FSCloseFork instead.

    Declaration

    Objective-C

    OSErr FSClose ( FSIORefNum refNum );

    Parameters

    refNum

    The file reference number of the open file.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The FSClose function removes the access path for the specified file and writes the contents of the volume buffer to the volume.

    The FSClose function calls the PBFlushFileSync function internally to write the file’s bytes onto the volume. To ensure that the file’s catalog entry is updated, you should call FlushVol after you call FSClose.

    Special Considerations

    Make sure that you do not call FSClose with a file reference number of a file that has already been closed. Attempting to close the same file twice may result in loss of data on a volume.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • PBCloseAsync PBCloseAsync (OS X v10.5)

    Closes an open file.

    Deprecation Statement

    Use PBCloseForkAsync instead.

    Declaration

    Objective-C

    OSErr PBCloseAsync ( ParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a basic File Manager parameter block.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    ioCompletion

    On input, a pointer to a completion routine.

    ioResult

    On output, the result code of the function.

    ioRefNum

    On input, a file reference number to the file to close.

    The PBCloseAsync function writes the contents of the access path buffer specified by the ioRefNum field to the volume and removes the access path.

    Special Considerations

    Some information stored on the volume won’t be updated until PBFlushVolAsync is called.

    Do not call PBCloseAsync with a file reference number of a file that has already been closed. Attempting to close the same file twice may result in loss of data on a volume.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • PBCloseSync PBCloseSync (OS X v10.5)

    Closes an open file.

    Deprecation Statement

    Use PBCloseForkSync instead.

    Declaration

    Objective-C

    OSErr PBCloseSync ( ParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a basic File Manager parameter block.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant field of the parameter block is:

    ioRefNum

    On input, a file reference number to the file to close.

    The PBCloseSync function writes the contents of the access path buffer specified by the ioRefNum field to the volume and removes the access path.

    Special Considerations

    Some information stored on the volume won’t be updated until PBFlushVolSync is called.

    Do not call PBCloseSync with a file reference number of a file that has already been closed. Attempting to close the same file twice may result in loss of data on a volume.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

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

    Deprecation Statement

    Use NSURL or CFURL APIs instead. To compare two file URLs to see if they have the same file system path or if the paths are linked to same inode on the same file system, use the NSURLFileResourceIdentifierKey or kCFURLFileResourceIdentifierKey properties.

    Declaration

    Objective-C

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

    Parameters

    ref1

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

    ref2

    A pointer to the second FSRef to compare.

    Return Value

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

    Discussion

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

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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

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

    Deprecation Statement

    Use NSURL or CFURL APIs instead. To compare two file URLs to see if they have the same file system path or if the paths are linked to same inode on the same file system, use the NSURLFileResourceIdentifierKey or kCFURLFileResourceIdentifierKey properties.

    Declaration

    Objective-C

    OSErr PBCompareFSRefsSync ( FSRefParam *paramBlock );

    Parameters

    paramBlock

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

    Return Value

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

    Discussion

    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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

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

    Deprecation Statement

    Use NSURL or CFURL APIs instead. To compare two file URLs to see if they have the same file system path or if the paths are linked to same inode on the same file system, use the NSURLFileResourceIdentifierKey or kCFURLFileResourceIdentifierKey properties.

    Declaration

    Objective-C

    void PBCompareFSRefsAsync ( FSRefParam *paramBlock );

    Parameters

    paramBlock

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

    Discussion

    The relevant fields of the parameter block are:

    ioCompletion

    On input, a pointer to a completion routine. For more information about completion routines, see IOCompletionProcPtr.

    ioResult

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

    ref

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

    parentRef

    On input, a pointer to the second FSRef to compare.

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

    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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Returns the access control information for a directory or file.

    Deprecation Statement

    Use FSGetCatalogInfo instead.

    Declaration

    Objective-C

    OSErr PBHGetDirAccessSync ( HParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to the AccessParam variant of an HFS parameter block. See HParamBlockRec for a description of the HParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    ioNamePtr

    On input, a pointer to a pathname for the directory or file.

    ioVRefNum

    On input, a volume specification for the volume containing the directory or file. This field can contain a volume reference number, drive number, or 0 for the default volume.

    ioACOwnerID

    On output, the user ID for the owner of the directory or file.

    ioACGroupID

    On output, the primary group ID of the directory or file.

    ioACAccess

    On output, the access rights for the directory or file. See File and Folder Access Privilege Constants for more information on these access rights.

    ioDirID

    On input, the directory ID.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • Returns the access control information for a directory or file.

    Deprecation Statement

    Use FSGetCatalogInfo instead.

    Declaration

    Objective-C

    OSErr PBHGetDirAccessAsync ( HParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to the AccessParam variant of an HFS parameter block. See HParamBlockRec for a description of the HParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    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.

    ioNamePtr

    On input, a pointer to a pathname for the directory or file.

    ioVRefNum

    On input, a volume specification for the volume containing the directory or file. This field can contain a volume reference number, drive number, or 0 for the default volume.

    ioACOwnerID

    On output, the user ID for the owner of the directory or file.

    ioACGroupID

    On output, the primary group ID of the directory or file.

    ioACAccess

    On output, the access rights for the directory or file. See File and Folder Access Privilege Constants for more information on these access rights.

    ioDirID

    On input, the directory ID.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • Changes the access control information for a directory.

    Deprecation Statement

    Use FSSetCatalogInfo instead.

    Declaration

    Objective-C

    OSErr PBHSetDirAccessSync ( HParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to an AccessParam variant of an HFS parameter block. See HParamBlockRec for a description of the HParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    ioNamePtr

    On input, a pointer to a pathname.

    ioVRefNum

    On input, a volume specification for the volume containing the directory. This field can contain a volume reference number, drive number, or 0 for the default volume.

    ioACOwnerID

    On input, the owner ID.

    ioACGroupID

    On input, the group ID.

    ioACAccess

    On input, the directory’s access rights. You cannot set the owner or user rights bits of the ioACAccess field directly; if you try to do this, PBHSetDirAccessSync returns the result code paramErr. Only the blank access privileges can be set for a directory using this function. See File and Folder Access Privilege Constants for more information on directory access privileges.

    ioDirID

    On input, the directory ID.

    To change the owner or group, you should set the ioACOwnerID or ioACGroupID field to the appropriate ID. You must be the owner of the directory to change the owner or group ID. A guest on a server can manipulate the privileges of any directory owned by the guest.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • Changes the access control information for a directory.

    Deprecation Statement

    Use FSSetCatalogInfo instead.

    Declaration

    Objective-C

    OSErr PBHSetDirAccessAsync ( HParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to an AccessParam variant of an HFS parameter block. See HParamBlockRec for a description of the HParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    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.

    ioNamePtr

    On input, a pointer to a pathname.

    ioVRefNum

    On input, a volume specification for the volume containing the directory. This field can contain a volume reference number, drive number, or 0 for the default volume.

    ioACOwnerID

    On input, the owner ID.

    ioACGroupID

    On input, the group ID.

    ioACAccess

    On input, the directory’s access rights. You cannot set the owner or user rights bits of the ioACAccess field directly; if you try to do this, PBHSetDirAccessAsync returns the result code paramErr. Only the blank access privileges can be set for a directory using this function. See File and Folder Access Privilege Constants for more information on directory access privileges.

    ioDirID

    On input, the directory ID.

    To change the owner or group, you should set the ioACOwnerID or ioACGroupID field to the appropriate ID. You must be the owner of the directory to change the owner or group ID. A guest on a server can manipulate the privileges of any directory owned by the guest.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • Determines the login method used to log on to a particular shared volume.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBHGetLogInInfoAsync ( HParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to the ObjParam variant of the HFS parameter block. See HParamBlockRec for a description of the HParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    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.

    ioNamePtr

    On input, a pointer to a pathname

    ioVRefNum

    On input, a volume specification for the shared volume. This field can contain a volume reference number, drive number, or 0 for the default volume.

    ioObjType

    On output, the login method type. See Authentication Method Constants for the values that are recognized. Values in the range 7–127 are reserved for future use by Apple Computer, Inc. Values in the range 128–255 are available to your application as user-defined values.

    ioObjNamePtr

    On output, a pointer to the user name used to establish the session. The login user name is returned as a Pascal string. The maximum size of the user name is 31 characters.

    Special Considerations

    This function is not implemented in OS X.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • PBHMapIDSync PBHMapIDSync (OS X v10.5)

    Determines the name of a user or group given the user or group ID.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBHMapIDSync ( HParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to the ObjParam variant of the HFS parameter block. See HParamBlockRec for a description of the HParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    ioNamePtr

    On input, a pointer to a pathname.

    ioVRefNum

    On input, a volume specification.

    ioObjType

    On input, the mapping function code its value is 1 if you’re mapping a user ID to a user name or 2 if you’re mapping a group ID to a group name. See Mapping Code Constants for more information about the values you can use in this field.

    ioObjNamePtr

    On output, a pointer to the user or group name; the maximum size of the name is 31 characters (preceded by a length byte).

    ioObjID

    On input, the user or group ID to be mapped. AppleShare uses the value 0 to signify Any User.

    Special Considerations

    See the BSD functions getpwnam and getpwuid, which correspond to this function on a conceptual level.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • Determines the name of a user or group given the user or group ID.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBHMapIDAsync ( HParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to the ObjParam variant of the HFS parameter block. See HParamBlockRec for a description of the HParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    ioCompletion

    On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.

    ioResult

    On output, the result code of the function.

    ioNamePtr

    On input, a pointer to a pathname.

    ioVRefNum

    On input, a volume specification.

    ioObjType

    On input, the mapping function code its value is 1 if you’re mapping a user ID to a user name or 2 if you’re mapping a group ID to a group name. See Mapping Code Constants for more information about the values you can use in this field.

    ioObjNamePtr

    On output, a pointer to the user or group name; the maximum size of the name is 31 characters (preceded by a length byte).

    ioObjID

    On input, the user or group ID to be mapped. AppleShare uses the value 0 to signify Any User.

    Special Considerations

    See the BSD functions getpwnam and getpwuid, which correspond to this function on a conceptual level.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • Determines the user ID or group ID from a user or group name.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBHMapNameSync ( HParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to the ObjParam variant of the HFS parameter block. See HParamBlockRec for a description of the HParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    ioNamePtr

    On input, a pointer to a pathname.

    ioVRefNum

    On input, a volume specification.

    ioObjType

    On input, the mapping function code its value is 3 if you’re mapping a user name to a user ID or 4 if you’re mapping a group name to a group ID. See Mapping Code Constants for more information on the values you can use in this field.

    ioObjNamePtr

    On input, a pointer to the user or group name. The maximum size of the name is 31 characters. If NULL is passed, the ID returned is always 0.

    ioObjID

    On output, the mapped user or group ID.

    Special Considerations

    See the BSD functions getpwnam and getpwuid, which correspond to this function on a conceptual level.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • Determines the user ID or group ID from a user or group name.

    Deprecation Statement

    There is no replacement function.

    Declaration

    Objective-C

    OSErr PBHMapNameAsync ( HParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to the ObjParam variant of the HFS parameter block. See HParamBlockRec for a description of the HParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    ioCompletion

    On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.

    ioResult

    On output, the result code of the function.

    ioNamePtr

    On input, a pointer to a pathname.

    ioVRefNum

    On input, a volume specification.

    ioObjType

    On input, the mapping function code its value is 3 if you’re mapping a user name to a user ID or 4 if you’re mapping a group name to a group ID. See Mapping Code Constants for more information on the values you can use in this field.

    ioObjNamePtr

    On input, a pointer to the user or group name. The maximum size of the name is 31 characters. If NULL is passed, the ID returned is always 0.

    ioObjID

    On output, the mapped user or group ID.

    Special Considerations

    See the BSD functions getpwnam and getpwuid, which correspond to this function on a conceptual level.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • Converts an FSRef structure into a POSIX-style pathname.

    Declaration

    Objective-C

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

    Parameters

    ref

    A pointer to the FSRef structure to convert.

    path

    A pointer to a character buffer allocated by the caller. On output, the buffer contains a UTF-8 C string that specifies the absolute path to the object referred to by the ref parameter. The File Manager uses the maxPathSize parameter to make sure it does not overrun the buffer.

    maxPathSize

    The maximum number of bytes to copy into the buffer.

    Return Value

    A result code. See File Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Converts a POSIX-style pathname into an FSRef structure.

    Declaration

    Objective-C

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

    Parameters

    path

    A UTF-8 C string that contains the pathname to convert.

    ref

    A pointer to an FSRef structure allocated by the caller. On output, the FSRef structure refers to the object whose location is specified by the path parameter.

    isDirectory

    A pointer to a Boolean variable allocated by the caller. On output, true indicates the object is a directory. This parameter is optional and may be NULL.

    Return Value

    A result code. See File Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

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

    Parameters

    path

    A UTF-8 C string that contains the pathname to convert.

    options

    One or more conversion flags. See Path Conversion Options.

    ref

    A pointer to an FSRef structure allocated by the caller. On output, the FSRef structure refers to the object whose location is specified by the path parameter. If the object is a symbolic link, the options parameter determines whether the FSRef structure refers to the link itself or to the linked object.

    isDirectory

    A pointer to a Boolean variable allocated by the caller. On output, true indicates the object is a directory. This parameter is optional and may be NULL.

    Return Value

    A result code. See File Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.8.

  • Duplicates a file and optionally renames it.

    Declaration

    Objective-C

    OSStatus PBFSCopyFileSync ( FSRefParamPtr paramBlock );

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.8.

  • Duplicates a file and optionally renames it.

    Declaration

    Objective-C

    OSStatus PBFSCopyFileAsync ( FSRefParamPtr paramBlock );

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.8.

  • Duplicates a file and optionally renames it.

    Deprecation Statement

    Use PBFSCopyFileSync instead.

    Declaration

    Objective-C

    OSErr PBHCopyFileSync ( HParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a CopyParam variant of the HFS parameter block. See HParamBlockRec for a description of the HParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    ioNamePtr

    On input, a pointer to the name of the source file.

    ioVRefNum

    On input, the volume reference number or drive number for the volume containing the source file. Pass 0 for the default volume.

    ioDstVRefNum

    On input, the reference number or drive number of the destination volume. Pass 0 for the default volume.

    ioNewName

    On input, a pointer to the partial pathname for the destination directory. If ioNewName is NULL, the destination directory is the directory having the ID specified in the ioNewDirID field.

    ioCopyName

    On input, a pointer to the file’s new name. The string pointed to by this field must be a filename, not a partial pathname. If you do not wish to rename the file, pass NULL in this field.

    ioNewDirID

    On input, if the ioNewName field is NULL, the directory ID of the destination directory. If ioNewName is not NULL, the parent directory ID of the destination directory.

    ioDirID

    On input, the directory ID of the source directory.

    This function is especially useful when you want to copy or move files located on a remote volume, because it allows you to forgo transmitting large amounts of data across a network. This function is used internally by the Finder; most applications do not need to use it.

    Special Considerations

    This is an optional call for AppleShare file servers. Your application should examine the information returned by the PBHGetVolParmsSync function to see if the volume supports PBHCopyFileSync. If the bHasCopyFile bit is set in the vMAttrib field of the GetVolParmsInfoBuffer structure, then the volume supports PBHCopyFileSync.

    For AppleShare file servers, the source and destination pathnames must indicate the same file server; however, the parameter block may specify different source and destination volumes on that file server. A useful way to tell if two file server volumes are on the same file server is to call the PBHGetVolParmsSync function for each volume and compare the server addresses returned. The server opens source files with read/deny write enabled and destination files with write/deny read and write enabled.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • Duplicates a file and optionally renames it.

    Deprecation Statement

    Use PBFSCopyFileAsync instead.

    Declaration

    Objective-C

    OSErr PBHCopyFileAsync ( HParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a CopyParam variant of the HFS parameter block. See HParamBlockRec for a description of the HParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The relevant fields of the parameter block are:

    ioCompletion

    On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.

    ioResult

    On output, the result code of the function.

    ioNamePtr

    On input, a pointer to the name of the source file.

    ioVRefNum

    On input, the volume reference number or drive number for the volume containing the source file. Pass 0 for the default volume.

    ioDstVRefNum

    On input, the reference number or drive number of the destination volume. Pass 0 for the default volume.

    ioNewName

    On input, a pointer to the partial pathname for the destination directory. If ioNewName is NULL, the destination directory is the directory having the ID specified in the ioNewDirID field.

    ioCopyName

    On input, a pointer to the file’s new name. The string pointed to by this field must be a filename, not a partial pathname. If you do not wish to rename the file, pass NULL in this field.

    ioNewDirID

    On input, if the ioNewName field is NULL, the directory ID of the destination directory. If ioNewName is not NULL, the parent directory ID of the destination directory.

    ioDirID

    On input, the directory ID of the source directory.

    This function is especially useful when you want to copy or move files located on a remote volume, because it allows you to forgo transmitting large amounts of data across a network. This function is used internally by the Finder; most applications do not need to use it.

    Special Considerations

    This is an optional call for AppleShare file servers. Your application should examine the information returned by the PBHGetVolParmsAsync function to see if the volume supports PBHCopyFileAsync. If the bHasCopyFile bit is set in the vMAttrib field of the GetVolParmsInfoBuffer structure, then the volume supports PBHCopyFileAsync.

    For AppleShare file servers, the source and destination pathnames must indicate the same file server; however, the parameter block may specify different source and destination volumes on that file server. A useful way to tell if two file server volumes are on the same file server is to call the PBHGetVolParmsAsync function for each volume and compare the server addresses returned. The server opens source files with read/deny write enabled and destination files with write/deny read and write enabled.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • Moves a file or directory and optionally renames it.

    Deprecation Statement

    Use FSMoveObjectSync instead.

    Declaration

    Objective-C

    OSErr PBHMoveRenameSync ( HParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a CopyParam variant of the HFS parameter block. See HParamBlockRec for a description of the HParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The PBHMoveRenameSync function allows you to move (not copy) a file or directory. The source and destination pathnames must point to the same file server volume. This function is especially useful when you want to copy or move files located on a remote volume, because it allows you to forgo transmitting large amounts of data across a network. This function is used internally by the Finder; most applications do not need to use it.

    The relevant fields of the parameter block are:

    ioNamePtr

    On input, a pointer to the pathname for the source file or directory.

    ioVRefNum

    On input, a volume reference number or drive number for the volume containing the source file or directory. Pass 0 for the default volume.

    ioNewName

    On input, a pointer to the destination pathname. If ioNewName is NULL, the destination directory is the directory having the ID specified in the ioNewDirID field. If ioNewName is not NULL, the destination directory is the directory having the partial pathname pointed to by ioNewName in the directory having ID ioNewDirID on the specified volume.

    ioCopyName

    On input, a pointer to the file’s new name. The string pointed to by this field must be a filename, not a partial pathname. If you do not wish to rename the file, pass NULL in this field.

    ioNewDirID

    On input, if the ioNewName field is NULL, the directory ID of the destination directory. If ioNewName is not NULL, the parent directory ID of the destination directory.

    ioDirID

    On input, the directory ID of the source directory.

    Special Considerations

    This function is not implemented in OS X.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Moves a file or directory and optionally renames it.

    Deprecation Statement

    Use FSMoveObjectAsync instead.

    Declaration

    Objective-C

    OSErr PBHMoveRenameAsync ( HParmBlkPtr paramBlock );

    Parameters

    paramBlock

    A pointer to a CopyParam variant of the HFS parameter block. See HParamBlockRec for a description of the HParamBlockRec data type.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

    The PBHMoveRenameAsync function allows you to move (not copy) a file or directory. The source and destination pathnames must point to the same file server volume. This function is especially useful when you want to copy or move files located on a remote volume, because it allows you to forgo transmitting large amounts of data across a network. This function is used internally by the Finder; most applications do not need to use it.

    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.

    ioNamePtr

    On input, a pointer to the pathname for the source file or directory.

    ioVRefNum

    On input, a volume reference number or drive number for the volume containing the source file or directory. Pass 0 for the default volume.

    ioNewName

    On input, a pointer to the destination pathname. If ioNewName is NULL, the destination directory is the directory having the ID specified in the ioNewDirID field. If ioNewName is not NULL, the destination directory is the directory having the partial pathname pointed to by ioNewName in the directory having ID ioNewDirID on the specified volume.

    ioCopyName

    On input, a pointer to the file’s new name. The string pointed to by this field must be a filename, not a partial pathname. If you do not wish to rename the file, pass NULL in this field.

    ioNewDirID

    On input, if the ioNewName field is NULL, the directory ID of the destination directory. If ioNewName is not NULL, the parent directory ID of the destination directory.

    ioDirID

    On input, the directory ID of the source directory.

    Special Considerations

    This function is not implemented in OS X.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Creates an object that represents an asynchronous file operation.

    Deprecation Statement

    At the Foundation layer, use copyItemAtURL:toURL:error: instead. At the POSIX/BSD layer, use copyfile(3) OS X Developer Tools Manual Page instead.

    Declaration

    Objective-C

    FSFileOperationRef FSFileOperationCreate ( CFAllocatorRef alloc );

    Parameters

    alloc

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.8.

  • Cancels an asynchronous file operation.

    Deprecation Statement

    At the Foundation layer, use copyItemAtURL:toURL:error: instead. At the POSIX/BSD layer, use copyfile(3) OS X Developer Tools Manual Page instead.

    Declaration

    Objective-C

    OSStatus FSFileOperationCancel ( FSFileOperationRef fileOp );

    Parameters

    fileOp

    The file operation to cancel.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.8.

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

    Deprecation Statement

    At the Foundation layer, use copyItemAtURL:toURL:error: instead. At the POSIX/BSD layer, use copyfile(3) OS X Developer Tools Manual Page instead.

    Declaration

    Objective-C

    CFTypeID FSFileOperationGetTypeID ( void );

    Return Value

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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.8.

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

    Deprecation Statement

    At the Foundation layer, use copyItemAtURL:toURL:error: instead. At the POSIX/BSD layer, use copyfile(3) OS X Developer Tools Manual Page instead.

    Declaration

    Objective-C

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

    Parameters

    fileOp

    The file operation to schedule.

    runLoop

    The run loop in which to schedule the operation. For information about Core Foundation run loops, see Run Loops.

    runLoopMode

    The run loop mode in which to schedule the operation. In most cases, you may specify kCFRunLoopCommonModes.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.8.

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

    Deprecation Statement

    At the Foundation layer, use copyItemAtURL:toURL:error: instead. At the POSIX/BSD layer, use copyfile(3) OS X Developer Tools Manual Page instead.

    Declaration

    Objective-C

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

    Parameters

    fileOp

    The file operation to unschedule.

    runLoop

    The run loop on which to unschedule the operation.

    runLoopMode

    The run loop mode in which to unschedule the operation.

    Return Value

    A result code. See File Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.8.

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

    Deprecation Statement

    At the Foundation layer, use copyItemAtURL:toURL:error: instead. At the POSIX/BSD layer, use copyfile(3) OS X Developer Tools Manual Page instead.

    Declaration

    Objective-C

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

    Parameters

    fileOp

    The file operation object you created for this copy operation.

    source

    A pointer to the source object to copy. The object can be a file or a directory.

    destDir

    A pointer to the destination directory.

    destName

    The name for the new object in the destination directory. Pass NULL to use the name of the source object.

    flags

    One or more file operation option flags. See File Operation Options.

    callback

    A callback function to receive status updates as the file operation proceeds. For more information, see File Operation Callbacks. This parameter is optional; pass NULL if you don’t need to supply a status callback.

    statusChangeInterval

    The minimum time in seconds between callbacks within a single stage of an operation.

    clientContext

    User-defined data to associate with this operation. For more information, see FSFileOperationClientContext. This parameter is optional; pass NULL if you don’t need to supply a client context.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.8.

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

    Deprecation Statement

    At the Foundation layer, use moveItemAtURL:toURL:error: instead. At the POSIX/BSD layer, use rename(2) OS X Developer Tools Manual Page instead.

    Declaration

    Objective-C

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

    Parameters

    fileOp

    The file operation object you created for this move operation.

    source

    A pointer to the source object to move. The object can be a file or a directory.

    destDir

    A pointer to the destination directory. If the destination directory is not on the same volume as the source object, the source object is copied and then deleted.

    destName

    The name for the new object in the destination directory. Pass NULL to use the name of the source object.

    flags

    One or more file operation option flags. See File Operation Options. If you specify the kFSFileOperationDoNotMoveAcrossVolumes flag and the destination directory is not on the same volume as the source object, this function does nothing and returns an error.

    callback

    A callback function to receive status updates as the file operation proceeds. For more information, see File Operation Callbacks. This parameter is optional; pass NULL if you don’t need to supply a status callback.

    statusChangeInterval

    The minimum time in seconds between callbacks within a single stage of an operation.

    clientContext

    User-defined data to associate with this operation. For more information, see FSFileOperationClientContext. This parameter is optional; pass NULL if you don’t need to supply a client context.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.8.

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

    Deprecation Statement

    At the Foundation layer, use trashItemAtURL:resultingItemURL:error: instead.

    Declaration

    Objective-C

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

    Parameters

    fileOp

    The file operation object you created for this move operation. For more information, see the function FSFileOperationCreate.

    source

    A pointer to the source object to move. The object can be a file or a directory.

    flags

    One or more file operation option flags. See File Operation Options.

    callback

    A callback function to receive status updates as the file operation proceeds. For more information, see File Operation Callbacks. This parameter is optional; pass NULL if you don’t need to supply a status callback.

    statusChangeInterval

    The minimum time in seconds between callbacks within a single stage of an operation.

    clientContext

    User-defined data to associate with this operation. This data is passed to the function you specify in the callback parameter. For more information, see FSFileOperationClientContext. This parameter is optional; pass NULL if you don’t need to supply a client context.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

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

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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.8.

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

    Deprecation Statement

    At the Foundation layer, use copyItemAtPath:toPath:error: instead. At the POSIX/BSD layer, use copyfile(3) OS X Developer Tools Manual Page instead.

    Declaration

    Objective-C

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

    Parameters

    fileOp

    The file operation object you created for this copy operation.

    sourcePath

    The UTF-8 pathname of the source object to copy. The object can be a file or a directory.

    destDirPath

    The UTF-8 pathname of the destination directory.

    destName

    The name for the new object in the destination directory. Pass NULL to use the name of the source object.

    flags

    One or more file operation option flags. See File Operation Options.

    callback

    A callback function to receive status updates as the file operation proceeds. For more information, see File Operation Callbacks. This parameter is optional; pass NULL if you don’t need to supply a status callback.

    statusChangeInterval

    The minimum time in seconds between callbacks within a single stage of an operation.

    clientContext

    User-defined data to associate with this operation. For more information, see FSFileOperationClientContext. This parameter is optional; pass NULL if you don’t need to supply a client context.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.8.

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

    Deprecation Statement

    At the Foundation layer, use moveItemAtPath:toPath:error: instead. At the POSIX/BSD layer, use rename(2) OS X Developer Tools Manual Page instead.

    Declaration

    Objective-C

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

    Parameters

    fileOp

    The file operation object you created for this move operation.

    sourcePath

    The UTF-8 pathname of the source object to move. The object can be a file or a directory.

    destDirPath

    The UTF-8 pathname of the destination directory. If the destination directory is not on the same volume as the source object, the source object is copied and then deleted.

    destName

    The name for the new object in the destination directory. Pass NULL to use the name of the source object.

    flags

    One or more file operation option flags. See File Operation Options. If you specify the kFSFileOperationDoNotMoveAcrossVolumes flag and the destination directory is not on the same volume as the source object, this function does nothing and returns an error.

    callback

    A callback function to receive status updates as the file operation proceeds. For more information, see File Operation Callbacks. This parameter is optional; pass NULL if you don’t need to supply a status callback.

    statusChangeInterval

    The minimum time in seconds between callbacks within a single stage of an operation.

    clientContext

    User-defined data to associate with this operation. For more information, see FSFileOperationClientContext. This parameter is optional; pass NULL if you don’t need to supply a client context.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.8.

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

    Deprecation Statement

    At the Foundation layer, use trashItemAtURL:resultingItemURL:error: instead.

    Declaration

    Objective-C

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

    Parameters

    fileOp

    The file operation object you created for this move operation. For more information, see the function FSFileOperationCreate.

    sourcePath

    The UTF-8 pathname of the source object to move. The object can be a file or a directory.

    flags

    One or more file operation option flags. See File Operation Options.

    callback

    A callback function to receive status updates as the file operation proceeds. For more information, see File Operation Callbacks. This parameter is optional; pass NULL if you don’t need to supply a status callback.

    statusChangeInterval

    The minimum time in seconds between callbacks within a single stage of an operation.

    clientContext

    User-defined data to associate with this operation. This data is passed to the function you specify in the callback parameter. For more information, see FSFileOperationClientContext. This parameter is optional; pass NULL if you don’t need to supply a client context.

    Return Value

    A result code. See File Manager Result Codes.

    Discussion

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

    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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.8.

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

    Deprecation Statement

    At the Foundation layer, use copyItemAtURL:toURL:error: instead. At the POSIX/BSD layer, use copyfile(3) OS X Developer Tools Manual Page instead.

    Declaration

    Objective-C

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

    Parameters

    fileOp

    The file operation to access.

    currentItem

    A pointer to an FSRef variable. On output, the variable contains the object currently being moved or copied. If the operation is complete, this parameter refers to the target (the new object corresponding to the source object in the destination directory).

    stage

    A pointer to a file operation stage variable. On output, the variable contains the current stage of the file operation.

    error

    A pointer to an error status variable. On output, the variable contains the current error status of the file operation.

    statusDictionary

    A pointer to a dictionary variable. On output, the variable contains a dictionary with more detailed status information. For information about the contents of the dictionary, see “File Operation Status Dictionary Keys”. You should release the dictionary when you are finished using it.

    info

    A pointer to a generic pointer. On output, the generic pointer refers to user-defined data associated with this file operation.

    Return Value

    A result code. See File Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.8.

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

    Deprecation Statement

    At the Foundation layer, use copyItemAtURL:toURL:error: instead. At the POSIX/BSD layer, use copyfile(3) OS X Developer Tools Manual Page instead.

    Declaration

    Objective-C

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

    Parameters

    fileOp

    The file operation to access.

    currentItem

    A pointer to a char* variable. On output, the variable refers to the UTF-8 pathname of the object currently being moved or copied. If the operation is complete, this parameter refers to the target (the new object corresponding to the source object in the destination directory). You should free the pathname when you are finished using it.

    stage

    A pointer to a file operation stage variable. On output, the variable contains the current stage of the file operation.

    error

    A pointer to an error status variable. On output, the variable contains the current error status of the file operation.

    statusDictionary

    A pointer to a dictionary variable. On output, the variable contains a dictionary with more detailed status information. For information about the contents of the dictionary, see “File Operation Status Dictionary Keys”. You should release the dictionary when you are finished using it.

    info

    A pointer to a generic pointer. On output, the generic pointer refers to user-defined data associated with this file operation.

    Return Va