< Previous PageNext Page >

Hide TOC

Deprecated File Manager Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.4

Allocate

Allocates additional space on a volume to an open file. (Deprecated in Mac OS X v10.4. Use FSAllocateFork instead.)

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.

Availability

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

Declared In

Files.h

AllocContig

Allocates additional contiguous space on a volume to an open file. (Deprecated in Mac OS X v10.4. Use FSAllocateFork instead.)

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.

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.

Availability

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

Declared In

Files.h

CatMove

Moves files or directories from one directory to another on the same volume. (Deprecated in Mac OS X v10.4. Use FSMoveObject instead.)

OSErr CatMove (
   FSVolumeRefNum vRefNum,
   SInt32 dirID,
   ConstStr255Param oldName,
   SInt32 newDirID,
   ConstStr255Param newName
);

Parameters

vRefNum

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

dirID

The parent directory ID of the file or directory to move.

oldName

The existing name of the file or directory to move.

newDirID

If the newName parameter is empty, the directory ID of the destination directory; otherwise, the parent directory ID of the destination directory.

newName

The name of the destination directory. If a valid directory name is provided in this parameter, the destination directory’s parent directory is specified in the newDirID parameter. However, you can specify an empty name for newName, in which case newDirID should be set to the directory ID of the destination directory.

It is usually simplest to specify the destination directory by passing its directory ID in the newDirID parameter and by setting newName to an empty name. To specify an empty name, set newName to ':'.

Return Value

A result code. See “File Manager Result Codes.” This function returns permErr if called on a locked file.

Discussion

CatMove is strictly a file catalog operation; it does not actually change the location of the file or directory on the disk.

The CatMove function cannot move a file or directory to another volume (that is, the vRefNum parameter is used in specifying both the source and the destination). Also, you cannot use it to rename files or directories; to rename a file or directory, use HRename.

If you need to move files or directories with named forks other than the data and resource forks, with long Unicode names, or files larger than 2GB, you should use the FSMoveObject function, or one of the corresponding parameter block calls, PBMoveObjectSync and PBMoveObjectAsync.

Availability

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

Declared In

Files.h

DirCreate

Creates a new directory. (Deprecated in Mac OS X v10.4. Use FSCreateDirectoryUnicode instead.)

OSErr DirCreate (
   FSVolumeRefNum vRefNum,
   SInt32 parentDirID,
   ConstStr255Param directoryName,
   SInt32 *createdDirID
);

Parameters

vRefNum: A volume reference number, drive number, or 0 for the default volume.
parentDirID: The directory ID of the parent directory. If the parent directory ID is 0 and the volume specified in the vRefNum parameter is the default volume, the new directory is placed in the default directory of the volume. If the parent directory ID is 0 and the volume specified in the vRefNum parameter is a volume other than the default volume, the new directory is placed in the root directory of the volume. To create a directory at the root of a volume, regardless of whether that volume is the current default volume, pass the constant fsRtDirID(2) in this parameter.
directoryName: The name of the new directory.
createdDirID: On return, a pointer to the directory ID of the new directory. Note that a directory ID, unlike a volume reference number, is a long integer.

Return Value

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

Discussion

The date and time of the new directory’s creation and last modification are set to the current date and time.

To create a directory with a Unicode name, use the function FSCreateDirectoryUnicode , or one of the corresponding parameter block calls, PBCreateDirectoryUnicodeSync and PBCreateDirectoryUnicodeAsync.

Availability

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

Declared In

Files.h

FSClose

Closes an open file. (Deprecated in Mac OS X v10.4. Use FSCloseFork instead.)

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.

Availability

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

Declared In

Files.h

FSMakeFSSpec

Creates an FSSpec structure describing a file or directory. (Deprecated in Mac OS X v10.4. Use FSMakeFSRefUnicode instead.)

OSErr FSMakeFSSpec (
   FSVolumeRefNum vRefNum,
   SInt32 dirID,
   ConstStr255Param fileName,
   FSSpec *spec
);

Parameters

vRefNum

A volume specification for the volume containing the file or directory. This parameter can contain a volume reference number, a drive number, or 0 to specify the default volume.

dirID

The parent directory ID of the target object. If the directory is sufficiently specified in the fileName parameter, the dirID parameter can be set to 0. If the fileName parameter contains an empty string, FSMakeFSSpec creates an FSSpec structure for the directory specified by the dirID parameter.

fileName

A full or partial pathname. If the fileName parameter specifies a full pathname, FSMakeFSSpec ignores both the vRefNum and dirID parameters. A partial pathname might identify only the final target, or it might include one or more parent directory names. If fileName specifies a partial pathname, then vRefNum, dirID, or both must be valid.

spec

A pointer to a file system specification to be filled in by FSMakeFSSpec. The FSMakeFSSpec function fills in the fields of the file system specification using the information contained in the other three parameters. If your application receives any result code other than noErr or fnfErr, all fields of the resulting FSSpec structure are set to 0.

The file system specification structure that you pass in this parameter should not share storage space with the input pathname; the name field may be initialized to the empty string before the pathname has been processed. For example, fileName should not refer to the name field of the output file system specification.

Return Value

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

Discussion

You should call FSMakeFSSpec, or one of the corresponding parameter block functions, PBMakeFSSpecSync and PBMakeFSSpecAsync , whenever you want to create an FSSpec structure. You should not create an FSSpec by filling in the fields of the structure yourself.

If the specified volume is mounted and the specified parent directory exists, but the target file or directory doesn’t exist in that location, FSMakeFSSpec fills in the structure and then returns fnfErr instead of noErr. The structure is valid, but it describes a target that doesn’t exist. You can use the structure for other operations, such as creating a file with the FSpCreate function.

Carbon Porting Notes

Non-Carbon applications can also specify a working directory reference number in the vRefNum parameter. However, because working directories are not supported in Carbon, you cannot specify a working directory reference number if you wish your application to be Carbon-compatible.

Availability

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

Related Sample Code

Declared In

Files.h

FSpCatMove

Moves a file or directory from one location to another on the same volume. (Deprecated in Mac OS X v10.4. Use FSMoveObject instead.)

OSErr FSpCatMove (
   const FSSpec *source,
   const FSSpec *dest
);

Parameters

source

A pointer to an FSSpec structure specifying the name and location of the file or directory to move. See FSSpec for a description of the FSSpec data type.

dest

A pointer to an FSSpec structure specifying the name and location of the directory into which the source file or directory is to be moved. The directory ID specified in the parID field of this FSSpec is the directory ID of the parent of the directory into which you want to move the source file or directory. The name field of this FSSpec specifies the name of the directory into which you want to move the source file or directory.

If you don’t already know the parent directory ID of the destination directory, it might be easier to use the PBCatMoveSync or PBCatMoveAsync function, which allow you to specify only the directory ID of the destination directory.

Return Value

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

Discussion

The FSpCatMove function is strictly a file catalog operation; it does not actually change the location of the file or directory on the disk. You cannot use FSpCatMove to move a file or directory to another volume (that is, the vRefNum field in both FSSpec structures in the source and dest parameters must be the same). Also, you cannot use FSpCatMove to rename files or directories; to rename a file or directory, use FSpRename.

Availability

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

Declared In

Files.h

FSpCreate

Creates a new file. (Deprecated in Mac OS X v10.4. Use FSCreateFileUnicode instead.)

OSErr FSpCreate (
   const FSSpec *spec,
   OSType creator,
   OSType fileType,
   ScriptCode scriptTag
);

Parameters

spec

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

creator

The creator of the new file. See the documentation for the Finder Interface for more information on file creators.

fileType

The file type of the new file. See the documentation for the Finder Interface for more information on file types.

scriptTag

The code of the script system in which the filename is to be displayed. If you have established the name and location of the new file using either the NavAskSaveChanges or NavCustomAskSaveChanges function, specify the script code returned in the reply structure. Otherwise, specify the system script by setting the scriptTag parameter to the value smSystemScript.

For more information about the functions NavAskSaveChanges and NavCustomAskSaveChanges, see Programming With Navigation Services. See the Script Manager Reference for a description of the smSystemScript constant.

Return Value

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

Discussion

The FSpCreate function creates a new file (both data and resource forks) with the specified type, creator, and script code. The new file is unlocked and empty. The date and time of creation and last modification are set to the current date and time.

Files created using FSpCreate are not automatically opened. If you want to write data to the new file, you must first open the file using one of the file access functions, FSpOpenDF , HOpenDF , PBHOpenDFSync or PBHOpenDFAsync.

The resource fork of the new file exists but is empty. You’ll need to call one of the Resource Manager functions HCreateResFile or FSpCreateResFile to create a resource map in the file before you can open it by calling one of the Resource Manager functions HOpenResFile or FSpOpenResFile).

Before calling this function, you should call the Gestalt function to check that the function is available. If FSpCreate is not available, you can use the function HCreate instead. To create a file with a Unicode filename, use the function FSCreateFileUnicode , or one of the corresponding parameter block calls, PBCreateFileUnicodeSync and PBCreateFileUnicodeAsync.

Availability

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

Declared In

Files.h

FSpDelete

Deletes a file or directory. (Deprecated in Mac OS X v10.4. Use FSDeleteObject instead.)

OSErr FSpDelete (
   const FSSpec *spec
);

Parameters

spec: A pointer to an FSSpec structure specifying the file or directory to delete. See FSSpec for a description of the FSSpec data type.

Return Value

A result code. See “File Manager Result Codes.” If you attempt to delete an open file or a non-empty directory, FSpDelete returns the result code fBsyErr. FSpDelete also returns the result code fBsyErr if the directory has an open working directory associated with it.

Discussion

If the specified target is a file, both forks of the file are deleted. The file ID reference, if any, is removed. A file must be closed before you can delete it. Similarly, a directory must be empty before you can delete it.

Before calling this function, you should call the Gestalt function to check that the function is available. If FSpDelete is not available, you can use the function HDelete instead.

Availability

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

Related Sample Code

CarbonSketch

Declared In

Files.h

FSpDirCreate

Creates a new directory. (Deprecated in Mac OS X v10.4. Use FSCreateDirectoryUnicode instead.)

OSErr FSpDirCreate (
   const FSSpec *spec,
   ScriptCode scriptTag,
   SInt32 *createdDirID
);

Parameters

spec

A pointer to an FSSpec structure specifying the directory to be created.

Note that if the parent directory ID for the directory described by this FSSpec is 0 and the volume specified in this FSSpec is the default volume, the new directory is placed in the default directory of the volume. If the parent directory ID is 0 and the specified volume is a volume other than the default volume, the new directory is placed in the root directory of the volume. To create a directory at the root of a volume, regardless of whether that volume is the current default volume, set the parent directory ID to the constant fsRtDirID(2).

scriptTag

The code of the script system in which the directory name is to be displayed. If you have established the name and location of the new directory using either the NavAskSaveChanges or NavCustomAskSaveChanges function, specify the script code returned in the reply structure. Otherwise, specify the system script by setting the scriptTag parameter to the value smSystemScript.

For more information on the functions NavAskSaveChanges and NavCustomAskSaveChanges, see Programming With Navigation Services. For a description of the smSystemScript constant, see the Script Manager Reference.

createdDirID

On return, a pointer to the directory ID of the directory that was created.

Return Value

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

Discussion

The FSpDirCreate function sets the date and time of creation and last modification to the current date and time.

Before calling this function, you should call the Gestalt function to check that the function is available. If FSpDirCreate is not available, you can use the function DirCreate instead. To create a directory with a Unicode name, use the function FSCreateDirectoryUnicode , or one of the corresponding parameter block calls, PBCreateDirectoryUnicodeSync and PBCreateDirectoryUnicodeAsync.

Availability

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

Declared In

Files.h

FSpExchangeFiles

Exchanges the data stored in two files on the same volume. (Deprecated in Mac OS X v10.4. Use FSExchangeObjects instead.)

OSErr FSpExchangeFiles (
   const FSSpec *source,
   const FSSpec *dest
);

Parameters

source: A pointer to an FSSpec for the first file to swap. The contents of this file and its file information are placed in the file specified in the dest parameter. See FSSpec for a description of the FSSpec data type.
dest: A pointer to an FSSpec for the second file to swap. The contents of this file and its file information are placed in the file specified in the source parameter.

Return Value

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

Discussion

The FSpExchangeFiles function swaps the data in two files by changing the information in the volume’s catalog and, if either of the files are open, in the file control blocks. The following fields in the catalog entries for the files are exchanged:

ioFlStBlk
ioFlLgLen
ioFlPyLen
ioFlRStBlk
ioFlRLgLen
ioFlRPyLen
ioFlMdDat

In the file control blocks, the fcbFlNum, fcbDirID, and fcbCName fields are exchanged.

You should use FSpExchangeFiles when updating an existing file, so that the file ID remains valid in case the file is being tracked through its file ID. The FSpExchangeFiles function changes the fields in the catalog entries that record the location of the data and the modification dates. It swaps both the data forks and the resource forks.

The FSpExchangeFiles function works on both open and closed files. If either file is open, FSpExchangeFiles updates any file control blocks associated with the file. Exchanging the contents of two files requires essentially the same access permissions as opening both files for writing.

The files whose data is to be exchanged must both reside on the same volume. If they do not, FSpExchangeFiles returns the result code diffVolErr.

To exchange the contents of files with named forks other than the data and resource forks, or of files larger than 2 GB, use the FSExchangeObjects , PBExchangeObjectsSync , or PBExchangeObjectsAsync function.

Special Considerations

The “compatibility code,” by which FSpExchangeFiles attempted to perform the file exchange itself if it suspected that the underlying filesystem did not have Exchange capability, has been removed in Mac OS 9 and X.

Because other programs may have access paths open to one or both of the files exchanged, your application should have exclusive read/write access permission (fsRdWrPerm) to both files before calling FSpExchangeFiles. Exclusive read/write access to both files will ensure that FSpExchangeFiles doesn't affect another application because it prevents other applications from obtaining write access to one or both of the files exchanged.

FSpExchangeFiles does not respect the file-locked attribute; it will perform the exchange even if one or both of the files are locked. Obtaining exclusive read/write access to both files before calling FSpExchangeFiles ensures that the files are unlocked because locked files cannot be opened with write access.

Availability

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

Declared In

Files.h

FSpGetFInfo

Obtains the Finder information for a file. (Deprecated in Mac OS X v10.4. Use FSGetCatalogInfo instead.)

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.”

Availability

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

Related Sample Code

QTCarbonShell

Declared In

Files.h

FSpOpenDF

Opens the data fork of a file. (Deprecated in Mac OS X v10.4. Use FSOpenFork instead.)

OSErr FSpOpenDF (
   const FSSpec *spec,
   SInt8 permission,
   FSIORefNum *refNum
);

Parameters

spec: A pointer to an FSSpec structure specifying the file whose data fork is to be opened. See FSSpec for a description of the FSSpec data type.
permission: A constant indicating the type of access with which to open the file’s data fork. In most cases, you can simply set the permission parameter to fsCurPerm. Some applications request fsRdWrPerm, to ensure that they can both read from and write to a file. For a description of the types of access that you can request, see “File Access Permission Constants.”
refNum: On return, a pointer to the file reference number for accessing the open data fork.

Return Value

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

Discussion

Before calling this function, you should call the Gestalt function to check that the function is available. If FSpOpenDF is not available, you can use the function HOpenDF instead.

Note that if you wish to access named forks other than the data and resource forks, or forks larger than 2GB, you will need to use the FSOpenFork function, or one of its corresponding parameter block calls, PBOpenForkSync and PBOpenForkAsync. If you try to open a fork larger than 2GB with the FSpOpenDF function, you will receive an error message.

Availability

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

Declared In

Files.h

FSpOpenRF

Opens the resource fork of a file. (Deprecated in Mac OS X v10.4. Use FSOpenFork instead.)

OSErr FSpOpenRF (
   const FSSpec *spec,
   SInt8 permission,
   FSIORefNum *refNum
);

Parameters

spec: A pointer to an FSSpec structure specifying the file whose resource fork is to be opened. See FSSpec for a description of the FSSpec data type.
permission: A constant indicating the type of access with which to open the file’s resource fork. For a description of the types of access you can request, see “File Access Permission Constants.”
refNum: On return, a pointer to the file reference number for accessing the open resource fork.

Return Value

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

Discussion

Before calling this function, you should call the Gestalt function to check that the function is available. If FSpOpenRF is not available, you can use the function HOpenRF instead.

Note that if you wish to access named forks other than the data and resource forks, or forks larger than 2GB, you will need to use the FSOpenFork function, or one of its corresponding parameter block calls, PBOpenForkSync or PBOpenForkAsync. If you try to open a fork larger than 2GB with the FSpOpenRF function, you will receive an error message.

Special Considerations

Generally, your application should use Resource Manager functions rather than File Manager functions to access a file’s resource fork. The FSpOpenRF function does not read the resource map into memory and is generally useful only for applications (such as utilities that copy files) that need block-level access to a resource fork.

You should not use the resource fork of a file to hold non-resource data. Many parts of the system software assume that a resource fork always contains resource data.

Because there is no support for locking and unlocking file ranges on local disks in Mac OS X, regardless of whether File Sharing is enabled, you cannot open more than one path to a resource fork with read/write permission. If you try to open a more than one path to a file's resource fork with fsRdWrShPerm permission, only the first attempt will succeed. Subsequent attempts will return an invalid reference number and the ResError function will return the error opWrErr.

Availability

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

Declared In

Files.h

FSpRename

Renames a file or directory. (Deprecated in Mac OS X v10.4. Use FSRenameUnicode instead.)

OSErr FSpRename (
   const FSSpec *spec,
   ConstStr255Param newName
);

Parameters

spec: A pointer to an FSSpec structure specifying the file or directory to rename. See FSSpec for a description of the FSSpec data type.
newName: The new name of the file or directory.

Return Value

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

Discussion

If a file ID reference for the specified file exists, it remains with the renamed file.

If you want to change the name of a new copy of an existing file, you should use the FSpExchangeFiles function instead. To rename a file or directory using a long Unicode name, use the FSRenameUnicode function or one of the corresponding parameter block calls, PBRenameUnicodeSync and PBRenameUnicodeAsync.

Availability

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

Declared In

Files.h

FSpRstFLock

Unlocks a file or directory. (Deprecated in Mac OS X v10.4. Use FSSetCatalogInfo instead.)

OSErr FSpRstFLock (
   const FSSpec *spec
);

Parameters

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

Return Value

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

Discussion

If the PBHGetVolParmsSync or PBHGetVolParmsAsync function indicates that the volume supports folder locking (that is, the bHasFolderLock bit of the vMAttrib field is set), you can use FSpRstFLock to unlock a directory. Otherwise, you can only use this function to unlock a file.

You can lock a file or directory with the FSpSetFLock , HSetFLock , PBHSetFLockSync , and PBHSetFLockAsync functions.

Availability

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

Declared In

Files.h

FSpSetFInfo

Sets the Finder information about a file. (Deprecated in Mac OS X v10.4. Use FSSetCatalogInfo instead.)

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.

Availability

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

Related Sample Code

Declared In

Files.h

FSpSetFLock

Locks a file or directory. (Deprecated in Mac OS X v10.4. Use FSSetCatalogInfo instead.)

OSErr FSpSetFLock (
   const FSSpec *spec
);

Parameters

spec: A pointer to an FSSpec structure specifying the file or directory to lock. See FSSpec for a description of the FSSpec data type.

Return Value

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

Discussion

If the PBHGetVolParmsSync or PBHGetVolParmsAsync functions indicate that the volume supports folder locking (that is, the bHasFolderLock bit of the vMAttrib field is set), you can use FSpSetFLock to lock a directory. Otherwise, you can only use this function to lock a file.

After you lock a file, all new access paths to that file are read-only. This function has no effect on existing access paths.

Availability

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

Declared In

Files.h

FSRead

Reads any number of bytes from an open file. (Deprecated in Mac OS X v10.4. Use FSReadFork instead.)

OSErr FSRead (
   FSIORefNum refNum,
   SInt32 *count,
   void *buffPtr
);

Parameters

refNum: The file reference number of the open file from which to read.
count: On input, a pointer to the number of bytes to read; on output, a pointer to the number of bytes actually read.
buffPtr: A pointer to the data buffer into which the data will be read. This buffer is allocated by your application and must be at least as large as the count parameter.

Return Value

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

Discussion

Because the read operation begins at the current mark, you might want to set the mark first by calling the SetFPos function. If you try to read past the logical end-of-file, FSRead reads in all the data up to the end-of-file, moves the mark to the end-of-file, and returns eofErr as its function result. Otherwise, FSRead moves the file mark to the byte following the last byte read and returns noErr.

