Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 1 - Resource Manager / Resource Manager Reference

Resource Manager Routines / Opening Resource Forks

OpenRFPerm

If the FSpOpenResFile and HOpenResFile functions are not available, you can use the OpenRFPerm function to open a file's resource fork.

FUNCTION OpenRFPerm (fileName: Str255; vRefNum: Integer; 
                     permission: SignedByte): Integer;

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 for one of the read/write permission combinations.

DESCRIPTION

The OpenRFPerm function opens the resource fork of the file with the name specified by the fileName parameter in the directory or volume specified by the vRefNum parameter. It also makes this file the current resource file.

In addition to opening the resource fork for the file with the specified name, OpenRFPerm lets you specify in the permission parameter the read/write permission of the resource fork the first time it is opened.

You can use the OpenRFPerm 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 OpenRFPerm is an earlier version of the HOpenResFile function.

You can specify the access path permission for the resource fork by setting the permission parameter to one of these constants:

CONST
   fsCurPerm    = 0; {whatever is currently allowed}
   fsRdPerm     = 1; {read-only permission}
   fsWrPerm     = 2; {write permission}
   fsRdWrPerm   = 3; {exclusive read/write permission}
   fsRdWrShPerm = 4; {shared read/write permission}

See page 1-55 for information about specifying access path permission with FSpOpenResFile. The same information applies to OpenRFPerm.

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.

The OpenRFPerm function returns a 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 routines. If the file's resource fork is already open, OpenRFPerm returns the file reference number but does not make that file the current resource file.

If the OpenRFPerm 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.

You don't have to call OpenRFPerm 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 OpenRFPerm function checks that the information in the resource map is internally consistent. If it isn't, ResError returns the result code mapReadErr.

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

The OpenRFPerm function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

It's possible to create multiple, unique, read-only access paths to a resource fork using OpenRFPerm; however, you should avoid doing so. See page 1-56 for discussion of this issue in relation to FSpOpenResFile; OpenRFPerm works the same way.

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

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 OpenRFPerm with calls to SetResLoad 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 (page 1-56) also applies to OpenRFPerm.

ASSEMBLY-LANGUAGE INFORMATION

A handle to the resource map for the most recently opened resource fork is stored in the global variable TopMapHndl.

RESULT CODES

noErr	0	No error
nsvErr	-35	No such volume
ioErr	-36	I/O error
bdNamErr	-37	Bad filename or volume name (perhaps zero length)
eofErr	-39	End of file
tmfoErr	-42	Too many files open
fnfErr	-43	File not found
opWrErr	-49	File already open with write permission
permErr	-54	Attempt to open locked file for writing
extFSErr	-58	Volume belongs to an external file system
memFullErr	-108	Not enough room in heap zone
dirNFErr	-120	Directory not found
mapReadErr	-199	Map inconsistent with operation

SEE ALSO

To check for errors, call the ResError function as described on page 1-47.

For more information about permission parameter constants and the OpenRF function, see Inside Macintosh: Files.