---

Deprecated Resource Manager Functions

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

Deprecated in Mac OS X v10.5

FSpCreateResFile

Creates an empty resource fork in a new or existing file. (Deprecated in Mac OS X v10.5. Use FSCreateResourceFile instead.)

void FSpCreateResFile (
   const FSSpec *spec,
   OSType creator,
   OSType fileType,
   ScriptCode scriptTag
);

Discussion

This function is not recommended. You should use a file’s data fork instead of its resource fork to store resource data.

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

Resources.h

FSpOpenOrphanResFile

Opens a resource file that is persistent across all contexts. (Deprecated in Mac OS X v10.5. Use FSOpenOrphanResFile instead.)

OSErr FSpOpenOrphanResFile (
   const FSSpec *spec,
   SignedByte permission,
   ResFileRefNum *refNum
);

Return Value

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

Discussion

FSpOpenOrphanResFile should be used to open a resource file that is persistent across all contexts. FSpOpenOrphanResFile loads everything into the system context and detaches the file from the context in which it was opened. If the file is already in the resource chain and a new instance is not opened, FSpOpenOrphanResFile will return a paramErr. Use this function with care, as it can and will fail if the map is very large or a lot of resources are preloaded.

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

Resources.h

FSpOpenResFile

Opens the resource fork in a file specified with an FSSpec structure. (Deprecated in Mac OS X v10.5. Use FSOpenResourceFile instead.)

ResFileRefNum FSpOpenResFile (
   const FSSpec *spec,
   SignedByte permission
);

Parameters

spec

A pointer to a file system specification record specifying the name and location of the file whose resource fork is to be opened. This function also makes the specified file the current resource file.

permission

A constant indicating the type of access with which to open the resource fork. For a description of the types of access you can request, see File Access Permission Constants in File Manager Reference.

Return Value

The file reference number for the resource fork. If the file reference number returned is greater than 0, you can use this number to refer to the resource fork in some other Resource Manager functions.

If you attempt to use this function to open a resource fork that is already open, it returns the existing file reference number or a new one, depending on the access permission for the existing access path. For example, your application receives a new file reference number after a successful request for read-only access to a file previously opened with write access, whereas it receives the same file reference number in response to a second request for write access to the same file. In this case, the function doesn’t make that file the current resource file.

If the function fails to open the specified file’s resource fork (for instance, because there’s no file with the given file system specification record or because there are permission problems), it returns –1 as the file reference number. Use the ResError function to determine what kind of error occurred.

If an application attempts to open a second access path with write access and the application is different from the one that originally opened the resource fork, FSpOpenResFile returns –1, and the ResError function returns the result code opWrErr.

Discussion

This function is available only in System 7 and later versions of system software. You can determine whether FSpOpenResFile is available by calling the Gestalt function with the gestaltFSAttr selector code. If this function is not available to your application, you can use HOpenResFile, OpenRFPerm, or OpenResFile instead. The HOpenResFile function is preferred if FSpOpenResFile is not available. The OpenRFPerm function is an earlier version of HOpenResFile that is still supported but is more restricted in its capabilities.

The Resource Manager reads the resource map from the specified file’s resource fork into memory. It also reads into memory every resource in the resource fork whose resPreload attribute is set.

You don’t have to call this function to open the System file’s resource fork or an application file’s resource fork. These resource forks are opened automatically when the system and the application start up, respectively. To get the file reference number for your application, call the CurResFile function after your application starts up and before you open any other resource forks.

The FSpOpenResFile function checks that the information in the resource map is internally consistent. If it isn’t, ResError returns the result code mapReadErr.

It’s possible to create multiple, unique, read-only access paths to a resource fork using this function however, you should avoid doing so. If a resource fork is opened twice—once with read/write permission and once with read-only permission—two copies of the resource map exist in memory. If you change one of the resources in memory using one of the resource maps, the two resource maps become inconsistent and the file will appear damaged to the second resource map.

If you must use this technique for read-only access, call this function immediately before your application reads information from the file and close the file immediately afterward. Otherwise, your application may get unexpected results.

If you want to open the resource fork for another application (or any resource fork other than your application’s that includes 'CODE' resources), you must bracket your calls to this function with calls to the SetResLoad function with the load parameter set to FALSE and then to TRUE. You must also avoid making intersegment calls while the other application’s resource fork is open. If you don’t do this, the Segment Loader Manager treats any preloaded 'CODE' resources as your code resources when you make an intersegment call that triggers a call to the LoadSeg function while the other application is first in the resource chain. In this case, your application can begin executing the other application’s code, and severe problems will ensue. If you need to get 'CODE' resources from the other application’s resource fork, you can still prevent the Segment Loader Manager problem by calling the UseResFile function with your application’s file reference number to make your application the current resource file.

To open a resource fork just for block-level operations, such as copying files without reading the resource map into memory, use the File Manager function OpenRF.

Special Considerations

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.5.
• Not available to 64-bit applications.

Related Sample Code

• Simple DrawSprocket

Declared In

Resources.h

FSpResourceFileAlreadyOpen

Checks whether a resource file is open. (Deprecated in Mac OS X v10.5. Use FSResourceFileAlreadyOpen instead.)

Boolean FSpResourceFileAlreadyOpen (
   const FSSpec *resourceFile,
   Boolean *inChain,
   ResFileRefNum *refNum
);

Parameters

resourceFile

The resource file to check.

inChain

A pointer to a variable allocated by the caller. On return, true if the resource file is in the resource chain, false otherwise.

refNum

A pointer to a variable allocated by the caller. On return, the reference number of the file if it is open.

Return Value

This function returns true if the resource file is already open and known by the Resource Manager—for example, it is either in the current resource chain or it is a detached resource file.

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