The low-level functions PBReadSync and PBReadAsync let you set the mark without having to call SetFPos. Furthermore, if you want to read data in newline mode, you must use PBReadSync or PBReadAsync instead of FSRead.

If you wish to read from named forks other than the data or resource forks, or from files larger than 2GB, you must use the FSReadFork function, or one of its corresponding parameter block calls, PBReadForkSync and PBReadForkAsync. If you attempt to use FSRead to read from a file larger than 2GB, you will receive an error message.

Availability

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

Declared In

Files.h

FSWrite

Writes any number of bytes to an open file. (Deprecated in Mac OS X v10.4. Use FSWriteFork instead.)

OSErr FSWrite (
   FSIORefNum refNum,
   SInt32 *count,
   const void *buffPtr
);

Parameters

refNum

The file reference number of the open file to which to write.

count

On input, a pointer to the number of bytes to write to the file. Passing 0 in this parameter will return a paramErr error.

On output, a pointer to the number of bytes actually written.

buffPtr

A pointer to the data buffer containing the data to write.

Return Value

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

Discussion

The FSWrite function takes the specified number of bytes from the data buffer and attempts to write them to the file. Because the write operation begins at the current mark, you might want to set the mark first by calling the SetFPos function.

If the write operation completes successfully, FSWrite moves the file mark to the byte following the last byte written and returns noErr. If you try to write past the logical end-of-file, FSWrite moves the logical end-of-file. If you try to write past the physical end-of-file, FSWrite adds one or more clumps to the file and moves the physical end-of-file accordingly.

The low-level functions PBWriteSync and PBWriteAsync let you set the mark without having to call SetFPos.

If you wish to write to named forks other than the data or resource forks, or grow files larger than 2GB, you must use the FSWriteFork function, or one of its corresponding parameter block calls, PBWriteForkSync and PBWriteForkAsync. If you attempt to use FSWrite to write to a file larger than 2GB, you will receive an error message.

Availability

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

Declared In

Files.h

GetEOF

Determines the current logical size of an open file. (Deprecated in Mac OS X v10.4. Use FSGetForkSize instead.)

OSErr GetEOF (
   FSIORefNum refNum,
   SInt32 *logEOF
);

Parameters

refNum: The file reference number of an open file.
logEOF: On return, a pointer to the logical size (the logical end-of-file) of the given file.

Return Value

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

Discussion

To determine the size of a named fork other than the data or resource forks, or of a fork larger than 2 GB, use the FSGetForkSize function, or one of the corresponding parameter block functions, PBGetForkSizeSync and PBGetForkSizeAsync.

Availability

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

Declared In

Files.h

GetFPos

Returns the current position of the file mark. (Deprecated in Mac OS X v10.4. Use FSGetForkPosition instead.)

OSErr GetFPos (
   FSIORefNum refNum,
   SInt32 *filePos
);

Parameters

refNum: The file reference number of an open file.
filePos: On return, a pointer to the current position of the mark. The position value is zero-based; that is, the value of filePos is 0 if the file mark is positioned at the beginning of the file.

Return Value

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

Discussion

Because the read and write operations performed by the functions FSRead and FSWrite begin at the current mark, you should call GetFPos, or one of the parameter block functions, PBGetFPosSync and PBGetFPosAsync , to determine the current position of the file mark before reading from or writing to the file.

To determine the current position of a named fork, or of a fork larger than 2GB, use the FSGetForkPosition function, or one of the corresponding parameter block calls, PBGetForkPositionSync and PBGetForkPositionAsync.

Availability

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

Declared In

Files.h

GetVRefNum

Gets a volume reference number from a file reference number. (Deprecated in Mac OS X v10.4. Use FSGetCatalogInfo instead.)

OSErr GetVRefNum (
   FSIORefNum fileRefNum,
   FSVolumeRefNum *vRefNum
);

Parameters

fileRefNum: The file reference number of an open file.
vRefNum: On return, a pointer to the volume reference number of the volume containing the file specified in the refNum parameter.

Return Value

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

Discussion

If you also want to determine the directory ID of the specified file’s parent directory, call the PBGetFCBInfoSync or PBGetFCBInfoAsync functions.

Availability

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

Declared In

Files.h

HCreate

Creates a new file. (Deprecated in Mac OS X v10.4. Use FSCreateFileUnicode instead.)

OSErr HCreate (
   FSVolumeRefNum vRefNum,
   SInt32 dirID,
   ConstStr255Param fileName,
   OSType creator,
   OSType fileType
);

Parameters

vRefNum

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

dirID

The directory ID of the directory in which to create the new file.

fileName

The name of the new file. This can be a full or partial pathname.

You should not allow users to give files names that begin with a period (.). This ensures that files can be successfully opened by applications calling HOpen instead of HOpenDF.

creator

The creator of the new file. For more information on a file’s creator, see the Finder Interface documentation.

fileType

The file type of the new file. For more information on a file’s type, see the Finder Interface documentation.

Return Value

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

Discussion

The HCreate function creates a new file (both data and resource forks) with the specified name, creator, and file type. The new file is unlocked and empty. The date and time of its creation and last modification are set to the current date and time.

Files created using HCreate are not automatically opened. If you want to write data to the new file, you must first open the file using a file access function.

The resource fork of the new file exists but is empty. You’ll need to call one of the Resource Manager functions HCreateResFile or FSpCreateResFile to create a resource map in the file before you can open it (by calling one of the Resource Manager functions HOpenResFile or FSpOpenResFile).

To create a file with a Unicode filename, use the function FSCreateFileUnicode , or one of the corresponding parameter block calls, PBCreateFileUnicodeSync and PBCreateFileUnicodeAsync.

Availability

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

Declared In

Files.h

HDelete

Deletes a file or directory. (Deprecated in Mac OS X v10.4. Use FSDeleteObject instead.)

OSErr HDelete (
   FSVolumeRefNum vRefNum,
   SInt32 dirID,
   ConstStr255Param fileName
);

Parameters

vRefNum: A volume reference number, drive number, or 0 for the default volume.
dirID: The directory ID of the parent directory of the file or directory to delete.
fileName: The name of the file or directory to delete. This can be a full or partial pathname.

Return Value

A result code. See “File Manager Result Codes.” If you attempt to delete an open file or a non-empty directory, HDelete returns the result code fBsyErr. HDelete also returns the result code fBsyErr if the directory has an open working directory associated with it.

Discussion

If the specified target is a file, both the data and the resource fork of the file are deleted. In addition, if a file ID reference for the specified file exists, that reference is removed. A file must be closed before you can delete it. Similarly, you cannot delete a directory unless it’s empty.

Availability

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

Declared In

Files.h

HGetFInfo

Obtains the Finder information for a file. (Deprecated in Mac OS X v10.4. Use FSGetCatalogInfo instead.)

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.”

Availability

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

Declared In

Files.h

HGetVol

Determines the current default volume and default directory. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr HGetVol (
   StringPtr volName,
   FSVolumeRefNum *vRefNum,
   SInt32 *dirID
);

Parameters

volName: On return, a pointer to the name of the default volume. If you do not want the name of the default volume returned, set this parameter to NULL.
vRefNum: On return, a pointer to the volume reference number of the default volume.
dirID: On return, a pointer to the directory ID of the default directory.

Return Value

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

Version Notes

When CarbonLib is not present, the HGetVol function returns a working directory reference number in the vRefNum parameter if the previous call to HSetVol (or one of the corresponding parameter block calls) passed in a working directory reference number.

Carbon Porting Notes

Carbon applications should use HGetVol and HSetVol to get and set the default directory. the functions GetVol and SetVol, as well as working directories, are no longer supported.

Availability

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

Declared In

Files.h

HOpen

Opens the data fork of a file. (Deprecated in Mac OS X v10.4. Use FSOpenFork instead.)

OSErr HOpen (
   FSVolumeRefNum vRefNum,
   SInt32 dirID,
   ConstStr255Param fileName,
   SInt8 permission,
   FSIORefNum *refNum
);

Parameters

vRefNum: A volume reference number, drive number, or 0 for the default volume.
dirID: The directory ID of the file’s parent directory.
fileName: The name of the file.
permission: A constant specifying the type of access with which to open the file’s data fork. For a description of the types of access you can request, see “File Access Permission Constants.”
refNum: On return, a pointer to the file reference number for accessing the open fork.

Return Value

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

Discussion

If you use HOpen to try to open a file whose name begins with a period, you might mistakenly open a driver instead; subsequent attempts to write data might corrupt data on the target device. To avoid these problems, you should always use HOpenDF instead of HOpen.

Special Considerations

Availability

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

Declared In

Files.h

HOpenDF

Opens the data fork of a file. (Deprecated in Mac OS X v10.4. Use FSOpenFork instead.)

OSErr HOpenDF (
   FSVolumeRefNum vRefNum,
   SInt32 dirID,
   ConstStr255Param fileName,
   SInt8 permission,
   FSIORefNum *refNum
);

Parameters

vRefNum: A volume reference number, drive number, or 0 for the default volume.
dirID: The directory ID of the file’s parent directory.
fileName: The name of the file.
permission: A constant specifying the type of access with which to open the file’s data fork. For a description of the types of access which you can request, see “File Access Permission Constants.”
refNum: On return, a pointer to the file reference number for accessing the open data fork.

Return Value

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

Discussion

Note that if you wish to access named forks other than the data and resource forks, or forks larger than 2GB, you will need to use the FSOpenFork function, or one of the corresponding parameter block calls, PBOpenForkSync or PBOpenForkAsync. If you try to open a fork larger than 2GB with the HOpenDF function, you will receive an error message.

Availability

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

Declared In

Files.h

HOpenRF

Opens the resource fork of a file. (Deprecated in Mac OS X v10.4. Use FSOpenFork instead.)

OSErr HOpenRF (
   FSVolumeRefNum vRefNum,
   SInt32 dirID,
   ConstStr255Param fileName,
   SInt8 permission,
   FSIORefNum *refNum
);

Parameters

vRefNum: A volume reference number, drive number, or 0 for the default volume.
dirID: The directory ID for the file’s parent directory.
fileName: The name of the file.
permission: A constant specifying the type of access with which to open the file’s resource fork. For a description of the types of access you can request, see “File Access Permission Constants.”
refNum: On return, a pointer to the file reference number for accessing the open resource fork.

Return Value

A result code. See “File Manager Result Codes.” If you try to open the resource fork of a file for which no resource fork exists with read-only access, HOpenRF returns the error eofErr.

Discussion

Note that if you wish to access named forks other than the data and resource forks, or forks larger than 2GB, you will need to use the FSOpenFork function, or one of its corresponding parameter block calls, PBOpenForkSync or PBOpenForkAsync. If you try to open a fork larger than 2GB with the HOpenRF function, you will receive an error message.

Special Considerations

Generally, your application should use Resource Manager functions rather than File Manager functions to access a file’s resource fork. The HOpenRF function does not read the resource map into memory and is generally useful only for applications (such as utilities that copy files) that need block-level access to a resource fork.

You should not use the resource fork of a file to hold non-resource data. Many parts of the system software assume that a resource fork always contains resource data.

Availability

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

Declared In

Files.h

HRename

Renames a file, directory, or volume. (Deprecated in Mac OS X v10.4. Use FSRenameUnicode instead.)

OSErr HRename (
   FSVolumeRefNum vRefNum,
   SInt32 dirID,
   ConstStr255Param oldName,
   ConstStr255Param newName
);

Parameters

vRefNum: A volume reference number, drive number, or 0 for the default volume.
dirID: A directory ID.
oldName: An existing filename, directory name, or volume name.
newName: The new filename, directory name, or volume name.

Return Value

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

Discussion

Given the name of a file or directory in the oldName parameter, HRename changes it to the name in the newName parameter. Given a volume name in the oldName parameter or a volume reference number in the vRefNum parameter, HRename changes the name of the volume to the name in newName. Access paths currently in use aren’t affected by this function.

If a file ID reference exists for a file you are renaming, the file ID remains with the renamed file.

To rename a file or directory using a long Unicode name, use the FSRenameUnicode function or one of the corresponding parameter block calls, PBRenameUnicodeSync and PBRenameUnicodeAsync.

Special Considerations

You cannot use HRename to change the directory in which a file resides. To move a file or directory, use the FSpCatMove, PBCatMoveSync, or PBCatMoveAsync functions.

If you’re renaming a volume, make sure that both names end with a colon.

Availability

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

Declared In

Files.h

HRstFLock

Unlocks a file or directory. (Deprecated in Mac OS X v10.4. Use FSSetCatalogInfo instead.)

OSErr HRstFLock (
   FSVolumeRefNum vRefNum,
   SInt32 dirID,
   ConstStr255Param fileName
);

Parameters

vRefNum: A volume reference number, drive number, or 0 for the default volume.
dirID: The parent directory ID of the file or directory to unlock.
fileName: The name of the file or directory.

Return Value

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

Discussion

If the PBHGetVolParmsSync or PBHGetVolParmsAsync function indicates that the volume supports folder locking (that is, the bHasFolderLock bit of the vMAttrib field is set), you can use HRstFLock to unlock a directory. Otherwise, you can only use this function to unlock a file.

You can lock a file or directory with the FSpSetFLock , HSetFLock , PBHSetFLockSync , and PBHSetFLockAsync functions.

Availability

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

Declared In

Files.h

HSetFInfo

Sets the Finder information for a file. (Deprecated in Mac OS X v10.4. Use FSSetCatalogInfo instead.)

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.”

Availability

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

Declared In

Files.h

HSetFLock

Locks a file or directory. (Deprecated in Mac OS X v10.4. Use FSSetCatalogInfo instead.)

OSErr HSetFLock (
   FSVolumeRefNum vRefNum,
   SInt32 dirID,
   ConstStr255Param fileName
);

Parameters

vRefNum: A volume reference number, drive number, or 0 for the default volume.
dirID: The parent directory ID of the file or directory to lock.
fileName: The name of the file or directory.

Return Value

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

Discussion

If the PBHGetVolParmsSync or PBHGetVolParmsAsync function indicates that the volume supports folder locking (that is, the bHasFolderLock bit of the vMAttrib field is set), you can use HSetFLock to lock a directory. Otherwise, you can only use this function to lock a file.

After you lock a file, all new access paths to that file are read-only. This function has no effect on existing access paths.

Availability

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

Declared In

Files.h

HSetVol

Sets the default volume and the default directory. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr HSetVol (
   ConstStr63Param volName,
   FSVolumeRefNum vRefNum,
   SInt32 dirID
);

Parameters

volName: The name of a mounted volume or the partial pathname of a directory. This parameter can be NULL.
vRefNum: A volume reference number, drive number, or 0 for the default volume.
dirID: A directory ID.

Return Value

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

Discussion

The HSetVol function lets you specify the default directory by volume reference number or by directory ID.

Both the default volume and the default directory are used in calls made with no volume name, a volume reference number of 0, and a directory ID of 0.

Special Considerations

Use of the HSetVol function is discouraged if your application may execute in system software versions prior to version 7.0. Because the specified directory might not itself be a working directory, HSetVol records the default volume and directory separately, using the volume reference number of the volume and the actual directory ID of the specified directory. Subsequent calls to GetVol (or PBGetVolSync or PBGetVolAsync) return only the volume reference number, which will cause that volume’s root directory (rather than the default directory, as expected) to be accessed.

Carbon Porting Notes

Carbon applications should use HGetVol and HSetVol to get and set the default directory. the functions GetVol and SetVol, as well as working directories, are no longer supported.

Availability

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

Declared In

Files.h

PBAllocateAsync

Allocates additional space on a volume to an open file. (Deprecated in Mac OS X v10.4. Use PBAllocateForkAsync instead.)

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.

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.

Availability

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

Declared In

Files.h

PBAllocateSync

Allocates additional space on a volume to an open file. (Deprecated in Mac OS X v10.4. Use PBAllocateForkSync instead.)

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.

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.

Availability

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

Declared In

Files.h

PBAllocContigAsync

Allocates additional contiguous space on a volume to an open file. (Deprecated in Mac OS X v10.4. Use PBAllocateForkAsync instead.)

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.

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.

Availability

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

Declared In

Files.h

PBAllocContigSync

Allocates additional contiguous space on a volume to an open file. (Deprecated in Mac OS X v10.4. Use PBAllocateForkSync instead.)

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.

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.

Availability

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

Declared In

Files.h

PBCatMoveAsync

Moves files or directories from one directory to another on the same volume. (Deprecated in Mac OS X v10.4. Use PBMoveObjectAsync instead.)

OSErr PBCatMoveAsync (
   CMovePBPtr paramBlock
);

Parameters

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

Return Value

A result code. See “File Manager Result Codes.” This function returns permErr if called on a locked file.

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 or directory to move.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioNewName: On input, a pointer to the name of the destination directory. Pass NULL in this field if you wish to specify the destination directory by its directory ID.
ioNewDirID: On input, if the ioNewName field is NULL, the directory ID of the destination directory. If ioNewName is not NULL, this is the parent directory ID of the directory into which the file or directory is to be moved. It is usually simplest to specify the destination directory by passing its directory ID in the ioNewDirID field and by setting ioNewName to NULL.
ioDirID: On input, the parent directory ID of the file or directory to move.

PBCatMoveAsync is strictly a file catalog operation; it does not actually change the location of the file or directory on the disk. If a file ID reference exists for the file, the file ID reference remains with the moved file.

The PBCatMoveAsync function cannot move a file or directory to another volume (that is, the value in the ioVRefNum field is used in specifying both the source and the destination). Also, you cannot use it to rename files or directories; to rename a file or directory, use FSpRename , PBHRenameSync , or PBHRenameAsync .

Availability

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

Declared In

Files.h

PBCatMoveSync

Moves files or directories from one directory to another on the same volume. (Deprecated in Mac OS X v10.4. Use PBMoveObjectSync instead.)

OSErr PBCatMoveSync (
   CMovePBPtr paramBlock
);

Parameters

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

Return Value

A result code. See “File Manager Result Codes.” This function returns permErr if called on a locked file.

Discussion

The relevant fields of the parameter block are:

ioNamePtr: On input, a pointer to the name of the file or directory to move.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioNewName: On input, a pointer to the name of the destination directory. Pass NULL in this field if you wish to specify the destination directory by its directory ID.
ioNewDirID: On input, if the ioNewName field is NULL, the directory ID of the destination directory. If ioNewName is not NULL, this is the parent directory ID of the destination directory. It is usually simplest to specify the destination directory by passing its directory ID in the ioNewDirID field and by setting ioNewName to NULL.
ioDirID: On input, the parent directory ID of the file or directory to move.

PBCatMoveSync is strictly a file catalog operation; it does not actually change the location of the file or directory on the disk. If a file ID reference exists for the file, the file ID reference remains with the moved file.

The PBCatMoveSync function cannot move a file or directory to another volume (that is, the value in the ioVRefNum field is used in specifying both the source and the destination). Also, you cannot use it to rename files or directories; to rename a file or directory, use FSpRename , PBHRenameSync , or PBHRenameAsync.

Availability

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

Declared In

Files.h

PBCatSearchAsync

Searches a volume’s catalog file using a set of search criteria that you specify. (Deprecated in Mac OS X v10.4. Use PBCatalogSearchAsync instead.)

OSErr PBCatSearchAsync (
   CSParamPtr paramBlock
);

Parameters

paramBlock: A pointer to a CSParam 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 routine. For more information on completion routines, see IOCompletionProcPtr.
ioResult: On output, the result code of the function. When PBCatSearchAsync has searched the entire volume, it returns eofErr. If it exits because it either spends the maximum time allowed in the ioSearchTime field or finds the maximum number of matches allowed in the ioReqMatchCount field, it returns noErr.
ioNamePtr: On input, a pointer to the name of the volume to search.
ioVRefNum: On input, a volume reference number or drive number for the volume to search; or 0 for the default volume.
ioMatchPtr: On input, a pointer to an array of FSSpec structure to hold the matches found by this function. On return, the FSSpec structures in this array identify the files and directories that match the criteria.
ioReqMatchCount: On input, the maximum number of matches to return.
ioActMatchCount: On output, the actual number of matches returned.
ioSearchBits: On input, a bitmap specifying the fields in the criteria structures to match against. See “Catalog Search Masks” for a description of the bits in this field.
ioSearchInfo1: On input, a pointer to a CInfoPBRec union containing search information. For values that match by mask and value (Finder information, for example), set the bits in the structure passed in ioSearchInfo2, and set the matching value in this structure. For values that match against a range (such as dates), set the lower bounds for the range in this structure.
ioSearchInfo2: On input, a pointer to a CInfoPBRec union containing search information. For values that match by mask and value (Finder information, for example), set the bits in this structure, and set the matching value in the structure passed in the ioSearchInfo1 field. For values that match against a range (such as dates), set the upper bounds for the range in this structure.
ioSearchTime: On input, the maximum allowed search time. If you pass 0 in this field, no time limit is set.
ioCatPosition: The current catalog position, specified as a CatPositionRec structure. You can use this field, along with the ioSearchTime field, to search a volume in segments. To search a volume in segments, set a time limit for the search in the ioSearchTime field and set the initialize field of the CatPositionRec structure to the location for the start of the search (0 if you wish to start searching at the beginning of the volume). On return, the catalog position will be updated. You can then pass this updated CatPositionRec structure to the next call to PBCatSearchSync to continue searching at the place where you left off.
ioOptBuffer: On input, a pointer to an optional read buffer.
ioOptBufSize: On input, the length of the optional read buffer.

