Legacy Document

Inside Macintosh: Files /

Chapter 2 - File Manager / File Manager Reference

Low-Level HFS Routines / Opening Files

PBHOpen

You can use the PBHOpen function to open the data fork of a file. Because PBHOpen will also open devices, it's safer to use the PBHOpenDF function instead.

FUNCTION PBHOpen (paramBlock: HParmBlkPtr; async: Boolean): OSErr;

paramBlock

A pointer to a basic HFS parameter block.

async

A Boolean value that specifies asynchronous (TRUE) or synchronous (FALSE) execution.

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The result code of the function.
-->	ioNamePtr	StringPtr	A pointer to a pathname.
-->	ioVRefNum	Integer	A volume specification.
<--	ioRefNum	Integer	A file reference number.
-->	ioPermssn	SignedByte	The read/write permission.
-->	ioDirID	LongInt	A directory ID.

DESCRIPTION

The PBHOpen function creates an access path to the data fork of the specified file and returns a file reference number in the ioRefNum field.

You can open a path for writing even if it accesses a file on a locked volume, and no error is returned until a PBWrite, PBSetEOF, or PBAllocate call is made.

If you attempt to open a locked file for writing, PBHOpen returns the result code permErr. If you request exclusive read/write permission but another access path is already open, PBHOpen returns the reference number of the existing access path in ioRefNum and opWrErr as its function result. You should not use this reference number unless your application originally opened the file.

WARNING

If you use PBHOpen 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 PBHOpenDF instead
of PBHOpen.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro for PBHOpen is _HOpen.

RESULT CODES

noErr	0	No error
nsvErr	-35	No such volume
ioErr	-36	I/O error
bdNamErr	-37	Bad filename
tmfoErr	-42	Too many files open
fnfErr	-43	File not found
opWrErr	-49	File already open for writing
permErr	-54	Attempt to open locked file for writing
dirNFErr	-120	Directory not found or incomplete pathname
afpAccessDenied	-5000	User does not have the correct access to the file