Resources.h

HCreateResFile

Creates an empty resource fork, when the FSpCreateResFile function is not available. (Deprecated in Mac OS X v10.5. Use FSCreateResourceFile instead.)

void HCreateResFile (
   FSVolumeRefNum vRefNum,
   long dirID,
   ConstStr255Param fileName
);

Discussion

This function is not recommended. You should use a file’s data fork instead of its resource fork to store resource data.

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

Resources.h

HOpenResFile

Opens a file’s resource fork, when the FSpOpenResFile function is not available. (Deprecated in Mac OS X v10.5. Use FSOpenResourceFile instead.)

ResFileRefNum HOpenResFile (
   FSVolumeRefNum vRefNum,
   long dirID,
   ConstStr255Param fileName,
   SInt8 permission
);

Parameters

vRefNum

The volume reference number of the volume on which the file is located.

dirID

The directory ID of the directory where the file is located.

fileName

The name of the file whose resource fork is to be opened.

permission

A constant indicating the type of access with which to open the resource fork. For a description of the types of access you can request, see File Access Permission Constants in File Manager Reference.

Return Value

The file reference number for the file. You can use this file reference number to refer to the file in other Resource Manager functions. The function also makes this file the current resource file. If the file’s resource fork is already open, the function returns the file reference number but does not make that file the current resource file. If the function fails to open the specified file’s resource fork (because there’s no file with the specified name or because there are permission problems), it returns –1 as the file reference number. Use the ResError function to determine what kind of error occurred.

Versions of system software before System 7 do not allow you to use this function to open a second access path, with write access, to a resource fork. In this case, the function returns the reference number already assigned to the file.

Discussion

The Resource Manager reads the resource map from the resource fork of the specified file into memory. It also reads into memory every resource whose resPreload attribute is set.

You don’t have to call this function to open the System file’s resource fork or an application file’s resource fork. These files are opened automatically when the system and the application start up, respectively. To get the file reference number for your application, call the CurResFile function after the application starts up and before you open the resource forks for any other files.

The HOpenResFile function checks that the information in the resource map is internally consistent. If it isn’t, ResError returns the result code mapReadErr. It’s possible to create multiple, unique, read-only access paths to a resource fork using HOpenResFile; however, you should avoid doing so, to prevent inconsistencies between multiple copies of the resource map. See the discussion of this issue in relation to FSpOpenResFile. The HOpenResFile function works the same way.

To open a resource fork just for block-level operations, such as copying files without reading the resource map into memory, use the File Manager function OpenRF.

If you want to open the resource fork for another application (or any resource fork other than your application’s that includes 'CODE' resources), you must bracket your calls to HOpenResFile with calls to the SetResLoad function with the load parameter set to FALSE and then to TRUE. You must also avoid making intersegment calls while the other application’s resource fork is open. The discussion of this issue in relation to FSpOpenResFile also applies to HOpenResFile.

Special Considerations

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.5.
• Not available to 64-bit applications.

Declared In

Resources.h

OpenRFPerm

Opens a file’s resource fork, when the FSpOpenResFile and HOpenResFile functions are not available. (Deprecated in Mac OS X v10.5. Use FSOpenResourceFile instead.)

ResFileRefNum OpenRFPerm (
   ConstStr255Param fileName,
   FSVolumeRefNum vRefNum,
   SInt8 permission
);

Parameters

fileName

The name of the file whose resource fork is to be opened.

vRefNum

The volume reference number or directory ID for the volume or directory in which the file is located.

permission

A constant indicating the type of access with which to open the resource fork. For a description of the types of access you can request, see File Access Permission Constants in File Manager Reference.

Return Value

The file reference number for the file whose resource fork it has opened. You can use this file reference number to refer to the file in other Resource Manager functions. The function also makes this file the current resource file. If the file’s resource fork is already open, the function returns the file reference number but does not make that file the current resource file.

If the function fails to open the specified file’s resource fork (because there’s no file with the given name or because there are permission problems), it returns –1 as the file reference number. Use the ResError function to determine what kind of error occurred.

Versions of system software before System 7 do not allow you to use this function to open a second access path, with write access, to a resource fork. In this case, the function returns the reference number already assigned to the file.

Discussion

You can use this function if the FSpOpenResFile function is not available. You can determine whether FSpOpenResFile is available by calling the Gestalt function with the gestaltFSAttr selector code. The HOpenResFile function allows you to specify both a directory ID and a volume reference number, and is therefore preferred if FSpOpenResFile is not available. The OpenRFPerm is an earlier versions of HOpenResFile that is still supported but is more restricted in its capabilities.

The Resource Manager reads the resource map from the resource fork for the specified file into memory. It also reads into memory every resource in the resource fork whose resPreload attribute is set.

You don’t have to call this function to open the System file’s resource fork or an application file’s resource fork. These files are opened automatically when the system and the application start up, respectively. To get the file reference number for your application, call the CurResFile function after the application starts up and before you open the resource forks for any other files.

This function checks that the information in the resource map is internally consistent. If it isn’t, ResError returns the result code mapReadErr. It’s possible to create multiple, unique, read-only access paths to a resource fork using this function however, you should avoid doing so, to prevent inconsistencies between multiple copies of the resource map.

To open a resource fork just for block-level operations, such as copying files without reading the resource map into memory, use the File Manager function OpenRF.

If you want to open the resource fork for another application (or any resource fork other than your application’s that includes 'CODE' resources), you must bracket your calls to this function with calls to the SetResLoad function with the load parameter set to FALSE and then to TRUE. You must also avoid making intersegment calls while the other application’s resource fork is open.

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

Resources.h

---