If the catalog file changes between two timed calls to PBCatSearchAsync (that is, when you are using ioSearchTime and ioCatPosition to search a volume in segments and the catalog file changes between searches), PBCatSearchAsync returns a result code of catChangedErr and no matches. Depending on what has changed on the volume, ioCatPosition might be invalid, most likely by a few entries in one direction or another. You can continue the search, but you risk either skipping some entries or reading some twice.

Special Considerations

Not all volumes support the PBCatSearchAsync function. Before you call PBCatSearchAsync to search a particular volume, you should call the PBHGetVolParmsAsync function to determine whether that volume supports PBCatSearchAsync. If the bHasCatSearch bit is set in the vMAttrib field, then the volume supports PBCatSearchAsync.

Even though AFP volumes support PBCatSearchSync, they do not support all of its features that are available on local volumes. These restrictions apply to AFP volumes:

AFP volumes do not use the ioSearchTime field. Current versions of the AppleShare server software search for 1 second or until 4 matches are found. The AppleShare workstation software keeps requesting the appropriate number of matches until the server returns either the number specified in the ioReqMatchCount field or an error.
AFP volumes do not support both logical and physical fork lengths. If you request a search using the length of a fork, the actual minimum length used is the smallest of the values in the logical and physical fields of the ioSearchInfo1 structure and the actual maximum length used is the largest of the values in the logical and physical fields of the ioSearchInfo2 structure.
The fsSBNegate bit of the ioSearchBits field is ignored during searches of remote volumes that support AFP version 2.1.
If the AFP server returns afpCatalogChanged, the catalog position structure returned to your application (in the ioCatPosition field) is the same one you passed to PBCatSearchAsync. You should clear the initialize field of that structure to restart the search from the beginning.

Availability

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

Declared In

Files.h

PBCatSearchSync

Searches a volume’s catalog file using a set of search criteria that you specify. (Deprecated in Mac OS X v10.4. Use PBCatalogSearchSync instead.)

OSErr PBCatSearchSync (
   CSParamPtr paramBlock
);

Parameters

paramBlock: A pointer to a CSParam 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.” When PBCatSearchSync has searched the entire volume, it returns eofErr. If it exits because it either spends the maximum time allowed in the ioSearchTime field or finds the maximum number of matches allowed in the ioReqMatchCount field, it returns noErr.

Discussion

The relevant fields of the parameter block are:

ioNamePtr: On input, a pointer to the name of the volume to search.
ioVRefNum: On input, a volume reference number or drive number for the volume to search; or 0 for the default volume.
ioMatchPtr: On input, a pointer to an array of FSSpec structure to hold the matches found by this function. On return, the FSSpec structures in this array identify the files and directories that match the criteria.
ioReqMatchCount: On input, the maximum number of matches to return.
ioActMatchCount: On output, the actual number of matches returned.
ioSearchBits: On input, a bitmap specifying the fields in the criteria structures to match against. See “Catalog Search Masks” for a description of the bits in this field.
ioSearchInfo1: On input, a pointer to a CInfoPBRec union containing search information. For values that match by mask and value (Finder information, for example), set the bits in the structure passed in ioSearchInfo2, and set the matching value in this structure. For values that match against a range (such as dates), set the lower bounds for the range in this structure.
ioSearchInfo2: On input, a pointer to a CInfoPBRec union containing search information. For values that match by mask and value (Finder information, for example), set the bits in this structure, and set the matching value in the structure passed in the ioSearchInfo1 field. For values that match against a range (such as dates), set the upper bounds for the range in this structure.
ioSearchTime: On input, the maximum allowed search time. If you pass 0 in this field, no time limit is set.
ioCatPosition: The current catalog position, specified as a CatPositionRec structure. You can use this field, along with the ioSearchTime field, to search a volume in segments. To search a volume in segments, set a time limit for the search in the ioSearchTime field and set the initialize field of the CatPositionRec structure to the location for the start of the search (0 if you wish to start searching at the beginning of the volume). On return, the catalog position will be updated. You can then pass this updated CatPositionRec structure to the next call to PBCatSearchSync to continue searching at the place where you left off.
ioOptBuffer: On input, a pointer to an optional read buffer.
ioOptBufSize: On input, the length of the optional read buffer.

If the catalog file changes between two timed calls to PBCatSearchSync (that is, when you are using ioSearchTime and ioCatPosition to search a volume in segments and the catalog file changes between searches), PBCatSearchSync returns a result code of catChangedErr and no matches. Depending on what has changed on the volume, ioCatPosition might be invalid, most likely by a few entries in one direction or another. You can continue the search, but you risk either skipping some entries or reading some twice.

Special Considerations

Not all volumes support the PBCatSearchSync function. Before you call PBCatSearchSync to search a particular volume, you should call the PBHGetVolParmsSync function to determine whether that volume supports PBCatSearchSync.If the bHasCatSearch bit is set in the vMAttrib field, then the volume supports PBCatSearchSync.

Even though AFP volumes support PBCatSearchSync, they do not support all of its features that are available on local volumes. These restrictions apply to AFP volumes:

AFP volumes do not use the ioSearchTime field. Current versions of the AppleShare server software search for 1 second or until 4 matches are found. The AppleShare workstation software keeps requesting the appropriate number of matches until the server returns either the number specified in the ioReqMatchCount field or an error.
AFP volumes do not support both logical and physical fork lengths. If you request a search using the length of a fork, the actual minimum length used is the smallest of the values in the logical and physical fields of the ioSearchInfo1 structure and the actual maximum length used is the largest of the values in the logical and physical fields of the ioSearchInfo2 structure.
The fsSBNegate bit of the ioSearchBits field is ignored during searches of remote volumes that support AFP version 2.1.
If the AFP server returns afpCatalogChanged, the catalog position structure returned to your application (in the ioCatPosition field) is the same one you passed to PBCatSearchSync. You should clear the initialize field of that structure to restart the search from the beginning.

Availability

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

Declared In

Files.h

PBDirCreateAsync

Creates a new directory. (Deprecated in Mac OS X v10.4. Use PBCreateDirectoryUnicodeAsync instead.)

OSErr PBDirCreateAsync (
   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 for the new directory.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioDirID: On input, the parent directory ID. If the parent directory ID is 0 and the volume specified in the ioVRefNum field is the default volume, the new directory is placed in the default directory of the volume. If the parent directory ID is 0 and the volume specified in the ioVRefNum field is a volume other than the default volume, the new directory is placed in the root directory of the volume. To create a directory at the root of a volume, regardless of whether that volume is the current default volume, pass the constant fsRtDirID (2) in this field. On output, the directory ID of the new directory. Note that a directory ID, unlike a volume reference number, is a long integer.

The PBDirCreateAsync function is identical to PBHCreateAsync except that it creates a new directory instead of a file. The date and time of the directory’s creation and last modification are set to the current date and time.

Availability

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

Declared In

Files.h

PBDirCreateSync

Creates a new directory. (Deprecated in Mac OS X v10.4. Use PBCreateDirectoryUnicodeSync instead.)

OSErr PBDirCreateSync (
   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 for the new directory.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioDirID: On input, the parent directory ID. If the parent directory ID is 0 and the volume specified in the ioVRefNum field is the default volume, the new directory is placed in the default directory of the volume. If the parent directory ID is 0 and the volume specified in the ioVRefNum field is a volume other than the default volume, the new directory is placed in the root directory of the volume. To create a directory at the root of a volume, regardless of whether that volume is the current default volume, pass the constant fsRtDirID (2) in this field. On output, the directory ID of the new directory. Note that a directory ID, unlike a volume reference number, is a long integer.

The PBDirCreateSync function is identical to PBHCreateSync except that it creates a new directory instead of a file. The date and time of the directory’s creation and last modification are set to the current date and time.

Availability

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

Declared In

Files.h

PBDTAddAPPLAsync

Adds an application to the desktop database. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTAddAPPLSync

Adds an application to the desktop database. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTAddIconAsync

Adds an icon definition to the desktop database. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTAddIconSync

Adds an icon definition to the desktop database. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTCloseDown

Closes the desktop database, though your application should never do this itself. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTDeleteAsync

Removes the desktop database. Unless you are manipulating the desktop database in the absence of the Finder, you should never use this function. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTDeleteSync

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.

Availability

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

Declared In

Files.h

PBDTFlushAsync

Saves your changes to the desktop database. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTFlushSync

Saves your changes to the desktop database. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTGetAPPLAsync

Identifies the application that can open a file with a given creator. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTGetAPPLSync

Identifies the application that can open a file with a given creator. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTGetCommentAsync

Retrieves the user comments for a file or directory. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTGetCommentSync

Retrieves the user comments for a file or directory. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTGetIconAsync

Retrieves an icon definition. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTGetIconInfoAsync

Retrieves an icon type and the associated file type supported by a given creator in the desktop database. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTGetIconInfoSync

Retrieves an icon type and the associated file type supported by a given creator in the desktop database. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

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.

Availability

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

Declared In

Files.h

PBDTGetIconSync

Retrieves an icon definition. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTGetInfoAsync

Determines information about the location and size of the desktop database on a particular volume. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTGetInfoSync

Determines information about the location and size of the desktop database on a particular volume. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTGetPath

Gets the reference number of the specified desktop database. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTOpenInform

Gets the reference number of the specified desktop database, reporting whether the desktop database was empty when it was opened. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTRemoveAPPLAsync

Removes an application from the desktop database. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTRemoveAPPLSync

Removes an application from the desktop database. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTRemoveCommentAsync

Removes a user comment associated with a file or directory from the desktop database. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTRemoveCommentSync

Removes a user comment associated with a file or directory from the desktop database. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTResetAsync

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. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTResetSync

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.

Availability

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

Declared In

Files.h

PBDTSetCommentAsync

Adds a user comment for a file or a directory to the desktop database. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBDTSetCommentSync

Adds a user comment for a file or a directory to the desktop database. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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.

Availability

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

Declared In

Files.h

PBExchangeFilesAsync

Exchanges the data stored in two files on the same volume. (Deprecated in Mac OS X v10.4. Use PBExchangeObjectsAsync instead.)

OSErr PBExchangeFilesAsync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the FIDParam 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 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 first file to swap.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioDestNamePtr: On input, a pointer to the name of the second file to swap.
ioDestDirID: On input, the second file’s parent directory ID.
ioSrcDirID: On input, the first file’s parent directory ID.

Typically, you use PBExchangeFilesAsync after creating a new file during a safe save. The PBExchangeFilesAsync function changes the fields in the catalog entries that record the location of the data and the modification dates. It swaps both the data forks and the resource forks.

The PBExchangeFilesAsync function works on either open or closed files. PBExchangeFilesAsync swaps the data in two files by changing some of the information in the volume catalog. If either file is open, PBExchangeFilesAsync updates any file control blocks associated with the file. Exchanging the contents of two files requires essentially the same access privileges as opening both files for writing.

The following fields in the catalog entries for the files are exchanged:

ioFlStBlk
ioFlLgLen
ioFlPyLen
ioFlRStBlk
ioFlRLgLen
ioFlRPyLen
ioFlMdDat

In the file control blocks, the fcbFlNum, fcbDirID, and fcbCName fields are exchanged.

You should use PBExchangeFilesAsync to preserve the file ID when updating an existing file, in case the file is being tracked through its file ID. The PBExchangeFilesAsync function does not require that file ID references exist for the files being exchanged.

Special Considerations

Your application will have to swap any open reference numbers to the two files because the file's name and parent directory ID are exchanged in the file control blocks.

Because other programs may have access paths open to one or both of the files exchanged, your application should have exclusive read/write access permission (fsRdWrPerm) to both files before calling PBExchangeFilesAsync. Exclusive read/write access to both files will ensure that PBExchangeFilesAsync doesn't affect another application because it prevents other applications from obtaining write access to one or both of the files exchanged.

PBExchangeFilesAsync does not respect the file-locked attribute; it will perform the exchange even if one or both of the files are locked. Obtaining exclusive read/write access to both files before calling PBExchangeFilesAsync ensures that the files are unlocked because locked files cannot be opened with write access.

Availability

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

Declared In

Files.h

PBExchangeFilesSync

Exchanges the data stored in two files on the same volume. (Deprecated in Mac OS X v10.4. Use PBExchangeObjectsSync instead.)

OSErr PBExchangeFilesSync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the FIDParam 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 first file to swap.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioDestNamePtr: On input, a pointer to the name of the second file to swap.
ioDestDirID: On input, the second file’s parent directory ID.
ioSrcDirID: On input, the first file’s parent directory ID.

Typically, you use PBExchangeFilesSync after creating a new file during a safe save. The PBExchangeFilesSync function changes the fields in the catalog entries that record the location of the data and the modification dates. It swaps both the data forks and the resource forks.

The PBExchangeFilesSync function works on either open or closed files. PBExchangeFilesSync swaps the data in two files by changing some of the information in the volume catalog. If either file is open, PBExchangeFilesSync updates any file control blocks associated with the file. Exchanging the contents of two files requires essentially the same access privileges as opening both files for writing.

The following fields in the catalog entries for the files are exchanged:

ioFlStBlk
ioFlLgLen
ioFlPyLen
ioFlRStBlk
ioFlRLgLen
ioFlRPyLen
ioFlMdDat

In the file control blocks, the fcbFlNum, fcbDirID, and fcbCName fields are exchanged.

You should use PBExchangeFilesSync to preserve the file ID when updating an existing file, in case the file is being tracked through its file ID. The PBExchangeFilesSync function does not require that file ID references exist for the files being exchanged.

Special Considerations

Your application will have to swap any open reference numbers to the two files because the file's name and parent directory ID are exchanged in the file control blocks.

Because other programs may have access paths open to one or both of the files exchanged, your application should have exclusive read/write access permission (fsRdWrPerm) to both files before calling PBExchangeFilesSync. Exclusive read/write access to both files will ensure that PBExchangeFilesSync doesn't affect another application because it prevents other applications from obtaining write access to one or both of the files exchanged.

PBExchangeFilesSync does not respect the file-locked attribute; it will perform the exchange even if one or both of the files are locked. Obtaining exclusive read/write access to both files before calling PBExchangeFilesSync ensures that the files are unlocked because locked files cannot be opened with write access.

Availability

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

Declared In

Files.h

PBFlushFileAsync

Writes the contents of a file’s access path buffer to the disk. (Deprecated in Mac OS X v10.4. Use PBFlushForkAsync instead.)

OSErr PBFlushFileAsync (
   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 flush.

After writing the contents of the file to the volume, the PBFlushFileAsync function updates the file’s entry in the volume catalog.

In the event of a system crash, all cached data not yet written to disk is lost. If you have made changes to space that already exists within a file (you are overwriting existing data before the file’s end-of-file), you must use PBFlushFileAsync to ensure that everything written to the file will be written to disk. If you flush the fork’s cached blocks using PBFlushFileAsync, the only possible data loss in a system crash will be the file’s modification date.

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

PBFlushFileSync flushes an open fork’s dirty cached blocks, but may not flush catalog information associated with the file. To flush catalog information, call FlushVol , or one of the related parameter block calls, PBFlushVolSync and PBFlushVolAsync.

To update a file larger than 2GB, or a named fork other than the data and resource forks, you must use the FSFlushFork function, or one of the corresponding parameter block calls, PBFlushForkSync and PBFlushForkAsync.

Special Considerations

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

Availability

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

Declared In

Files.h

PBFlushFileSync

Writes the contents of a file’s access path buffer to the disk. (Deprecated in Mac OS X v10.4. Use PBFlushForkSync instead.)

OSErr PBFlushFileSync (
   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 field of the parameter block is:

ioRefNum: On input, a file reference number for the file to flush.

After writing the contents of the file to the volume, the PBFlushFileSync function updates the file’s entry in the volume catalog.

In the event of a system crash, all cached data not yet written to disk is lost. If you have made changes to space that already exists within a file (you are overwriting existing data before the file’s end-of-file), you must use PBFlushFileSync to ensure that everything written to the file will be written to disk. If you flush the fork’s cached blocks using PBFlushFileSync, the only possible data loss in a system crash will be the file’s modification date.

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

Special Considerations

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

Availability

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

Declared In

Files.h

PBGetCatInfoAsync

Returns catalog information about a file or directory. (Deprecated in Mac OS X v10.4. Use PBGetCatalogInfoAsync instead.)

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.

Availability

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

Declared In

Files.h

PBGetCatInfoSync

Returns catalog information about a file or directory. (Deprecated in Mac OS X v10.4. Use PBGetCatalogInfoSync instead.)

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.

Availability

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

Declared In

Files.h

PBGetEOFAsync

Determines the current logical size of an open file. (Deprecated in Mac OS X v10.4. Use PBGetForkSizeAsync instead.)

OSErr PBGetEOFAsync (
   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.
ioMisc: On output, the logical size (the logical end-of-file) of the given file. Because the ioMisc field is of type Ptr, you’ll need to coerce the value to a long integer to interpret the value correctly.

Availability

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

Declared In

Files.h

PBGetEOFSync

Determines the current logical size of an open file. (Deprecated in Mac OS X v10.4. Use PBGetForkSizeSync instead.)

OSErr PBGetEOFSync (
   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.
ioMisc: On output, a pointer to the logical size (the logical end-of-file) of the given file. Because the ioMisc field is of type Ptr, you’ll need to coerce the value to a long integer to interpret the value correctly.

Availability

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

Declared In

Files.h

PBGetFCBInfoAsync

Gets information about an open file from the file control block. (Deprecated in Mac OS X v10.4. Use PBGetForkCBInfoAsync instead.)

OSErr PBGetFCBInfoAsync (
   FCBPBPtr paramBlock
);

Parameters

paramBlock: A pointer to a file control block parameter block. See FCBPBRec for a description of the FCBPBRec 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. You should pass a pointer to a Str31 value if you want the name of the file returned. If you pass NULL, no filename is returned. On output, if PBGetFCBInfoAsync executes successfully, a pointer to the name of the specified open file.
ioVRefNum: On input, a volume specification. If you specify a valid index number in the ioFCBIndx field, the File Manager returns information on the file having that index in the FCB buffer on the volume specified in this field. This field may contain a drive number or volume reference number. If the value of ioVRefNum is 0, all open files are indexed; otherwise, only open files on the specified volume are indexed.
ioRefNum: On input, if the ioFCBIndx field is 0, the file reference number of the file to get information about. If the value of ioFCBIndx is positive, the ioRefNum field is ignored on input and contains the file reference number on output.
ioFCBIndx: On input, an index. If the value of ioFCBIndx is positive, the File Manager returns information about the file whose index in the FCB buffer is ioFCBIndx and that is located on the volume specified in the ioVRefNum field. If the value of ioFCBIndx is 0, the File Manager returns information about the file whose file reference number is specified by the ioRefNum field.
ioFCBFlNm: On output, the file ID.
ioFCBFlags: On output, file status flags. See “FCB Flags” for a description of the bits in this field.
ioFCBStBlk: On output, the first allocation block of the file.
ioFCBEOF: On output, the logical size (the logical end-of-file) of the file.
ioFCBPLen: On output, the physical size (the physical end-of-file) of the file.
ioFCBCrPs: On output, the position of the file mark.
ioFCBVRefNum: On output, the volume reference number.
ioFCBClpSiz: On output, the file clump size.
ioFCBParID: On output, the directory ID of the file’s parent directory.

To get information about a fork control block, use one of the functions, FSGetForkCBInfo , PBGetForkCBInfoSync , or PBGetForkCBInfoAsync.

Special Considerations

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

Availability

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

Declared In

Files.h

PBGetFCBInfoSync

Gets information about an open file from the file control block. (Deprecated in Mac OS X v10.4. Use PBGetForkCBInfoSync instead.)

OSErr PBGetFCBInfoSync (
   FCBPBPtr paramBlock
);

Parameters

paramBlock: A pointer to a file control block parameter block. See FCBPBRec for a description of the FCBPBRec 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. You should pass a pointer to a Str31 value if you want the name of the file returned. If you pass NULL, no filename is returned. On output, if PBGetFCBInfoSync executes successfully, a pointer to the name of the specified open file.
ioVRefNum: On input, a volume specification. If you specify a valid index number in the ioFCBIndx field, the File Manager returns information on the file having that index in the FCB buffer on the volume specified in this field. This field may contain a drive number or volume reference number. If the value of ioVRefNum is 0, all open files are indexed; otherwise, only open files on the specified volume are indexed.
ioRefNum: On input, if the ioFCBIndx field is 0, the file reference number of the file to get information about. If the value of ioFCBIndx is positive, the ioRefNum field is ignored on input and contains the file reference number on output.
ioFCBIndx: On input, an index. If the value of ioFCBIndx is positive, the File Manager returns information about the file whose index in the FCB buffer is ioFCBIndx and that is located on the volume specified in the ioVRefNum field. If the value of ioFCBIndx is 0, the File Manager returns information about the file whose file reference number is specified by the ioRefNum field.
ioFCBFlNm: On output, the file ID.
ioFCBFlags: On output, file status flags. See “FCB Flags” for a description of the bits in this field.
ioFCBStBlk: On output, the first allocation block of the file.
ioFCBEOF: On output, the logical size (the logical end-of-file) of the file.
ioFCBPLen: On output, the physical size (the physical end-of-file) of the file.
ioFCBCrPs: On output, the current position of the file mark.
ioFCBVRefNum: On output, the volume reference number.
ioFCBClpSiz: On output, the file clump size.
ioFCBParID: On output, the directory ID of the file’s parent directory.

To get information about a fork control block, use one of the functions, FSGetForkCBInfo , PBGetForkCBInfoSync , or PBGetForkCBInfoAsync.

Special Considerations

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

Availability

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

Declared In

Files.h

PBGetForeignPrivsAsync

Determines the native access-control information for a file or directory stored on a volume managed by a foreign file system. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr PBGetForeignPrivsAsync (
   HParmBlkPtr paramBlock
);

Special Considerations

This function is not implemented in Mac OS X.

Availability

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

Declared In

Files.h

PBGetForeignPrivsSync

Determines the native access-control information for a file or directory stored on a volume managed by a foreign file system. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr PBGetForeignPrivsSync (
   HParmBlkPtr paramBlock
);

Special Considerations

This function is not implemented in Mac OS X.

Availability

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

Declared In

Files.h

PBGetFPosAsync

Returns the current position of the file mark. (Deprecated in Mac OS X v10.4. Use PBGetForkPositionAsync instead.)

OSErr PBGetFPosAsync (
   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 about completion routines, see IOCompletionProcPtr.
ioResult: On output, the result code of the function.
ioRefNum: On input, the file reference number of an open file.
ioPosOffset: On output, the current position of the mark. The value returned in ioPosOffset is zero-based. Thus, a call to PBGetFPosAsync returns 0 if you call it when the file mark is positioned at the beginning of the file. The ioReqCount, ioActCount, and ioPosMode fields of the parameter block are all set to 0 on output. To determine the current position of a named fork, or of a fork larger than 2GB, use the FSGetForkPosition function, or one of the corresponding parameter block calls, PBGetForkPositionSync and PBGetForkPositionAsync.

Availability

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

Declared In

Files.h

PBGetFPosSync

Returns the current position of the file mark. (Deprecated in Mac OS X v10.4. Use PBGetForkPositionSync instead.)

OSErr PBGetFPosSync (
   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, the file reference number of an open file.
ioPosOffset: On output, the current position of the mark. The value returned in ioPosOffset is zero-based. Thus, a call to PBGetFPosSync returns 0 if you call it when the file mark is positioned at the beginning of the file.

The ioReqCount, ioActCount, and ioPosMode fields of the parameter block are all set to 0 on output.

Availability

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

Declared In

Files.h

PBGetUGEntryAsync

Gets a user or group entry from the list of User and Group names and IDs on the local file server. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr PBGetUGEntryAsync (
   HParmBlkPtr paramBlock
);

Special Considerations

This function is not implemented in Mac OS X.

Availability

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

Declared In

Files.h

PBGetUGEntrySync

Gets a user or group entry from the list of User and Group names and IDs on a local file server. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr PBGetUGEntrySync (
   HParmBlkPtr paramBlock
);

Special Considerations

This function is not implemented in Mac OS X.

Availability

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

Declared In

Files.h

PBGetXCatInfoAsync

Returns the short name (MS-DOS format name) and the ProDOS information for a file or directory. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr PBGetXCatInfoAsync (
   XCInfoPBPtr paramBlock
);

Special Considerations

This function is not implemented in Mac OS X.

Availability

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

Declared In

Files.h

PBGetXCatInfoSync

Returns the short name (MS-DOS format name) and the ProDOS information for a file or directory. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr PBGetXCatInfoSync (
   XCInfoPBPtr paramBlock
);

Special Considerations

This function is not implemented in Mac OS X.

Availability

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

Declared In

Files.h

PBHCreateAsync

Creates a new file. (Deprecated in Mac OS X v10.4. Use PBCreateFileUnicodeAsync instead.)

OSErr PBHCreateAsync (
   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 functions, see IOCompletionProcPtr.
ioResult: On output, the result code of the function.
ioNamePtr: On input, a pointer to the name for the new file.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioDirID: On input, the directory ID of the parent directory of the new 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.

The PBHCreateAsync function creates both forks of the file the new file is unlocked and empty. The date and time of its creation and last modification are set to the current date and time. If the file created isn’t temporary (that is, if it will exist after the user quits the application), the application should call PBHSetFInfoAsync , after the call to PBHCreateAsync, to fill in the information needed by the Finder.

Files created using PBHCreateAsync are not automatically opened. If you want to write data to the new file, you must first open the file using one of the file access functions, FSpOpenDF , HOpenDF , PBHOpenDFSync or PBHOpenDFAsync.

The resource fork of the new file exists but is empty. You’ll need to call one of the Resource Manager procedures HCreateResFile or FSpCreateResFile to create a resource map in the file before you can open it (by calling one of the Resource Manager functions HOpenResFile or FSpOpenResFile).

To create a file with a Unicode filename, use the function FSCreateFileUnicode , or one of the corresponding parameter block calls, PBCreateFileUnicodeSync and PBCreateFileUnicodeAsync.

Availability

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

Declared In

Files.h

PBHCreateSync

Creates a new file. (Deprecated in Mac OS X v10.4. Use PBCreateFileUnicodeSync instead.)

OSErr PBHCreateSync (
   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 for the new file.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioDirID: On input, the directory ID of the parent directory of the new 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.

The PBHCreateSync function creates both the data and resource fork of the file the new file is unlocked and empty. The date and time of its creation and last modification are set to the current date and time. If the file created isn’t temporary (that is, if it will exist after the user quits the application), the application should call PBHSetFInfoSync after the call to PBHCreateSync to fill in the information needed by the Finder.

Files created using PBHCreateSync are not automatically opened. If you want to write data to the new file, you must first open the file using one of the file access functions, FSpOpenDF , HOpenDF , PBHOpenDFSync or PBHOpenDFAsync.

To create a file with a Unicode filename, use the function FSCreateFileUnicode , or one of the corresponding parameter block calls, PBCreateFileUnicodeSync and PBCreateFileUnicodeAsync.

Availability

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

Declared In

Files.h

PBHDeleteAsync

Deletes a file or directory. (Deprecated in Mac OS X v10.4. Use PBDeleteObjectAsync instead.)

OSErr PBHDeleteAsync (
   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. If you attempt to delete an open file or a non-empty directory, PBHDeleteAsync returns the result code fBsyErr. PBHDeleteAsync also returns fBsyErr if you attempt to delete a directory that has an open working directory associated with it.
ioNamePtr: On input, a pointer to the name of the file or directory to delete.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioDirID: On input, the directory ID of the parent directory of the file or directory to delete.
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.

If the specified target is a file, both the data and the resource fork of the file are deleted. In addition, if a file ID reference for the specified file exists, that file ID reference is also removed. A file must be closed before you can delete it. Similarly, you cannot delete a directory unless it’s empty.

Availability

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

Declared In

Files.h

PBHDeleteSync

Deletes a file or directory. (Deprecated in Mac OS X v10.4. Use PBDeleteObjectSync instead.)

OSErr PBHDeleteSync (
   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.” If you attempt to delete an open file or a non-empty directory, PBHDeleteSync returns the result code fBsyErr. PBHDeleteSync also returns fBsyErr if you attempt to delete a directory that has an open working directory associated with it.

Discussion

The relevant fields of the parameter block are:

ioNamePtr: On input, a pointer to the name of the file or directory to delete.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioDirID: On input, the directory ID of the parent directory of the file or directory to delete.
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.

Availability

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

Declared In

Files.h

PBHGetFInfoAsync

Obtains information about a file. (Deprecated in Mac OS X v10.4. Use PBGetCatalogInfoAsync instead.)

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.

Availability

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

Declared In

Files.h

PBHGetFInfoSync

Obtains information about a file. (Deprecated in Mac OS X v10.4. Use PBGetCatalogInfoSync instead.)

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.

Availability

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

Declared In

Files.h

PBHGetLogInInfoAsync

Determines the login method used to log on to a particular shared volume. (Deprecated in Mac OS X v10.4. There is no replacement function.)

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 Mac OS X.

Availability

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

Declared In

Files.h

PBHGetLogInInfoSync

Determines the login method used to log on to a particular shared volume. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr PBHGetLogInInfoSync (
   HParmBlkPtr paramBlock
);

Special Considerations

This function is not implemented in Mac OS X.

Availability

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

Declared In

Files.h

PBHGetVInfoAsync

Gets detailed information about a volume. (Deprecated in Mac OS X v10.4. Use PBGetVolumeInfoAsync instead.)

OSErr PBHGetVInfoAsync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the HVolumeParam 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 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 buffer. If you specify a negative number in the ioVolIndex field, this buffer should hold the name of the volume for which to return information. On output, a pointer to the volume’s name. You should pass a pointer to a Str31 value if you want the name returned. If you pass NULL, no volume name is returned.

ioVRefNum

On input, a volume specification for the volume for which to return information. If the ioVolIndex field is negative, the File Manager uses the value in the ioNamePtr field, along with the value specified in the ioVRefNum field, to determine the volume. If the value in ioVolIndex is 0, the File Manager attempts to access the volume using only the value in this field. On output, the volume reference number.

ioVolIndex

On input, an index used for indexing through all mounted volumes. If this value is positive, the File Manager uses it to find the volume for which to return information. For instance, if the value of ioVolIndex is 2, the File Manager attempts to access the second mounted volume in the VCB queue. If ioVolIndex is negative, the File Manager uses the values in the ioNamePtr and ioVRefNum fields to access the requested volume. If ioVolIndex is 0, the File Manager uses only the value in the ioVRefNum field.

ioVCrDate

On output, the date and time of the volume’s initialization.

ioVLsMod

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

ioVAtrb

On output, the volume attributes. See “Volume Information Attribute Constants” for a description of the volume attributes returned by this function.

ioVNmFls

On output, the number of files in the root directory of the volume. For performance reasons, the Carbon File Manager does not return the number of files in this field; instead, it sets ioVNmFls to 0.To determine the number of files in the root directory of a volume in Carbon, call PBGetCatInfoAsync for the root directory. The number of files in the root directory is returned in the ioDrNmFls field.

ioVBitMap

On output, the first block of the volume bitmap.

ioVAllocPtr

On output, the block at which the search for the next new file allocation should start.

ioVNmAlBlks

On output, the number of allocation blocks on the volume.

ioVAlBlkSiz

On output, the size of the allocation blocks.

ioVClpSiz

On output, the default clump size.

ioAlBlSt

On output, the first block in the volume block map.

ioVNxtCNID

On output, the next unused catalog node ID.

ioVFrBlk

On output, the number of unused allocation blocks.

ioVSigWord

On output, the volume signature. For HFS volumes, this is ‘BD’ for HFS Plus volumes, this is ‘H+’.

ioVDrvInfo

On output, the drive number. You can determine whether the given volume is online by inspecting the value of this field. For online volumes, the ioVDrvInfo field contains the drive number of the drive containing the specified volume and hence is always greater than 0. If the value returned in ioVDrvInfo is 0, the volume is either offline or ejected.

Mac OS X does not support drive numbers; in Mac OS X, the File Manager always returns a value of 1 in this field.

ioVDRefNum

On output, the driver reference number. You can determine whether the volume is offline or ejected by inspecting the value of this field. If the volume is offline, the value of ioVDRefNum is the negative of the drive number (which is cleared when the volume is placed offline; hence the ioVDrvInfo field for an offline volume is zero), and is a negative number. If the volume is ejected, the value of ioVDRefNum is the drive number itself, and thus is a positive number. For online volumes, ioVDRefNum contains a driver reference number; these numbers are always less than 0.

ioVFSID

On output, the file system handling this volume.

ioVBkUp

On output, the date and time of the volume’s last backup.

ioVSeqNum

Used internally.

ioVWrCnt

On output, the volume write count.

ioVFilCnt

On output, the number of files on the volume.

ioVDirCnt

On output, the number of directories on the volume.

ioVFndrInfo

On output, Finder information for the volume.

You can get information about all the online volumes by making repeated calls to PBHGetVInfoAsync, starting with the value of the ioVolIndex field set to 1 and incrementing that value until PBHGetVInfoAsync returns nsvErr.

If you need to obtain information about HFS Plus volumes, you should use the FSGetVolumeInfo function, or one of the corresponding parameter block calls, PBGetVolumeInfoSync and PBGetVolumeInfoAsync. The PBHGetVInfoAsync function is still supported for HFS Plus volumes, but there is additional information returned by the FSGetVolumeInfo function (such as the date and time that the volume was last checked for consistency).

Special Considerations

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

If the value of ioVolIndex is negative, the File Manager uses ioNamePtr and ioVRefNum in the standard way to determine the volume. However, because PBHGetVInfoAsync returns the volume name in the buffer whose address you passed in ioNamePtr, your input pathname will be modified. If you don't want your input pathname modified, make a copy of it and pass the copy to PBHGetVInfoAsync.

The volume name returned by PBHGetVInfoAsync is not a full pathname to the volume because it does not contain a colon.

For compatibility with older programs, some values returned by PBHGetVInfoAsync are not what is stored in the volume's Volume Control Block (VCB). Specifically:

ioVNmAlBlks and ioVFrBlk are pinned to values which, when multiplied by ioVAlBlkSiz, are always less than 2 Gigabytes.
ioVNmAlBlks may not include the allocation blocks used by the catalog and extents overflow files.
$4244 is returned in ioVSigWord for both HFS and HFS Plus volumes.

For unpinned total and free byte counts, and for the real ioVSigWord, use PBXGetVolInfoAsync instead of PBHGetVInfoAsync.

Version Notes

In non-Carbon applications, you may pass a working directory reference in the ioVRefNum field; if you pass a working directory reference in that field, the number of files and directories in the specified directory is returned in the ioVNmFls field.

Availability

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

Declared In

Files.h

PBHGetVInfoSync

Gets detailed information about a volume. (Deprecated in Mac OS X v10.4. Use PBGetVolumeInfoSync instead.)

OSErr PBHGetVInfoSync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the HVolumeParam 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

ioVRefNum

On input, a volume reference number or drive number for the volume for which to return information; or 0 for the default volume. If the ioVolIndex field is negative, the File Manager uses the value in the ioNamePtr field, along with the value specified in the ioVRefNum field, to determine the volume. If the value in ioVolIndex is 0, the File Manager attempts to access the volume using only the value in this field. On output, the volume reference number.

ioVolIndex

ioVCrDate

On output, the date and time of the volume’s initialization.

ioVLsMod

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

ioVAtrb

On output, the volume attributes. See “Volume Information Attribute Constants” for a description of the volume attributes returned by this function.

ioVNmFls

On output, the number of files in the root directory of the volume. For performance reasons, the Carbon File Manager does not return the number of files in this field; instead, it sets ioVNmFls to 0.To determine the number of files in the root directory of a volume in Carbon, call PBGetCatInfoSync for the root directory. The number of files in the root directory is returned in the ioDrNmFls field.

ioVBitMap

On output, the first block of the volume bitmap.

ioVAllocPtr

On output, the block at which the search for the next new file allocation should start.

ioVNmAlBlks

On output, the number of allocation blocks on the volume.

ioVAlBlkSiz

On output, the size of the allocation blocks.

ioVClpSiz

On output, the default clump size.

ioAlBlSt

On output, the first block in the volume block map.

ioVNxtCNID

On output, the next unused catalog node ID.

ioVFrBlk

On output, the number of unused allocation blocks.

ioVSigWord

On output, the volume signature. For HFS volumes, this is ‘BD’ for HFS Plus volumes, this is ‘H+’.

ioVDrvInfo

Mac OS X does not support drive numbers; in Mac OS X, the File Manager always returns a value of 1 in this field.

ioVDRefNum

ioVFSID

On output, the file system handling this volume.

ioVBkUp

On output, the date and time of the volume’s last backup.

ioVSeqNum

Used internally.

ioVWrCnt

On output, the volume write count.

ioVFilCnt

On output, the number of files on the volume.

ioVDirCnt

On output, the number of directories on the volume.

ioVFndrInfo

On output, Finder information for the volume.

You can get information about all the online volumes by making repeated calls to PBHGetVInfoSync, starting with the value of the ioVolIndex field set to 1 and incrementing that value until PBHGetVInfoSync returns nsvErr.

If you need to obtain information about HFS Plus volumes, you should use the FSGetVolumeInfo function, or one of the corresponding parameter block calls, PBGetVolumeInfoSync and PBGetVolumeInfoAsync. The PBHGetVInfoSync function is still supported for HFS Plus volumes, but there is additional information returned by the FSGetVolumeInfo function (such as the date and time that the volume was last checked for consistency).

Special Considerations

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

If the value of ioVolIndex is negative, the File Manager uses ioNamePtr and ioVRefNum in the standard way to determine the volume. However, because PBHGetVInfoSync returns the volume name in the buffer whose address you passed in ioNamePtr, your input pathname will be modified. If you don't want your input pathname modified, make a copy of it and pass the copy to PBHGetVInfoSync.

The volume name returned by PBHGetVInfoSync is not a full pathname to the volume because it does not contain a colon.

For compatibility with older programs, some values returned by PBHGetVInfoSync are not what is stored in the volume's Volume Control Block (VCB). Specifically:

ioVNmAlBlks and ioVFrBlk are pinned to values which, when multiplied by ioVAlBlkSiz, are always less than 2 Gigabytes.
ioVNmAlBlks may not include the allocation blocks used by the catalog and extents overflow files.
$4244 is returned in ioVSigWord for both HFS and HFS Plus volumes.

For unpinned total and free byte counts, and for the real ioVSigWord, use PBXGetVolInfoSync instead of PBHGetVInfoSync.

Version Notes

Availability

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

Declared In

Files.h

PBHGetVolAsync

Determines the default volume and default directory. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr PBHGetVolAsync (
   WDPBPtr paramBlock
);

Parameters

paramBlock: A pointer to a working directory parameter block. See WDPBRec for a description of the WDPBRec data type.

Return Value

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

Discussion

The PBHGetVolAsync function returns the default volume and directory last set by a call to HSetVol or PBHSetVolSync. 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 output, a pointer to the default volume’s name. You should pass a pointer to a Str31 value if you want that name returned. If you pass NULL in this field, no volume name is returned.
ioVRefNum: On output, the volume reference number of the default volume.
ioWDProcID: On output, the working directory user identifier.
ioWDVRefNum: On output, the volume reference number of the volume on which the default directory exists.
ioWDDirID: On output, the directory ID of the default directory.

Version Notes

When CarbonLib is not present, the PBHGetVolAsync function returns a working directory reference number in the ioVRefNum parameter if the previous call to HSetVol (or one of the corresponding parameter block calls) passed in a working directory reference number.

Availability

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

Declared In

Files.h

PBHGetVolSync

Determines the default volume and default directory. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr PBHGetVolSync (
   WDPBPtr paramBlock
);

Parameters

paramBlock: A pointer to a working directory parameter block. See WDPBRec for a description of the WDPBRec data type.

Return Value

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

Discussion

The PBHGetVolSync function returns the default volume and directory last set by a call to HSetVol or PBHSetVolSync. The relevant fields of the parameter block are:

ioNamePtr: On output, a pointer to the default volume’s name. Pass a pointer to a Str31 value if you want that name returned. If you pass NULL in this field, no volume name is returned.
ioVRefNum: On output, the volume reference number of the default volume.
ioWDProcID: On output, the working directory user identifier.
ioWDVRefNum: On output, the volume reference number of the volume on which the default directory exists.
ioWDDirID: On output, the directory ID of the default directory.

Version Notes

When CarbonLib is not present, the PBHGetVolSync function returns a working directory reference number in the ioVRefNum parameter if the previous call to HSetVol (or one of the corresponding parameter block calls) passed in a working directory reference number.

Availability

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

Declared In

Files.h

PBHMoveRenameAsync

Moves a file or directory and optionally renames it. (Deprecated in Mac OS X v10.4. Use FSMoveObjectAsync instead.)

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 Mac OS X.

Availability

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

Declared In

Files.h

PBHMoveRenameSync

Moves a file or directory and optionally renames it. (Deprecated in Mac OS X v10.4. Use FSMoveObjectSync instead.)

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 Mac OS X.

Availability

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

Declared In

Files.h

PBHOpenAsync

Opens the data fork of a file. (Deprecated in Mac OS X v10.4. Use PBOpenForkAsync instead.)

OSErr PBHOpenAsync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to a basic HFS 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 function. For more information on completion routines, see IOCompletionProcPtr.
ioResult: On output, the result code of the function. If you attempt to open a locked file for writing, PBHOpenAsync returns the result code permErr. If you request exclusive read/write permission but another access path is already open, PBHOpenAsync returns the reference number of the existing access path in ioRefNum and opWrErr as its function result.
ioNamePtr: On input, a pointer to the name of the file.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioRefNum: On output, a file reference number for accessing the open data fork. If you request exclusive read/write permission but another access path is already open, PBHOpenAsync returns the reference number of the existing access path. You should not use this reference number unless your application originally opened the file.
ioPermssn: On input, a constant specifying the type of access with which to open the fork. For a description of the types of access you can request, see “File Access Permission Constants.” You can open a path for writing even if it accesses a file on a locked volume, and no error is returned until a PBWriteAsync, PBSetEOFAsync , or PBAllocateAsync call is made.
ioDirID: On input, the directory ID of the file’s parent directory.
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.

If you use PBHOpenAsync to try to open a file whose name begins with a period, you might mistakenly open a driver instead; subsequent attempts to write data might corrupt data on the target device. To avoid these problems, you should always use PBHOpenDFAsync instead of PBHOpenAsync.

Availability

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

Declared In

Files.h

PBHOpenDFAsync

Opens the data fork of a file. (Deprecated in Mac OS X v10.4. Use PBOpenForkAsync instead.)

OSErr PBHOpenDFAsync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the HIOParam 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

You should use PBHOpenDFAsync instead of the PBHOpenAsync function; PBHOpenDFAsync allows you to safely open a file whose name begins with a period (.).

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. If you attempt to open a locked file for writing, PBHOpenDFAsync returns the result code permErr. If you request exclusive read/write permission but another access path is already open, PBHOpenDFAsync returns the reference number of the existing access path in ioRefNum and opWrErr as its function result.
ioNamePtr: On input, a pointer to the name of the file.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioRefNum: On output, the file reference number for accessing the open data fork. If you request exclusive read/write permission but another access path is already open, PBHOpenDFAsync returns the reference number of the existing access path. You should not use this reference number unless your application originally opened the file.
ioPermssn: On input, a constant specifying the type of access with which to open the fork. For a description of the types of access you can request, see “File Access Permission Constants.” You can open a path for writing even if it accesses a file on a locked volume, and no error is returned until a PBWriteAsync, PBSetEOFAsync , or PBAllocateAsync call is made.
ioDirID: On input, the directory ID of the file’s parent directory.
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.

Note that if you wish to access named forks other than the data and resource forks, or forks larger than 2GB, you will need to use the FSOpenFork function, or one of its corresponding parameter block calls, PBOpenForkSync or PBOpenForkAsync. If you try to open a fork larger than 2GB with the PBHOpenDFAsync function, you will receive an error message.

Availability

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

Declared In

Files.h

PBHOpenDFSync

Opens the data fork of a file. (Deprecated in Mac OS X v10.4. Use PBOpenForkSync instead.)

OSErr PBHOpenDFSync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the HIOParam 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.” . If you attempt to open a locked file for writing, PBHOpenDFSync returns the result code permErr. If you request exclusive read/write permission but another access path is already open, PBHOpenDFSync returns the reference number of the existing access path in ioRefNum and opWrErr as its function result.

Discussion

You should use PBHOpenDFSync instead of the PBHOpenSync function; PBHOpenDFSync allows you to safely open a file whose name begins with a period (.).

The relevant fields of the parameter block are:

ioNamePtr: On input, a pointer to the name of the file.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioRefNum: On output, the file reference number for accessing the open data fork. If you request exclusive read/write permission but another access path is already open, PBHOpenDFSync returns the reference number of the existing access path. You should not use this reference number unless your application originally opened the file.
ioPermssn: On input, a constant specifying the type of access with which to open the fork. For a description of the types of access you can request, see “File Access Permission Constants.” You can open a path for writing even if it accesses a file on a locked volume, and no error is returned until a PBWriteSync, PBSetEOFSync , or PBAllocateSync call is made.
ioDirID: On input, the directory ID of the file’s parent directory.
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.

Note that if you wish to access named forks other than the data and resource forks, or forks larger than 2GB, you will need to use the FSOpenFork function, or one of its corresponding parameter block calls, PBOpenForkSync or PBOpenForkAsync. If you try to open a fork larger than 2GB with the PBHOpenDFSync function, you will receive an error message.

Availability

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

Declared In

Files.h

PBHOpenRFAsync

Opens the resource fork of a file. (Deprecated in Mac OS X v10.4. Use PBOpenForkAsync instead.)

OSErr PBHOpenRFAsync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the HIOParam 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. On some file systems, PBHOpenRFAsync will return the error eofErr if you try to open the resource fork of a file for which no resource fork exists with read-only access.
ioNamePtr: On input, a pointer to the name of the file.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioRefNum: On output, a file reference number for accessing the open resource fork.
ioPermssn: On input, a constant specifying the type of access with which to open the fork. For a description of the types of access you can request, see “File Access Permission Constants.”
ioDirID: On input, the directory ID of the file’s parent directory.
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.

Note that if you wish to access named forks other than the data and resource forks, or forks larger than 2GB, you will need to use the FSOpenFork function, or one of its corresponding parameter block calls, PBOpenForkSync or PBOpenForkAsync. If you try to open a fork larger than 2GB with the PBHOpenRFAsync function, you will receive an error message.

Special Considerations

Generally your application should use Resource Manager functions rather than File Manager functions to access a file’s resource fork. The PBHOpenRFAsync function does not read the resource map into memory and is generally useful only for applications (such as utilities that copy files) that need block-level access to a resource fork.

You should not use the resource fork of a file to hold non-resource data. Many parts of the system software assume that a resource fork always contains resource data.

Because there is no support for locking and unlocking file ranges in Mac OS X, regardless of whether File Sharing is enabled, you cannot open more than one path to a resource fork with read/ write permission. If you try to open a more than one path to a file's resource fork with fsRdWrShPerm permission, only the first attempt will succeed. Subsequent attempts will return an invalid reference number and the ResError function will return the error opWrErr.

Availability

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

Declared In

Files.h

PBHOpenRFSync

Opens the resource fork of a file. (Deprecated in Mac OS X v10.4. Use PBOpenForkSync instead.)

OSErr PBHOpenRFSync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the HIOParam 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.” On some file systems, PBHOpenRFSync will return the error eofErr if you try to open the resource fork of a file for which no resource fork exists with read-only access.

Discussion

The relevant fields of the parameter block are:

ioNamePtr: On input, a pointer to the name of the file.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioRefNum: On output, a file reference number for accessing the open resource fork.
ioPermssn: On input, a constant specifying the type of access with which to open the fork. For a description of the types of access you can request, see “File Access Permission Constants.”
ioDirID: On input, the directory ID of the file’s parent directory.
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.

Note that if you wish to access named forks other than the data and resource forks, or forks larger than 2GB, you will need to use the FSOpenFork function, or one of its corresponding parameter block calls, PBOpenForkSync or PBOpenForkAsync. If you try to open a fork larger than 2GB with the PBOpenRFSync function, you will receive an error message.

Special Considerations

Generally your application should use Resource Manager functions rather than File Manager functions to access a file’s resource fork. The PBHOpenRFSync function does not read the resource map into memory and is generally useful only for applications (such as utilities that copy files) that need block-level access to a resource fork.

You should not use the resource fork of a file to hold non-resource data. Many parts of the system software assume that a resource fork always contains resource data.

Because there is no support for locking and unlocking file ranges on local disks in Mac OS X, regardless of whether File Sharing is enabled, you cannot open more than one path to a resource fork with read/ write permission. If you try to open a more than one path to a file's resource fork with fsRdWrShPerm permission, only the first attempt will succeed. Subsequent attempts will return an invalid reference number and the ResError function will return the error opWrErr.

Availability

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

Declared In

Files.h

PBHOpenSync

Opens the data fork of a file. (Deprecated in Mac OS X v10.4. Use PBOpenForkSync instead.)

OSErr PBHOpenSync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the HIOParam 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.” If you attempt to open a locked file for writing, PBHOpenSync returns the result code permErr. If you request exclusive read/write permission but another access path is already open, PBHOpenSync returns the reference number of the existing access path in ioRefNum and opWrErr as its function result.

Discussion

The relevant fields of the parameter block are:

ioNamePtr: On input, a pointer to the name of the file.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioRefNum: On output, a file reference number for accessing the open data fork. If you request exclusive read/write permission but another access path is already open, PBHOpenSync returns the reference number of the existing access path. You should not use this reference number unless your application originally opened the file.
ioPermssn: On input, a constant specifying the type of access with which to open the fork. For a description of the types of access you can request, see “File Access Permission Constants.” You can open a path for writing even if it accesses a file on a locked volume, and no error is returned until a PBWriteSync, PBSetEOFSync , or PBAllocateSync call is made.
ioDirID: On input, the directory ID of the file’s parent directory.
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.

If you use PBHOpenSync to try to open a file whose name begins with a period, you might mistakenly open a driver instead; subsequent attempts to write data might corrupt data on the target device. To avoid these problems, you should always use PBHOpenDFSync instead of PBHOpenSync.

Availability

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

Declared In

Files.h

PBHRenameAsync

Renames a file, directory, or volume. (Deprecated in Mac OS X v10.4. Use PBRenameUnicodeAsync instead.)

OSErr PBHRenameAsync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the HIOParam 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 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 existing filename, directory name, or volume name.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioMisc: On input, a pointer to the new name for the file, directory or volume.
ioDirID: On input, the parent directory ID of the file or directory to rename.
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.

Given a pointer to the name of a file or directory in the ioNamePtr field, PBHRenameAsync changes it to the name pointed to in the ioMisc field. Given a pointer to a volume name in ioNamePtr or a volume reference number in ioVRefNum, the function changes the name of the volume to the name pointed to in ioMisc.

If a file ID reference exists for the file being renamed, the file ID remains with the file.

To rename a file or directory using a long Unicode name, use the FSRenameUnicode function or one of the corresponding parameter block calls, PBRenameUnicodeSync and PBRenameUnicodeAsync.

Special Considerations

You cannot use PBHRenameAsync to change the directory in which a file is located. To move a file or directory, use the FSpCatMove, PBCatMoveSync, or PBCatMoveAsync functions.

Availability

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

Declared In

Files.h

PBHRenameSync

Renames a file, directory, or volume. (Deprecated in Mac OS X v10.4. Use PBRenameUnicodeSync instead.)

OSErr PBHRenameSync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the HIOParam 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 existing filename, directory name, or volume name.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioMisc: On input, a pointer to the new name for the file, directory or volume.
ioDirID: On input, the parent directory ID of the file or directory to rename.
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.

Given a pointer to the name of a file or directory in the ioNamePtr field, PBHRenameSync changes it to the name pointed to in the ioMisc field. Given a pointer to a volume name in ioNamePtr or a volume reference number in ioVRefNum, the function changes the name of the volume to the name pointed to in ioMisc.

If a file ID reference exists for the file being renamed, the file ID remains with the file.

To rename a file or directory using a long Unicode name, use the FSRenameUnicode function or one of the corresponding parameter block calls, PBRenameUnicodeSync and PBRenameUnicodeAsync.

Special Considerations

You cannot use PBHRenameSync to change the directory in which a file is located. To move a file or directory, use the FSpCatMove, PBCatMoveSync, or PBCatMoveAsync functions.

Availability

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

Declared In

Files.h

PBHRstFLockAsync

Unlocks a file or directory. (Deprecated in Mac OS X v10.4. Use PBSetCatalogInfoAsync instead.)

OSErr PBHRstFLockAsync (
   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 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 for the file or directory o unlock.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioDirID: On input, the parent directory ID of the file or directory to unlock.
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.

If the PBHGetVolParmsSync or PBHGetVolParmsAsync function indicates that the volume supports folder locking (that is, the bHasFolderLock bit of the vMAttrib field is set), you can use PBHRstFLockAsync to unlock a directory. Otherwise, you can only use this function to unlock a file.

Access paths currently in use aren’t affected by this function.

Availability

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

Declared In

Files.h

PBHRstFLockSync

Unlocks a file or directory. (Deprecated in Mac OS X v10.4. Use PBSetCatalogInfoSync instead.)

OSErr PBHRstFLockSync (
   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 for the file or directory to unlock.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioDirID: On input, the parent directory ID of the file or directory to unlock.
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.

If the PBHGetVolParmsSync or PBHGetVolParmsAsync function indicates that the volume supports folder locking (that is, the bHasFolderLock bit of the vMAttrib field is set), you can use PBHRstFLockSync to unlock a directory. Otherwise, you can only use this function to unlock a file.

Access paths currently in use aren’t affected by this function.

Availability

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

Declared In

Files.h

PBHSetFInfoAsync

Sets information for a file. (Deprecated in Mac OS X v10.4. Use PBSetCatalogInfoAsync instead.)

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.

Availability

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

Declared In

Files.h

PBHSetFInfoSync

Sets information for a file. (Deprecated in Mac OS X v10.4. Use PBSetCatalogInfoSync instead.)

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.

Availability

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

Declared In

Files.h

PBHSetFLockAsync

Locks a file or directory. (Deprecated in Mac OS X v10.4. Use PBSetCatalogInfoAsync instead.)

OSErr PBHSetFLockAsync (
   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 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 name for the file or directory to lock.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioDirID: On input, the parent directory ID of the file or directory to lock.
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.

If the PBHGetVolParmsSync or PBHGetVolParmsAsync function indicates that the volume supports folder locking (that is, the bHasFolderLock bit of the vMAttrib field is set), you can use PBHSetFLockAsync to lock a directory. Otherwise, you can only use this function to lock a file.

After you lock a file, all new access paths to that file are read-only. Access paths currently in use aren’t affected.

Availability

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

Declared In

Files.h

PBHSetFLockSync

Locks a file or directory. (Deprecated in Mac OS X v10.4. Use PBSetCatalogInfoSync instead.)

OSErr PBHSetFLockSync (
   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 name for the file or directory to lock.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.
ioDirID: On input, the parent directory ID of the file or directory to lock.
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.

If the PBHGetVolParmsSync or PBHGetVolParmsAsync function indicates that the volume supports folder locking (that is, the bHasFolderLock bit of the vMAttrib field is set), you can use PBHSetFLockSync to lock a directory. Otherwise, you can only use this function to lock a file.

After you lock a file, all new access paths to that file are read-only. Access paths currently in use aren’t affected.

Availability

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

Declared In

Files.h

PBHSetVolAsync

Sets the default volume and the default directory. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr PBHSetVolAsync (
   WDPBPtr paramBlock
);

Parameters

paramBlock: A pointer to a working directory parameter block. See WDPBRec for a description of the WDPBRec 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. If this field specifies a full pathname, the default volume is set to the volume whose name is contained in that pathname. (A full pathname overrides the ioVRefNum field.)If this field contains a partial pathname and the ioVRefNum field specifies a volume reference number, then the default directory is set to the directory having the partial pathname specified here, in the directory given in the ioWDDirID field. If this field is NULL, then the default directory is set to the directory having the ID specified in the ioWDDirID field.
ioVRefNum: On input, a volume reference number for the default volume. This field is ignored if the ioNamePtr field specifies a full pathname.
ioWDDirID: On input, a directory ID. If the ioVRefNum field contains a volume reference number and ioNamePtr contains a partial pathname, this field contains the directory ID of the directory containing the default directory. If ioNamePtr is NULL, this field contains the directory ID of the default directory.

Both the default volume and the default directory are used in calls made with no volume name, a volume reference number of 0, and a directory ID of 0.

Availability

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

Declared In

Files.h

PBHSetVolSync

Sets the default volume and the default directory. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr PBHSetVolSync (
   WDPBPtr paramBlock
);

Parameters

paramBlock: A pointer to a working directory parameter block. See WDPBRec for a description of the WDPBRec 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 this field specifies a full pathname, the default volume is set to the volume whose name is contained in that pathname. (A full pathname overrides the ioVRefNum field.)If this field contains a partial pathname and the ioVRefNum field specifies a volume reference number, then the default directory is set to the directory having the partial pathname specified here, in the directory given in the ioWDDirID field. If this field is NULL, then the default directory is set to the directory having the ID specified in the ioWDDirID field.
ioVRefNum: On input, the volume reference number for the default volume. This field is ignored if the ioNamePtr field specifies a full pathname.
ioWDDirID: On input, a directory ID. If the ioVRefNum field contains a volume reference number and ioNamePtr contains a partial pathname, this field contains the directory ID of the directory containing the default directory. If ioNamePtr is NULL, this field contains the directory ID of the default directory.

Both the default volume and the default directory are used in calls made with no volume name, a volume reference number of 0, and a directory ID of 0.

Availability

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

Declared In

Files.h

PBLockRangeAsync

Locks a portion of a file. (Deprecated in Mac OS X v10.4. Use PBXLockRangeAsync instead.)

OSErr PBLockRangeAsync (
   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. If you call PBLockRangeAsync on a file system that does not implement it—for example, SMB—PBLockRangeAsync returns noErr and does nothing.

ioRefNum

On input, the file reference number of the file owning the range to lock.

ioReqCount

On input, the number of bytes in the range. Set ioReqCount to –1 to lock the maximum number of bytes from the position specified in the ioPosOffset field.

ioPosMode

On input, a constant specifying the base location for the start of the locked range. See “Position Mode Constants” for more information on the constants you can use to specify the base location.

You should not use the fsFromLEOF constant when locking a file range. PBLockRangeAsync does not return the start of the locked range; thus, there is no way to determine what range was actually locked when you specify fsFromLEOF.

ioPosOffset

On input, the offset from the base location specified in the ioPosMode field for the start of the locked range.

The PBLockRangeAsync function locks a portion of a file that was opened with shared read/write permission. The beginning of the range to be locked is determined by the ioPosMode and ioPosOffset fields. The end of the range to be locked is determined by the beginning of the range and the ioReqCount field. For example, to lock the first 50 bytes in a file, set ioReqCount to 50, ioPosMode to fsFromStart, and ioPosOffset to 0.

The PBLockRangeAsync function uses the same parameters as both PBReadAsync and PBWriteAsync; by calling it immediately before PBReadAsync, you can use the information in the parameter block for the PBReadAsync call.

When you’re finished with the data (typically after a call to PBWriteSync), you can call PBUnlockRangeAsync to free that portion of the file for subsequent read and write calls. Closing a file also releases all locked ranges in that file.

Special Considerations

The PBLockRangeAsync function does nothing if the file specified in the ioRefNum field is open with shared read/write permission but is not located on a remote server volume or is not located under a share point on a sharable local volume. To check whether file sharing is currently on, check that the bHasPersonalAccessPrivileges bit in the vMAttrib field of the GetVolParmsInfoBuffer returned by the PBHGetVolParmsSync function is set.

Availability

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

Declared In

Files.h

PBLockRangeSync

Locks a portion of a file. (Deprecated in Mac OS X v10.4. Use PBXLockRangeSync or FSLockRange instead.)

OSErr PBLockRangeSync (
   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.” If you call PBLockRangeSync on a file system that does not implement it—for example, SMB—PBLockRangeSync returns noErr and does nothing.

Discussion

The relevant fields of the parameter block are:

ioRefNum

On input, the file reference number of the file owning the range to lock.

ioReqCount

On input, the number of bytes in the range. Set ioReqCount to –1 to lock the maximum number of bytes from the position specified in the ioPosOffset field.

ioPosMode

On input, a constant specifying the base location for the start of the locked range. See “Position Mode Constants” for more information about the constants you can use to specify the base location.

You should not use the fsFromLEOF constant when locking a file range. PBLockRangeSync does not return the start of the locked range; thus, there is no way to determine what range was actually locked when you specify fsFromLEOF.

ioPosOffset

On input, the offset from the base location specified in the ioPosMode field for the start of the locked range.

The PBLockRangeSync function locks a portion of a file that was opened with shared read/write permission. The beginning of the range to be locked is determined by the ioPosMode and ioPosOffset fields. The end of the range to be locked is determined by the beginning of the range and the ioReqCount field. For example, to lock the first 50 bytes in a file, set ioReqCount to 50, ioPosMode to fsFromStart, and ioPosOffset to 0.

The PBLockRangeSync function uses the same parameters as both PBReadSync and PBWriteSync; by calling it immediately before PBReadSync, you can use the information in the parameter block for the PBReadSync call.

When you’re finished with the data (typically after a call to PBWriteSync), you can call PBUnlockRangeSync to free that portion of the file for subsequent read and write calls. Closing a file also releases all locked ranges in that file.

Special Considerations

The PBLockRangeSync function does nothing if the file specified in the ioRefNum field is open with shared read/write permission but is not located on a remote server volume or is not located under a share point on a sharable local volume. To check whether file sharing is currently on, check that the bHasPersonalAccessPrivileges bit in the vMAttrib field of the GetVolParmsInfoBuffer returned by the PBHGetVolParmsSync function is set.

Availability

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

Declared In

Files.h

PBMakeFSSpecAsync

Creates an FSSpec structure for a file or directory. (Deprecated in Mac OS X v10.4. Use PBMakeFSRefUnicodeAsync instead.)

OSErr PBMakeFSSpecAsync (
   HParmBlkPtr paramBlock
);

Parameters

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

Return Value

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

If the specified volume is mounted and the specified parent directory exists, but the target file or directory doesn’t exist in that location, PBMakeFSSpecAsync fills in the structure and returns fnfErr instead of noErr. The structure is valid, but it describes a target that doesn’t exist. You can use the structure for another operation, such as creating a file.

PBMakeFSSpecAsync can return a number of different File Manager error codes. When PBMakeFSSpecAsync returns any result other than noErr or fnfErr, all fields of the resulting FSSpec structure are set to 0.

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. When PBMakeFSSpecAsync returns any result other than noErr or fnfErr, all fields of the resulting FSSpec structure are set to 0. See “File Manager Result Codes”.
ioNamePtr: On input, a pointer to a full or partial pathname specifying the file or directory for which to create an FSSpec. If the ioNamePtr field specifies a full pathname, PBMakeFSSpecAsync ignores both the ioVRefNum and ioDirID fields. A partial pathname might identify only the final target, or it might include one or more parent directory names. If ioNamePtr specifies a partial pathname, then ioVRefNum, ioDirID, or both must be valid.
ioVRefNum: On input, a volume specification for the volume containing the file or directory. This field can contain a volume reference number, a drive number, or 0 to specify the default volume.
ioMisc: On input, a pointer to an FSSpec structure. Given a complete specification for a file or directory, the PBMakeFSSpecAsync function fills in this FSSpec structure to identify the file or directory. On output, this field points to the initialized FSSpec. The file system specification structure that you pass in this field should not share storage space with the input pathname; the name field may be initialized to the empty string before the pathname has been processed. For example, ioNamePtr should not refer to the name field of the output file system specification.
ioDirID: On input, a directory ID. This field usually specifies the parent directory ID of the target object. If the directory is sufficiently specified by the ioNamePtr field, the ioDirID field can be set to 0. If the ioNamePtr field contains an empty string, PBMakeFSSpecAsync creates an FSSpec structure for the directory specified by the ioDirID field.

Carbon Porting Notes

Non-Carbon applications can also specify a working directory reference number in the ioVRefNum field. However, because working directories are not supported in Carbon, you cannot specify a working directory reference number if you wish your application to be Carbon-compatible.

Availability

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

Declared In

Files.h

PBMakeFSSpecSync

Creates an FSSpec structure for a file or directory. (Deprecated in Mac OS X v10.4. Use PBMakeFSRefUnicodeSync instead.)

OSErr PBMakeFSSpecSync (
   HParmBlkPtr paramBlock
);

Parameters

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

Return Value

A result code. See “File Manager Result Codes.” When PBMakeFSSpecSync returns any result other than noErr or fnfErr, all fields of the resulting FSSpec structure are set to 0.

Discussion

The relevant fields of the parameter block are:

ioNamePtr: On input, a pointer to a full or partial pathname specifying the file or directory for which to create an FSSpec. If the ioNamePtr field specifies a full pathname, PBMakeFSSpecSync ignores both the ioVRefNum and ioDirID fields. A partial pathname might identify only the final target, or it might include one or more parent directory names. If ioNamePtr specifies a partial pathname, then ioVRefNum, ioDirID, or both must be valid.
ioVRefNum: On input, a volume specification for the volume containing the file or directory. This field can contain a volume reference number, a drive number, or 0 to specify the default volume.
ioMisc: On input, a pointer to an FSSpec structure. Given a complete specification for a file or directory, the PBMakeFSSpecSync function fills in this FSSpec structure to identify the file or directory. On output, this field points to the initialized FSSpec. The file system specification structure that you pass in this field should not share storage space with the input pathname; the name field may be initialized to the empty string before the pathname has been processed. For example, ioNamePtr should not refer to the name field of the output file system specification.
ioDirID: On input, a directory ID. This field usually specifies the parent directory ID of the target object. If the directory is sufficiently specified by the ioNamePtr field, the ioDirID field can be set to 0. If the ioNamePtr field contains an empty string, PBMakeFSSpecSync creates an FSSpec structure for the directory specified by the ioDirID field.

If the specified volume is mounted and the specified parent directory exists, but the target file or directory doesn’t exist in that location, PBMakeFSSpecSync fills in the structure and returns fnfErr instead of noErr. The structure is valid, but it describes a target that doesn’t exist. You can use the structure for another operation, such as creating a file.

Carbon Porting Notes

Availability

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

Declared In

Files.h

PBSetCatInfoAsync

Modifies catalog information for a file or directory. (Deprecated in Mac OS X v10.4. Use PBSetCatalogInfoAsync instead.)

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.

Availability

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

Declared In

Files.h

PBSetCatInfoSync

Modifies catalog information for a file or directory. (Deprecated in Mac OS X v10.4. Use PBSetCatalogInfoSync instead.)

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.

Availability

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

Declared In

Files.h

PBSetEOFAsync

Sets the logical size of an open file. (Deprecated in Mac OS X v10.4. Use PBSetForkSizeAsync instead.)

OSErr PBSetEOFAsync (
   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.
ioMisc: On input, the new logical size (the logical end-of-file) of the given file. Because the ioMisc field is of type Ptr, you must coerce the desired value from a long integer to type Ptr. If the value of the ioMisc field is 0, all space occupied by the file on the volume is released. The file still exists, but it contains 0 bytes. Setting a file fork’s end-of-file to 0 is therefore not the same as deleting the file, which removes both file forks at once.

If you attempt to set the logical end-of-file beyond the current physical end-of-file, another allocation block is added to the file if there isn’t enough space on the volume, no change is made and PBSetEOFAsync returns dskFulErr as its function result.

To ensure that your changes to the file are written to disk, call one of the functions, FlushVol , PBFlushVolSync , or PBFlushVolAsync. To set the size of a named fork other than the data and resource forks, or to grow the size of a file beyond 2GB, you must use the FSSetForkSize function, or one of the corresponding parameter block calls, PBSetForkSizeSync and PBSetForkSizeAsync.

Availability

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

Declared In

Files.h

PBSetEOFSync

Sets the logical size of an open file. (Deprecated in Mac OS X v10.4. Use PBSetForkSizeSync instead.)

OSErr PBSetEOFSync (
   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.
ioMisc: On input, the new logical size (the logical end-of-file) of the given file. Because the ioMisc field is of type Ptr, you must coerce the desired value from a long integer to type Ptr. If the value of the ioMisc field is 0, all space occupied by the file on the volume is released. The file still exists, but it contains 0 bytes. Setting a file fork’s end-of-file to 0 is therefore not the same as deleting the file, which removes both file forks at once.

Availability

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

Declared In

Files.h

PBSetForeignPrivsAsync

Changes the native access-control information for a file or directory stored on a volume managed by a foreign file system. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr PBSetForeignPrivsAsync (
   HParmBlkPtr paramBlock
);

Special Considerations

This function is not implemented in Mac OS X.

Availability

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

Declared In

Files.h

PBSetForeignPrivsSync

Changes the native access-control information for a file or directory stored on a volume managed by a foreign file system. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr PBSetForeignPrivsSync (
   HParmBlkPtr paramBlock
);

Special Considerations

This function is not implemented in Mac OS X.

Availability

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

Declared In

Files.h

PBSetFPosAsync

Sets the position of the file mark. (Deprecated in Mac OS X v10.4. Use PBSetForkPositionAsync instead.)

OSErr PBSetFPosAsync (
   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, the file reference number for an open file.
ioPosMode: On input, a constant indicating how to position the mark; this field must contain one of the values described in “Position Mode Constants.”
ioPosOffset: On input, the offset from the base location specified by the ioPosMode field for the file mark. If you specify fsAtMark in the ioPosMode field, the mark is left wherever it’s currently positioned and the value in the ioPosOffset field is ignored. If you specify fsFromLEOF, the value in ioPosOffset must be less than or equal to 0. On output, the position at which the mark was actually set.

The PBSetFPosAsync function sets the mark of the specified file to the position specified by the ioPosMode and ioPosOffset fields. If you try to set the mark past the logical end-of-file, PBSetFPosAsync moves the mark to the end-of-file and returns eofErr as its function result.

To set the file mark position for a named fork other than the data and resource forks, or to position the file mark at a point more than 2GB into the file, use the FSSetForkPosition function, or one of the corresponding parameter block calls, PBSetForkPositionSync and PBSetForkPositionAsync.

Availability

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

Declared In

Files.h

PBSetFPosSync

Sets the position of the file mark. (Deprecated in Mac OS X v10.4. Use PBSetForkPositionSync instead.)

OSErr PBSetFPosSync (
   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, the file reference number for an open file.
ioPosMode: On input, a constant indicating how to position the file mark; this field must contain one of the values described in “Position Mode Constants.”
ioPosOffset: On input, the offset from the base location specified by the ioPosMode field for the file mark. If you specify fsAtMark in the ioPosMode field, the mark is left wherever it’s currently positioned and the value in the ioPosOffset field is ignored. If you specify fsFromLEOF, the value in ioPosOffset must be less than or equal to 0. On output, the position at which the mark was actually set.

The PBSetFPosSync function sets the mark of the specified file to the position specified by the ioPosMode and ioPosOffset fields. If you try to set the mark past the logical end-of-file, PBSetFPosSync moves the mark to the end-of-file and returns eofErr as its function result.

Availability

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

Declared In

Files.h

PBSetVInfoAsync

Changes information about a volume. (Deprecated in Mac OS X v10.4. Use PBSetVolumeInfoAsync instead.)

OSErr PBSetVInfoAsync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the HVolumeParam 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 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 volume’s name. You can specify a new name for the volume here. You cannot specify the volume by name you must use either the volume reference number or the drive number.
ioVRefNum: On input, a volume reference number or drive number for the volume whose information is to be changed; or 0 for the default volume.
ioVCrDate: On input, the date and time of the volume’s initialization.
ioVLsMod: On input, the date and time of the volume’s last modification.
ioVAtrb: On input, the volume attributes. Only bit 15 of the ioVAtrb field can be changed; setting it locks the volume. See “Volume Information Attribute Constants” for a description of the volume attributes.
ioVBkUp: On input, the date and time of the volume’s last backup.
ioVSeqNum: Used internally.
ioVFndrInfo: On input, Finder information for the volume.

Availability

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

Declared In

Files.h

PBSetVInfoSync

Changes information about a volume. (Deprecated in Mac OS X v10.4. Use PBSetVolumeInfoSync instead.)

OSErr PBSetVInfoSync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the HVolumeParam 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 volume’s name. You can specify a new name for the volume here. You cannot specify the volume by name you must use either the volume reference number or the drive number.
ioVRefNum: On input, a volume reference number or drive number for the volume whose information is to be changed; or 0 for the default volume.
ioVCrDate: On input, the date and time of the volume’s initialization.
ioVLsMod: On input, the date and time of the volume’s last modification.
ioVAtrb: On input, the volume attributes. Only bit 15 of the ioVAtrb field can be changed; setting it locks the volume. See “Volume Information Attribute Constants” for a description of the volume attributes.
ioVBkUp: On input, the date and time of the volume’s last backup.
ioVSeqNum: Used internally.
ioVFndrInfo: On input, Finder information for the volume.

Availability

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

Declared In

Files.h

PBShareAsync

Establishes a local volume or directory as a share point. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr PBShareAsync (
   HParmBlkPtr paramBlock
);

Special Considerations

This function is not implemented in Mac OS X.

Availability

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

Declared In

Files.h

PBShareSync

Establishes a local volume or directory as a share point. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr PBShareSync (
   HParmBlkPtr paramBlock
);

Special Considerations

This function is not implemented in Mac OS X.

Availability

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

Declared In

Files.h

PBUnlockRangeAsync

Unlocks a portion of a file. (Deprecated in Mac OS X v10.4. Use PBXUnlockRangeAsync instead.)

OSErr PBUnlockRangeAsync (
   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. If you call PBUnlockRangeAsync on a file system that does not implement it—for example, SMB—PBUnlockRangeAsync returns noErr and does nothing.
ioRefNum: On input, the file reference number of the file owning the range to unlock.
ioReqCount: On input, the number of bytes in the range.
ioPosMode: On input, a constant specifying the base location for the start of the locked range. See “Position Mode Constants” for more information on the constants you can use to indicate the base location.
ioPosOffset: On input, the offset from the base location specified in the ioPosMode field for the start of the locked range.

The PBUnlockRangeAsync function unlocks a portion of a file that you locked with PBLockRangeSync or PBLockRangeAsync. The beginning of the range to be unlocked is determined by the ioPosMode and ioPosOffset fields. The end of the range to be unlocked is determined by the beginning of the range and the ioReqCount field. For example, to unlock the first 50 bytes in a file, set ioReqCount to 50, ioPosMode to fsFromStart, and ioPosOffset to 0. The range of bytes to be unlocked must be the exact same range locked by a previous call to PBLockRangeSync or PBLockRangeAsync.

If for some reason you need to unlock a range whose beginning or length is unknown, you can simply close the file. When a file is closed, all locked ranges held by the user are unlocked.

Special Considerations

The PBUnlockRangeAsync function does nothing if the file specified in the ioRefNum field is open with shared read/write permission but is not located on a remote server volume or is not located under a share point on a local volume. To check whether file sharing is currently on, check that the bHasPersonalAccessPrivileges bit in the vMAttrib field of the GetVolParmsInfoBuffer returned by the PBHGetVolParmsSync function is set.

Availability

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

Declared In

Files.h

PBUnlockRangeSync

Unlocks a portion of a file. (Deprecated in Mac OS X v10.4. Use PBXUnlockRangeSync or FSUnlockRange instead.)

OSErr PBUnlockRangeSync (
   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.” If you call PBUnlockRangeSync on a file system that does not implement it—for example, SMB—PBUnlockRangeSync returns noErr and does nothing.

Discussion

The relevant fields of the parameter block are:

ioRefNum: On input, the file reference number of the file owning the range to unlock.
ioReqCount: On input, the number of bytes in the range.
ioPosMode: On input, a constant specifying the base location for the start of the locked range. See “Position Mode Constants” for more information on the constants you can use to indicate the base location.
ioPosOffset: On input, the offset from the base location specified in the ioPosMode field for the start of the locked range.

The PBUnlockRangeSync function unlocks a portion of a file that you locked with PBLockRangeSync or PBLockRangeAsync. The beginning of the range to be unlocked is determined by the ioPosMode and ioPosOffset fields. The end of the range to be unlocked is determined by the beginning of the range and the ioReqCount field. For example, to unlock the first 50 bytes in a file, set ioReqCount to 50, ioPosMode to fsFromStart, and ioPosOffset to 0. The range of bytes to be unlocked must be the exact same range locked by a previous call to PBLockRangeSync or PBLockRangeAsync.

If for some reason you need to unlock a range whose beginning or length is unknown, you can simply close the file. When a file is closed, all locked ranges held by the user are unlocked.

Special Considerations

The PBUnlockRangeSync function does nothing if the file specified in the ioRefNum field is open with shared read/write permission but is not located on a remote server volume or is not located under a share point on a local volume. To check whether file sharing is currently on, check that the bHasPersonalAccessPrivileges bit in the vMAttrib field of the GetVolParmsInfoBuffer returned by the PBHGetVolParmsSync function is set.

Availability

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

Declared In

Files.h

PBUnmountVol

Unmounts a volume. (Deprecated in Mac OS X v10.4. Use FSEjectVolumeSync or FSUnmountVolumeSync instead.)

OSErr PBUnmountVol (
   ParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the VolumeParam 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:

ioResult: On output, the result code of the function.
ioNamePtr: On input, a pointer to the name of the volume.
ioVRefNum: On input, the volume reference number of the volume to unmount, or 0 for the default volume.

This function calls PBFlushVolSync to flush the specified volume, unmounts and ejects the volume, and releases the memory used for the volume. Prior to calling this function, all user files on the volume must be closed. Ejecting a volume results in the unmounting of other volumes on the same device.

The PBUnmountVol function always executes synchronously.

Special Considerations

Don’t unmount the startup volume. Doing so will cause a system crash.

Availability

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

Declared In

Files.h

PBUnshareAsync

Makes a share point unavailable on the network. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr PBUnshareAsync (
   HParmBlkPtr paramBlock
);

Special Considerations

This function is not implemented in Mac OS X.

Availability

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

Declared In

Files.h

PBUnshareSync

Makes a share point unavailable on the network. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr PBUnshareSync (
   HParmBlkPtr paramBlock
);

Special Considerations

This function is not implemented in Mac OS X.

Availability

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

Declared In

Files.h

PBXGetVolInfoAsync

Returns information about a volume, including size information for volumes up to 2 terabytes. (Deprecated in Mac OS X v10.4. Use FSGetVolumeInfo instead.)

OSErr PBXGetVolInfoAsync (
   XVolumeParamPtr paramBlock
);

Parameters

paramBlock: A pointer to an extended volume parameter block. See XVolumeParam for a description of the XVolumeParam 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 function result.
ioNamePtr: On input, a pointer to a buffer. You should pass a pointer to a Str31 value if you want the volume name returned; otherwise, pass NULL. If you specify a negative number in the ioVolIndex field, this buffer should hold the name of the volume for which to return information. On output, a pointer to the volume’s name.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume. If the value in the ioVolIndex field is negative, the File Manager uses the name in the ioNamePtr field, along with the value in the ioVRefNum field, to determine the volume. If the value in ioVolIndex is 0, the File Manager attempts to access the volume using only the value in this field. On output, the volume reference number.
ioXVersion: On input, the version of the extended volume parameter block. Currently, this value is 0.
ioVolIndex: On input, an index used for indexing through all the mounted volumes. If this value is positive, the File Manager uses it to find the volume for which to return information. For instance, if the value of ioVolIndex is 2, the File Manager attempts to access the second mounted volume in the VCB queue. If ioVolIndex is negative, the File Manager uses the values in the ioNamePtr and ioVRefNum fields to access the requested volume. If ioVolIndex is 0, the File Manager uses only the value in the ioVRefNum field.
ioVCrDate: On output, the date and time of the volume’s creation (initialization).
ioVLsMod: On output, the date and time that the volume was last modified.
ioVAtrb: On output, the volume attributes. See “Volume Information Attribute Constants” for a description of these attributes.
ioVNmFls: On output, the number of files in the root directory of the volume. For performance reasons, the Carbon File Manager does not return the number of files in this field; instead, it sets ioVNmFls to 0.To determine the number of files in the root directory of a volume in Carbon, call PBGetCatInfoAsync for the root directory. The number of files in the root directory is returned in the ioDrNmFls field.
ioVBitMap: On output, the first block of the volume bitmap.
ioVAllocPtr: On output, the block where the next new file allocation search should start.
ioVNmAlBlks: On output, the number of allocation blocks on the volume.
ioVAlBlkSiz: On output, the allocation block size for the volume.
ioVClpSiz: On output, the volume’s default clump size.
ioAlBlSt: On output, the first block in the volume block map.
ioVNxtCNID: On output, the next unused catalog node ID.
ioVFrBlk: On output, the number of free (unused) allocation blocks on the volume.
ioVSigWord: On output, the volume signature. For HFS volumes, this is ‘BD’ for HFS Plus volumes, this is ‘H+’.
ioVDrvInfo: On output, the drive number. You can determine whether the given volume is online by inspecting the value of this field. For online volumes, the ioVDrvInfo field contains the drive number of the drive containing the specified volume and hence is always greater than 0. If the value returned in ioVDrvInfo is 0, the volume is either offline or ejected.
ioVDRefNum: On output, the driver reference number. You can determine whether the volume is offline or ejected by inspecting the value of this field. If the volume is offline, the value of ioVDRefNum is the negative of the drive number (which is cleared when the volume is placed offline; hence the ioVDrvInfo field for an offline volume is zero), and is a negative number. If the volume is ejected, the value of ioVDRefNum is the drive number itself, and thus is a positive number. For online volumes, ioVDRefNum contains a driver reference number; these numbers are always less than 0.
ioVFSID: On output, the file system ID for the file system handling this volume.
ioVBkUp: On output, the date and time that the volume was last backed up.
ioVSeqNum: Used internally.
ioVWrCnt: On output, the volume write count.
ioVFilCnt: On output, the number of files on the volume.
ioVDirCnt: On output, the number of directories on the volume.
ioVFndrInfo: On output, Finder information for the volume.
ioVTotalBytes: On output, the total number of bytes on the volume.
ioVFreeBytes: On output, the number of free bytes on the volume.

The PBXGetVolInfoAsync function is similar to the PBHGetVInfoAsync function except that it returns additional volume space information in 64-bit integers and does not modify the information copied from the volume’s volume control block (VCB). Systems that support PBXGetVolInfoAsync will have the gestaltFSSupports2TBVols bit set in the response returned by the gestaltFSAttr Gestalt selector. See Inside Mac OS X: Gestalt Manager Reference for a description of the gestaltFSAttr selector and of the bits that may be returned in the response.

Special Considerations

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

Availability

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

Declared In

Files.h

PBXGetVolInfoSync

Returns information about a volume, including size information for volumes up to 2 terabytes. (Deprecated in Mac OS X v10.4. Use FSGetVolumeInfo instead.)

OSErr PBXGetVolInfoSync (
   XVolumeParamPtr paramBlock
);

Parameters

paramBlock: A pointer to an extended volume parameter block. See XVolumeParam for a description of the XVolumeParam 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 buffer. You should pass a pointer to a Str31 value if you want the volume name returned; otherwise, pass NULL. If you specify a negative number in the ioVolIndex field, this buffer should hold the name of the volume for which to return information. On output, a pointer to the volume’s name.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume. If the value in the ioVolIndex field is negative, the File Manager uses the name in the ioNamePtr field, along with the value in the ioVRefNum field, to determine the volume. If the value in ioVolIndex is 0, the File Manager attempts to access the volume using only the value in this field. On output, the volume reference number.
ioXVersion: On input, the version of the extended volume parameter block. Currently, this value is 0.
ioVolIndex: On input, an index used for indexing through all the mounted volumes. If this value is positive, the File Manager uses it to find the volume for which to return information. For instance, if the value of ioVolIndex is 2, the File Manager attempts to access the second mounted volume in the VCB queue. If ioVolIndex is negative, the File Manager uses the values in the ioNamePtr and ioVRefNum fields to access the requested volume. If ioVolIndex is 0, the File Manager uses only the value in the ioVRefNum field.
ioVCrDate: On output, the date and time of the volume’s creation (initialization).
ioVLsMod: On output, the date and time that the volume was last modified.
ioVAtrb: On output, the volume attributes. See “Volume Information Attribute Constants” for a description of these attributes.
ioVNmFls: On output, the number of files in the root directory of the volume. For performance reasons, the Carbon File Manager does not return the number of files in this field; instead, it sets ioVNmFls to 0.To determine the number of files in the root directory of a volume in Carbon, call PBGetCatInfoSync for the root directory. The number of files in the root directory is returned in the ioDrNmFls field.
ioVBitMap: On output, the first block of the volume bitmap.
ioVAllocPtr: On output, the block where the next new file allocation search should start.
ioVNmAlBlks: On output, the number of allocation blocks on the volume.
ioVAlBlkSiz: On output, the allocation block size for the volume.
ioVClpSiz: On output, the volume’s default clump size.
ioAlBlSt: On output, the first block in the volume block map.
ioVNxtCNID: On output, the next unused catalog node ID.
ioVFrBlk: On output, the number of free (unused) allocation blocks on the volume.
ioVSigWord: On output, the volume signature. For HFS volumes, this is ‘BD’ for HFS Plus volumes, this is ‘H+’.
ioVDrvInfo: On output, the drive number. You can determine whether the given volume is online by inspecting the value of this field. For online volumes, the ioVDrvInfo field contains the drive number of the drive containing the specified volume and hence is always greater than 0. If the value returned in ioVDrvInfo is 0, the volume is either offline or ejected.
ioVDRefNum: On output, the driver reference number. You can determine whether the volume is offline or ejected by inspecting the value of this field. If the volume is offline, the value of ioVDRefNum is the negative of the drive number (which is cleared when the volume is placed offline; hence the ioVDrvInfo field for an offline volume is zero), and is a negative number. If the volume is ejected, the value of ioVDRefNum is the drive number itself, and thus is a positive number. For online volumes, ioVDRefNum contains a driver reference number; these numbers are always less than 0.
ioVFSID: On output, the file system ID for the file system handling this volume.
ioVBkUp: On output, the date and time that the volume was last backed up.
ioVSeqNum: Used internally.
ioVWrCnt: On output, the volume write count.
ioVFilCnt: On output, the number of files on the volume.
ioVDirCnt: On output, the number of directories on the volume.
ioVFndrInfo: On output, Finder information for the volume.
ioVTotalBytes: On output, the total number of bytes on the volume.
ioVFreeBytes: On output, the number of free bytes on the volume.

The PBXGetVolInfoSync function is similar to the PBHGetVInfoSync function except that it returns additional volume space information in 64-bit integers and does not modify the information copied from the volume’s volume control block (VCB). Systems that support PBXGetVolInfoSync will have the gestaltFSSupports2TBVols bit set in the response returned by the gestaltFSAttr Gestalt selector. See Inside Mac OS X: Gestalt Manager Reference for a description of the gestaltFSAttr selector and of the bits that may be returned in the response.

Special Considerations

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

Availability

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

Declared In

Files.h

SetEOF

Sets the logical size of an open file. (Deprecated in Mac OS X v10.4. Use FSSetForkSize instead.)

OSErr SetEOF (
   FSIORefNum refNum,
   SInt32 logEOF
);

Parameters

refNum: The file reference number of an open file.
logEOF: The new logical size (the logical end-of-file) of the given file. If you set the logEOF parameter to 0, all space occupied by the file on the volume is released. The file still exists, but it contains 0 bytes. Setting a file fork’s end-of-file to 0 is therefore not the same as deleting the file, which removes both file forks at once.

Return Value

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

Discussion

If you attempt to set the logical end-of-file beyond the physical end-of-file, the physical end-of-file is set 1 byte beyond the end of the next free allocation block if there isn’t enough space on the volume, no change is made, and SetEOF returns dskFulErr as its function result.

Availability

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

Declared In

Files.h

SetFPos

Sets the position of the file mark. (Deprecated in Mac OS X v10.4. Use FSSetForkPosition instead.)

OSErr SetFPos (
   FSIORefNum refNum,
   SInt16 posMode,
   SInt32 posOff
);

Parameters

refNum: The file reference number of an open file.
posMode: A constant specifying how to position the file mark; this parameter must contain one of the values described in “Position Mode Constants.”
posOff: The offset from the base location specified by the posMode parameter for the new file mark position. If you specify fsFromLEOF in the posMode parameter, the value in the posOff parameter must be less than or equal to 0. If you specify fsAtMark, the value in the posOff parameter is ignored.

Return Value

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

Discussion

Because the read and write operations performed by the functions FSRead and FSWrite begin at the current mark, you may want to call SetFPos to reposition the file mark before reading from or writing to the file.

Availability

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

Declared In

Files.h

UnmountVol

Unmounts a volume that isn’t currently being used. (Deprecated in Mac OS X v10.4. Use FSUnmountVolumeSync instead.)

OSErr UnmountVol (
   ConstStr63Param volName,
   FSVolumeRefNum vRefNum
);

Parameters

volName: The name of a mounted volume. This parameter may be NULL.
vRefNum: The volume reference number, drive number, or 0 for the default volume.

Return Value

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

Discussion

All files on the volume (except those opened by the Operating System) must be closed before you call UnmountVol, which does not eject the volume.

Most applications do not need to use this function, because the user typically ejects (and possibly also unmounts) a volume in the Finder.

Special Considerations

Don’t unmount the startup volume. Doing so will cause a system crash.

Availability

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

Declared In

Files.h

Deprecated in Mac OS X v10.5

FlushVol

Writes the contents of the volume buffer and updates information about the volume. (Deprecated in Mac OS X v10.5. Use FSFlushVolume instead.)

OSErr FlushVol (
   ConstStr63Param volName,
   FSVolumeRefNum vRefNum
);

Parameters

volName: The name of the mounted volume to flush.
vRefNum: The volume reference number, drive number, or 0 for the default volume.

Return Value

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

Discussion

For the specified volume, the FlushVol function writes the contents of the associated volume buffer and descriptive information about the volume. Information which has changed since the last time FlushVol was called is written to the volume.

Availability

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

Declared In

Files.h

FSpMakeFSRef

Creates an FSRef for a file or directory, given an FSSpec. (Deprecated in Mac OS X v10.5. There is no replacement function.)

OSErr FSpMakeFSRef (
   const FSSpec *source,
   FSRef *newRef
);

Parameters

source: A pointer to the FSSpec for the file or directory. This parameter must point to a valid FSSpec for an existing file or directory; if it does not, the call will return fnfErr. See FSSpec for a description of the FSSpec data type.
newRef: On input, a pointer to an FSRef structure. On return, a pointer to the FSRef for the file or directory specified in the FSSpec pointed to in the source parameter.

Return Value

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

Discussion

To obtain an FSSpec from an FSRef, use the FSGetCatalogInfo function.

Availability

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

Related Sample Code

Declared In

Files.h

PBCloseAsync

Closes an open file. (Deprecated in Mac OS X v10.5. Use PBCloseForkAsync instead.)

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.

Availability

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

Declared In

Files.h

PBCloseSync

Closes an open file. (Deprecated in Mac OS X v10.5. Use PBCloseForkSync instead.)

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.

Availability

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

Declared In

Files.h

PBCreateFileIDRefAsync

Establishes a file ID reference for a file. (Deprecated in Mac OS X v10.5. Use FSGetCatalogInfo instead.)

OSErr PBCreateFileIDRefAsync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the FIDParam 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

Most applications do not need to use this function. In general, you should track files using alias records, as described in the Alias Manager documentation. The Alias Manager uses file IDs internally as part of its search algorithms for finding the target of an alias record.

Given a volume reference number, filename, and parent directory ID, the PBCreateFileIDRefAsync function creates a structure to hold the name and parent directory ID of the specified file. 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. PBCreateFileIDRefAsync returns the result code fidExists if a file ID reference already exists for the file.
ioNamePtr: On input, a pointer to the file’s name.
ioVRefNum: On input, a volume reference number for the volume containing the file.
ioSrcDirID: On input, the file’s parent directory ID.
ioFileID: On output, a file ID. If a file ID reference already exists for the file, PBCreateFileIDRefAsync supplies the file ID but returns the result code fidExists.

Availability

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

Declared In

Files.h

PBCreateFileIDRefSync

Establishes a file ID reference for a file. (Deprecated in Mac OS X v10.5. Use FSGetCatalogInfo instead.)

OSErr PBCreateFileIDRefSync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the FIDParam 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.”PBCreateFileIDRefSync returns the result code fidExists if a file ID reference already exists for the file.

Discussion

Given a volume reference number, filename, and parent directory ID, the PBCreateFileIDRefSync function creates a structure to hold the name and parent directory ID of the specified file. The relevant fields of the parameter block are:

ioNamePtr: On input, a pointer to the file’s name.
ioVRefNum: On input, a volume reference number for the volume containing the file.
ioSrcDirID: On input, the file’s parent directory ID.
ioFileID: On output, a file ID. If a file ID reference already exists for the file, PBCreateFileIDRefSync supplies the file ID but returns the result code fidExists.

Availability

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

Declared In

Files.h

PBDeleteFileIDRefAsync

Deletes a file ID reference. (Deprecated in Mac OS X v10.5. There is no replacement function.)

OSErr PBDeleteFileIDRefAsync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the FIDParam 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 for the volume containing the file.
ioFileID: On input, the file ID reference to delete. After it has invalidated a file ID reference, the File Manager can no longer resolve that ID reference to a filename and parent directory ID.

Special Considerations

This function is not implemented in Mac OS X.

Availability

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

Declared In

Files.h

PBDeleteFileIDRefSync

Deletes a file ID reference. (Deprecated in Mac OS X v10.5. There is no replacement function.)

OSErr PBDeleteFileIDRefSync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the FIDParam 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 for the volume containing the file.
ioFileID: On input, the file ID reference to delete. After it has invalidated a file ID reference, the File Manager can no longer resolve that ID reference to a filename and parent directory ID.

Special Considerations

This function is not implemented in Mac OS X.

Availability

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

Declared In

Files.h

PBFlushVolAsync

Writes the contents of the volume buffer and updates information about the volume. (Deprecated in Mac OS X v10.5. Use PBFlushVolumeAsync instead.)

OSErr PBFlushVolAsync (
   ParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the VolumeParam 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.
ioNamePtr: On input, a pointer to the name of the volume to flush.
ioVRefNum: On input, a volume reference number, drive number, or 0 for the default volume.

PBFlushVolAsync flushes all open files on the volume, and then flushes all volume data structures. On the volume specified by ioNamePtr or ioVRefNum, the PBFlushVolAsync function writes descriptive information about the volume, the contents of the associated volume buffer, and all access path buffers for the volume (if they’ve changed since the last time PBFlushVolAsync was called).

The date and time of the last modification to the volume are set when the modification is made, not when the volume is flushed.

To ensure that all changes to a volume are flushed to the volume, use PBFlushVolAsync. You do not, however, need to flush a volume before unmounting it, ejecting it, or putting it offline; this is done automatically.

If changes are made to a file that affect the file’s end-of-file, the file’s name, the file’s Finder information, or the file’s location on the volume, then you must use PBFlushVolAsync, or one of the other two volume flush functions in this section, to ensure that these changes are written to disk.

Availability

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

Declared In

Files.h

PBFlushVolSync

Writes the contents of the volume buffer and updates information about the volume. (Deprecated in Mac OS X v10.5. Use PBFlushVolumeSync instead.)

OSErr PBFlushVolSync (
   ParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the VolumeParam 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:

ioNamePtr: On input, a pointer to the name of the volume to flush.
ioVRefNum: On input, the volume reference number, drive number, or 0 for the default volume.

PBFlushVolSync flushes all open files on the volume, and then flushes all volume data structures. On the volume specified by ioNamePtr or ioVRefNum, the PBFlushVolSync function writes descriptive information about the volume, the contents of the associated volume buffer, and all access path buffers for the volume (if they’ve changed since the last time PBFlushVolSync was called).

The date and time of the last modification to the volume are set when the modification is made, not when the volume is flushed.

To ensure that all changes to a volume are flushed to the volume, use PBFlushVolSync. You do not, however, need to flush a volume before unmounting it, ejecting it, or putting it offline; this is done automatically.

If changes are made to a file that affect the file’s end-of-file, the file’s name, the file’s Finder information, or the file’s location on the volume, then you must use PBFlushVolSync, or one of the other two volume flush functions in this section, to ensure that these changes are written to disk.

Availability

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

Declared In

Files.h

PBGetVolMountInfo

Retrieves a record containing all the information needed to mount a volume, except for passwords. (Deprecated in Mac OS X v10.5. Use FSVolumeMount instead.)

OSErr PBGetVolMountInfo (
   ParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the IOParam variant of the basic File Manager 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. This field can contain a volume reference number, drive number, or 0 for the default volume.
ioBuffer: On input, a pointer to a buffer to hold the mounting information. The length of the buffer is specified by the value pointed to by the ioBuffer field in a previous call to PBGetVolMountInfoSize. On output, the mounting information for the specified volume. You can later pass this structure to the PBVolumeMount function to mount the volume. The mounting information for an AppleShare volume is stored as an AFP mounting record. The PBGetVolMountInfo function does not return the user password or volume password in the AFPVolMountInfo structure. Your application should solicit these passwords from the user and fill in the structure before attempting to mount the remote volume.

This function allows your application to record the mounting information for a volume and then to mount the volume later. This programmatic mounting function stores the mounting information in a structure called the AFPVolMountInfo structure.

Special Considerations

This function executes synchronously. You should not call it at interrupt time.

Availability

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

Declared In

Files.h

PBGetVolMountInfoSize

Determines how much space to allocate for a volume mounting information structure. (Deprecated in Mac OS X v10.5. Use FSVolumeMount instead.)

OSErr PBGetVolMountInfoSize (
   ParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the IOParam variant of the basic File Manager 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. This field can contain a volume reference number, drive number, or 0 for the default volume.
ioBuffer: On input, a pointer to storage for the size information, which is of type Integer (2 bytes). If PBGetVolMountInfoSize returns noErr, that integer contains the size of the volume mounting information structure on output.

You should call this function before you call PBGetVolMountInfo , to obtain the size of the volume mounting information for which you must allocate storage. Then call PBGetVolMountInfo to retrieve the actual volume mounting information.

Special Considerations

This function executes synchronously. You should not call it at interrupt time.

Availability

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

Declared In

Files.h

PBHCopyFileAsync

Duplicates a file and optionally renames it. (Deprecated in Mac OS X v10.5. Use PBFSCopyFileAsync instead.)

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.

Availability

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

Declared In

Files.h

PBHCopyFileSync

Duplicates a file and optionally renames it. (Deprecated in Mac OS X v10.5. Use PBFSCopyFileSync instead.)

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.

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.

Availability

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

Declared In

Files.h

PBHGetDirAccessAsync

Returns the access control information for a directory or file. (Deprecated in Mac OS X v10.5. Use FSGetCatalogInfo instead.)

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.

Availability

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

Declared In

Files.h

PBHGetDirAccessSync

Returns the access control information for a directory or file. (Deprecated in Mac OS X v10.5. Use FSGetCatalogInfo instead.)

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.

Availability

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

Declared In

Files.h

PBHGetVolParmsAsync

Returns information about the characteristics of a volume. (Deprecated in Mac OS X v10.5. Use FSGetVolumeParms instead.)

OSErr PBHGetVolParmsAsync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the HIOParam 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 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 volume’s name. You can use a either a name or a volume specification to specify the volume. If you use a volume specification to specify the volume, you should set the ioNamePtr field to NULL.
ioVRefNum: On input, a volume specification. You can use a either a name or a volume specification to specify the volume. A volume specification can be a volume reference number, drive number, or 0 for the default volume.
ioBuffer: On input, a pointer to a GetVolParmsInfoBuffer record; you must allocate this memory to hold the returned attributes. On return, the PBHGetVolParmsAsync function places the attributes information in the buffer. Volumes that implement the HFS Plus APIs must use version 3 (or newer) of the GetVolParmsInfoBuffer structure. If the version of the GetVolParmsInfoBuffer is 2 or less, or the bSupportsHFSPlusAPIs bit is clear, then the volume does not implement the HFS Plus APIs and they are being emulated for that volume by the File Manager.
ioReqCount: On input, the size, in bytes, of the buffer area pointed to in the ioBuffer field.
ioActCount: On output, the size of the data actually returned.

Availability

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

Declared In

Files.h

PBHGetVolParmsSync

Returns information about the characteristics of a volume. (Deprecated in Mac OS X v10.5. Use FSGetVolumeParms instead.)

OSErr PBHGetVolParmsSync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the HIOParam 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 volume’s name. You can use a either a name or a volume specification to specify the volume. If you use a volume specification to specify the volume, you should set the ioNamePtr field to NULL.
ioVRefNum: On input, a volume specification. You can use a either a name or a volume specification to specify the volume. A volume specification can be a volume reference number, drive number, or 0 for the default volume.
ioBuffer: On input, a pointer to a GetVolParmsInfoBuffer record; you must allocate this memory to hold the returned attributes. On return, the PBHGetVolParmsSync function places the attributes information in the buffer. Volumes that implement the HFS Plus APIs must use version 3 (or newer) of the GetVolParmsInfoBuffer structure. If the version of the GetVolParmsInfoBuffer is 2 or less, or the bSupportsHFSPlusAPIs bit is clear, then the volume does not implement the HFS Plus APIs and they are being emulated for that volume by the File Manager.
ioReqCount: On input, the size, in bytes, of the buffer area pointed to in the ioBuffer field.
ioActCount: On output, the size of the data actually returned.

Availability

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

Declared In

Files.h

PBHMapIDAsync

Determines the name of a user or group given the user or group ID. (Deprecated in Mac OS X v10.5. There is no replacement function.)

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.

Version Notes

Because user and group IDs are interchangeable under AFP 2.1 and later volumes, you might not need to specify a value in the ioObjType field.

Availability

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

Declared In

Files.h

PBHMapIDSync

Determines the name of a user or group given the user or group ID. (Deprecated in Mac OS X v10.5. There is no replacement function.)

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.

Version Notes

Because user and group IDs are interchangeable under AFP 2.1 and later volumes, you might not need to specify a value in the ioObjType field.

Availability

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

Declared In

Files.h

PBHMapNameAsync

Determines the user ID or group ID from a user or group name. (Deprecated in Mac OS X v10.5. There is no replacement function.)

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.

Version Notes

Because user and group IDs are interchangeable under AFP 2.1 and later volumes, you might need to set the ioObjType field to determine which database (user or group) to search first. If both a user and a group have the same name, this field determines which kind of ID you receive.

Availability

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

Declared In

Files.h

PBHMapNameSync

Determines the user ID or group ID from a user or group name. (Deprecated in Mac OS X v10.5. There is no replacement function.)

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.

Version Notes

Availability

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

Declared In

Files.h

PBHOpenDenyAsync

Opens a file’s data fork using the access deny modes. (Deprecated in Mac OS X v10.5. Use PBOpenForkAsync with deny modes in the permissions field.)

OSErr PBHOpenDenyAsync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to a basic HFS 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. For more information on completion routines, see IOCompletionProcPtr.
ioResult: On output, the result code of the function. The function returns the result code opWrErr if you’ve requested write permission and you have already opened the file for writing in that case, the existing file reference number is returned in ioRefNum. You should not use this reference number unless your application originally opened the file.
ioNamePtr: On input, a pointer to a pathname for the file.
ioVRefNum: On input, a volume reference number or drive number for the volume containing the file. Pass 0 to indicate the default volume.
ioRefNum: On output, the file reference number for the file.
ioDenyModes: On input, the type of access you are requesting to the fork. See “File Access Permission Constants” for a description of the types of access that you can request.
ioDirID: On input, the parent directory ID of the file.

You should use the PBHOpenDenyAsync and PBHOpenRFDenyAsync functions (or their synchronous counterparts, PBHOpenDenySync and PBHOpenRFDenySync ) if you want to ensure that you get the access permissions and deny-mode permissions that you request. PBHOpenDenyAsync is not retried in any way. If the file cannot be opened because of a deny conflict, the error afpDenyConflict is returned and the ioRefNum field is set to 0.

You can check that the volume supports AFP deny-mode permissions by checking that the bHasOpenDeny bit is set in the vMAttrib field returned by the PBHGetVolParmsSync or PBHGetVolParmsAsync function. If you don’t want to special case volumes that support AFP deny mode permissions, you can use the File Manager permissions. See “File Access Permission Constants” for a description of how File Manager permissions are translated to AFP deny-mode permissions.

To open a file’s resource fork with access deny permissions, use the PBHOpenRFDenySync or PBHOpenRFDenyAsync function.

Availability

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

Declared In

Files.h

PBHOpenDenySync

Opens a file’s data fork using the access deny modes. (Deprecated in Mac OS X v10.5. Use PBOpenForkSync with deny modes in the permissions field.)

OSErr PBHOpenDenySync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the AccessParam 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.” The function returns the result code opWrErr if you’ve requested write permission and you have already opened the file for writing in that case, the existing file reference number is returned in ioRefNum. You should not use this reference number unless your application originally opened the file.

Discussion

The relevant fields of the parameter block are:

ioNamePtr: On input, a pointer to a pathname for the file.
ioVRefNum: On input, a volume reference number or drive number for the volume containing the file. Pass 0 to indicate the default volume.
ioRefNum: On output, the file reference number for the file.
ioDenyModes: On input, the type of access you are requesting to the fork. See “File Access Permission Constants” for a description of the types of access that you can request.
ioDirID: On input, the parent directory ID of the file.

You should use the PBHOpenDenySync and PBHOpenRFDenySync functions (or their asynchronous counterparts, PBHOpenDenyAsync and PBHOpenRFDenyAsync ) if you want to ensure that you get the access permissions and deny-mode permissions that you request. PBHOpenDenySync is not retried in any way. If the file cannot be opened because of a deny conflict, the error afpDenyConflict is returned and the ioRefNum field is set to 0.

To open a file’s resource fork with access deny permissions, use the PBHOpenRFDenySync or PBHOpenRFDenyAsync function.

Availability

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

Declared In

Files.h

PBHOpenRFDenyAsync

Opens a file’s resource fork using the access deny modes. (Deprecated in Mac OS X v10.5. Use PBOpenForkAsync with deny modes in the permissions field.)

OSErr PBHOpenRFDenyAsync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the AccessParam 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 routine. For more information on completion routines, see IOCompletionProcPtr.
ioResult: On output, the result code of the function. The function returns the result code opWrErr if you’ve requested write permission and you have already opened the file for writing in that case, the existing file reference number is returned in ioRefNum. You should not use this reference number unless your application originally opened the file.
ioNamePtr: On input, a pointer to a pathname for the file.
ioVRefNum: On input, a volume reference number or drive number for the volume containing the file. Pass 0 to indicate the default volume.
ioRefNum: On output, the file reference number for the file.
ioDenyModes: On input, the type of access you are requesting to the fork. See “File Access Permission Constants” for a description of the types of access that you can request.
ioDirID: On input, the parent directory ID of the file.

You should use the PBHOpenRFDenyAsync and PBHOpenDenyAsync functions (or their synchronous counterparts, PBHOpenRFDenySync and PBHOpenDenySync ) if you want to ensure that you get the access permissions and deny-mode permissions that you request. PBHOpenRFDenyAsync is not retried in any way. If the file cannot be opened because of a deny conflict, the error afpDenyConflict is returned and the ioRefNum field is set to 0.

To open a file’s data fork with access deny permissions, use the PBHOpenDenySync or PBHOpenDenyAsync function.

Availability

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

Declared In

Files.h

PBHOpenRFDenySync

Opens a file’s resource fork using the access deny modes. (Deprecated in Mac OS X v10.5. Use PBOpenForkSync with deny modes in the permissions field.)

OSErr PBHOpenRFDenySync (
   HParmBlkPtr paramBlock
);

Parameters

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

Return Value

Discussion

The relevant fields of the parameter block are:

ioCompletion: On input, a pointer to a completion function.
ioResult: On output, the result code of the function.
ioNamePtr: On input, a pointer to a pathname for the file.
ioVRefNum: On input, a volume reference number or drive number for the volume containing the file. Pass 0 to indicate the default volume.
ioRefNum: On output, the file reference number for the file.
ioDenyModes: On input, the type of access you are requesting to the fork. See “File Access Permission Constants” for a description of the types of access that you can request.
ioDirID: On input, the parent directory ID of the file.

You should use the PBHOpenRFDenySync and PBHOpenDenySync functions (or their asynchronous counterparts, PBHOpenRFDenyAsync and PBHOpenDenyAsync ) if you want to ensure that you get the access permissions and deny-mode permissions that you request. PBHOpenRFDenySync is not retried in any way. If the file cannot be opened because of a deny conflict, the error afpDenyConflict is returned and the ioRefNum field is set to 0.

To open a file’s data fork with access deny permissions, use the PBHOpenDenySync or PBHOpenDenyAsync function.

Availability

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

Declared In

Files.h

PBHSetDirAccessAsync

Changes the access control information for a directory. (Deprecated in Mac OS X v10.5. Use FSSetCatalogInfo instead.)

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.

Availability

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

Declared In

Files.h

PBHSetDirAccessSync

Changes the access control information for a directory. (Deprecated in Mac OS X v10.5. Use FSSetCatalogInfo instead.)

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.

Availability

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

Declared In

Files.h

PBMakeFSRefAsync

Creates an FSRef for a file or directory, given an FSSpec. (Deprecated in Mac OS X v10.5. Use PBMakeFSRefUnicodeAsync instead.)

void PBMakeFSRefAsync (
   FSRefParam *paramBlock
);

Parameters

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

Discussion

For the parameter block based calls, the fields of the source FSSpec are passed as separate parameters (in the ioNamePtr, ioVRefNum, and ioDirID fields). This allows the call to be dispatched to external file systems the same way as other FSp calls are.

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 file or directory for which you wish to create an FSRef.
ioVRefNum: On input, a volume specification for the volume containing the file or directory. This can be a volume reference number, a drive number, or 0 for the default volume.
ioDirID: On input, the directory ID of the file or directory’s parent directory.
newRef: On input, a pointer to an FSRef structure. On output, this FSRef refers to the specified file or directory.

To obtain an FSSpec from an FSRef, use the PBGetCatalogInfoAsync call.

Availability

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

Declared In

Files.h

PBMakeFSRefSync

Creates an FSRef for a file or directory, given an FSSpec. (Deprecated in Mac OS X v10.5. Use PBMakeFSRefUnicodeSync instead.)

OSErr PBMakeFSRefSync (
   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:

ioNamePtr: On input, a pointer to the name of the file or directory for which you wish to create an FSRef.
ioVRefNum: On input, a volume specification for the volume containing the file or directory. This can be a volume reference number, a drive number, or 0 for the default volume.
ioDirID: On input, the directory ID of the file or directory’s parent directory.
newRef: On input, a pointer to an FSRef structure. On output, this FSRef refers to the specified file or directory.

To obtain an FSSpec from an FSRef, use the PBGetCatalogInfoSync function.

Availability

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

Declared In

Files.h

PBReadAsync

Reads any number of bytes from an open file. (Deprecated in Mac OS X v10.5. Use PBReadForkAsync instead.)

OSErr PBReadAsync (
   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 for an open file to be read.
ioBuffer: On input, a pointer to a data buffer into which the bytes are read.
ioReqCount: On input, the number of bytes requested. The value that you pass in this field should be greater than zero.
ioActCount: On output, the number of bytes actually read.
ioPosMode: On input, the positioning mode.
ioPosOffset: On input, the positioning offset. On output, the new position of the mark.

This function attempts to read ioReqCount bytes from the open file whose access path is specified in the ioRefNum field and transfer them to the data buffer pointed to by the ioBuffer field. The position of the mark is specified by ioPosMode and ioPosOffset. If your application tries to read past the logical end-of-file, PBReadAsync reads the data, moves the mark to the end-of-file, and returns eofErr as its function result. Otherwise, PBReadAsync moves the file mark to the byte following the last byte read and returns noErr.

You can specify that PBReadAsync read the file data 1 byte at a time until the requested number of bytes have been read or until the end-of-file is reached. To do so, set bit 7 of the ioPosMode field. Similarly, you can specify that PBReadAsync should stop reading data when it reaches an application-defined newline character. To do so, place the ASCII code of that character into the high-order byte of the ioPosMode field; you must also set bit 7 of that field to enable newline mode.

When reading data in newline mode, PBReadAsync returns the newline character as part of the data read and sets ioActCount to the actual number of bytes placed into the buffer (which includes the newline character).

Availability

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

Declared In

Files.h

PBReadSync

Reads any number of bytes from an open file. (Deprecated in Mac OS X v10.5. Use PBReadForkSync instead.)

OSErr PBReadSync (
   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:

ioRefNum: On input, a file reference number for an open file to be read.
ioBuffer: On input, a pointer to a data buffer into which the bytes are read.
ioReqCount: On input, the number of bytes requested. The value that you pass in this field should be greater than zero.
ioActCount: On output, the number of bytes actually read.
ioPosMode: On input, the positioning mode.
ioPosOffset: On input, the positioning offset. On output, the new position of the mark.

This function attempts to read ioReqCount bytes from the open file whose access path is specified in the ioRefNum field and transfer them to the data buffer pointed to by the ioBuffer field. The position of the mark is specified by ioPosMode and ioPosOffset. If your application tries to read past the logical end-of-file, PBReadSync reads the data, moves the mark to the end-of-file, and returns eofErr as its function result. Otherwise, PBReadSync moves the file mark to the byte following the last byte read and returns noErr.

You can specify that PBReadSync read the file data 1 byte at a time until the requested number of bytes have been read or until the end-of-file is reached. To do so, set bit 7 of the ioPosMode field. Similarly, you can specify that PBReadSync should stop reading data when it reaches an application-defined newline character. To do so, place the ASCII code of that character into the high-order byte of the ioPosMode field; you must also set bit 7 of that field to enable newline mode.

When reading data in newline mode, PBReadSync returns the newline character as part of the data read and sets ioActCount to the actual number of bytes placed into the buffer (which includes the newline character).

Availability

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

Declared In

Files.h

PBResolveFileIDRefAsync

Retrieves the filename and parent directory ID of a file given its file ID. (Deprecated in Mac OS X v10.5. Use FSGetCatalogInfo instead.)

OSErr PBResolveFileIDRefAsync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to an FIDParam variant of the HFS parameter block. See HParamBlockRec for more information on the HParamBlockRec data type.

Return Value

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

Discussion

Most applications do not need to use this function. In general, you should track files using alias records, as described in the Alias Manager documentation. The Alias Manager uses file IDS internally as part of its search algorithms for finding the target of an alias record.

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. A return code of fidNotFound means that the specified file ID reference has become invalid, either because the file was deleted or because the file ID reference was destroyed by PBDeleteFileIDRefSync or PBDeleteFileIDRefAsync.
ioNamePtr: On input, a pointer to a pathname. If the name string is NULL, PBResolveFileIDRefAsync doe s not return the filename, but returns only the parent directory ID of the file in the ioSrcDirID field. If the name string is not NULL but is only a volume name, PBResolveFileIDRefAsync ignores the value in the ioVRefNum field and uses the volume name instead. On output, a pointer to the filename for the file with the given file ID.
ioVRefNum: On input, a volume specification for the volume containing the file. This field can contain a volume reference number, a drive number, or 0 for the default volume.
ioSrcDirID: On output, the file’s parent directory ID.
ioFileID: On input, a file ID for the file to retrieve information about.

Availability

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

Declared In

Files.h

PBResolveFileIDRefSync

Retrieves the filename and parent directory ID of a file given its file ID. (Deprecated in Mac OS X v10.5. Use FSGetCatalogInfo instead.)

OSErr PBResolveFileIDRefSync (
   HParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to an FIDParam variant of the HFS parameter block. See HParamBlockRec for more information on the HParamBlockRec data type.

Return Value

A result code. See “File Manager Result Codes.” A return code of fidNotFound means that the specified file ID reference has become invalid, either because the file was deleted or because the file ID reference was destroyed by PBDeleteFileIDRefSync or PBDeleteFileIDRefAsync.

Discussion

The relevant fields of the parameter block are:

ioNamePtr: On input, a pointer to a pathname. If the name string is NULL, PBResolveFileIDRefSync doe s not return the filename, but returns only the parent directory ID of the file in the ioSrcDirID field. If the name string is not NULL but is only a volume name, PBResolveFileIDRefSync ignores the value in the ioVRefNum field and uses the volume name instead. On output, a pointer to the filename of the file with the given file ID.
ioVRefNum: On input, a volume specification for the volume containing the file. This field can contain a volume reference number, drive number, or 0 for the default volume.
ioSrcDirID: On output, the file’s parent directory ID.
ioFileID: On input, a file ID for the file to retrieve information about.

Availability

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

Declared In

Files.h

PBVolumeMount

Mounts a volume. (Deprecated in Mac OS X v10.5. Use FSVolumeMount instead.)

OSErr PBVolumeMount (
   ParmBlkPtr paramBlock
);

Parameters

paramBlock: A pointer to the IOParam variant of the basic File Manager 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:

ioVRefNum: On output, a volume reference number for the mounted volume.
ioBuffer: On input, a pointer to mounting information. You can use the volume mounting information returned by the PBGetVolMountInfo function or you can use a volume mounting information structure filled in by your application. If you’re mounting an AppleShare volume, place the volume’s AFP mounting information structure in the buffer pointed to by the ioBuffer field.

This function allows your application to record the mounting information for a volume and then to mount the volume later.

The PBGetVolMountInfo function does not return the user and volume passwords they’re returned blank. Typically, your application asks the user for any necessary passwords and fills in those fields just before calling PBVolumeMount. If you want to mount a volume with guest status, pass an empty string as the user password.

If you have enough information about the volume, you can fill in the mounting structure yourself and call PBVolumeMount, even if you did not save the mounting information while the volume was mounted. To mount an AFP volume, you must fill in the structure with at least the zone name, server name, user name, user password, and volume password. You can lay out the fields in any order within the data field, as long as you specify the correct offsets.

In general, it is easier to mount remote volumes by creating and then resolving alias records that describe those volumes. The Alias Manager displays the standard user interface for user authentication when resolving alias records for remote volumes. As a result, this function is primarily of interest for applications that need to mount remote volumes with no user interface or with some custom user interface.

Special Considerations

AFP volumes currently ignore the user authentication method passed in the uamType field of the volume mounting information structure whose address is passed in the ioBuffer field of the parameter block. The most secure available method is used by default, except when a user mounts the volume as Guest and uses the kNoUserAuthentication authentication method.

This function executes synchronously. You should not call it at interrupt time.

Version Notes

The File Sharing workstation software introduced in system software version 7.0 does not currently pass the volume password. The AppleShare 3.0 workstation software does, however, pass the volume password.

Availability

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

Declared In

Files.h

PBWaitIOComplete

Keeps the system idle until either an interrupt occurs or the specified timeout value is reached. (Deprecated in Mac OS X v10.5. There is no replacement function.)

OSErr PBWaitIOComplete (
   ParmBlkPtr paramBlock,
   Duration timeout
);

Parameters

paramBlock: A pointer to a basic File Manager parameter block.
timeout: The maximum length of time you want the system to be kept idle.

Return Value

A result code. If the timeout value is reached, returns kMPTimeoutErr.

Special Considerations

This function is not implemented in Mac OS X.

Availability

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

Declared In

Files.h

PBWriteAsync

Writes any number of bytes to an open file. (Deprecated in Mac OS X v10.5. Use PBWriteForkAsync instead.)

OSErr PBWriteAsync (
   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 for the open file to which to write.
ioBuffer: On input, a pointer to a data buffer containing the bytes to write.
ioReqCount: On input, the number of bytes requested.
ioActCount: On output, the number of bytes actually written.
ioPosMode: On input, the positioning mode.
ioPosOffset: On input, the positioning offset. On output, the new position of the mark.

The PBWriteAsync function takes ioReqCount bytes from the buffer pointed to by ioBuffer and attempts to write them to the open file whose access path is specified by ioRefNum. The position of the mark is specified by ioPosMode and ioPosOffset. If the write operation completes successfully, PBWriteAsync moves the file mark to the byte following the last byte written and returns noErr. If you try to write past the logical end-of-file, PBWriteAsync moves the logical end-of-file. If you try to write past the physical end-of-file, PBWriteAsync adds one or more clumps to the file and moves the physical end-of-file accordingly.

Availability

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

Declared In

Files.h

PBWriteSync

Writes any number of bytes to an open file. (Deprecated in Mac OS X v10.5. Use PBWriteForkSync instead.)

OSErr PBWriteSync (
   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:

ioRefNum: On input, a file reference number for the open file to which to write.
ioBuffer: On input, a pointer to a data buffer containing the bytes to write.
ioReqCount: On input, the number of bytes requested.
ioActCount: On output, the number of bytes actually written.
ioPosMode: On input, the positioning mode.
ioPosOffset: On input, the positioning offset. On output, the new position of the mark.

The PBWriteSync function takes ioReqCount bytes from the buffer pointed to by ioBuffer and attempts to write them to the open file whose access path is specified by ioRefNum. The position of the mark is specified by ioPosMode and ioPosOffset. If the write operation completes successfully, PBWriteSync moves the file mark to the byte following the last byte written and returns noErr. If you try to write past the logical end-of-file, PBWriteSync moves the logical end-of-file. If you try to write past the physical end-of-file, PBWriteSync adds one or more clumps to the file and moves the physical end-of-file accordingly.

Availability

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

Declared In

Files.h

< Previous PageNext Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.