Legacy Document

Inside Macintosh: Files /

Chapter 2 - File Manager / File Manager Reference

Shared Environment Routines / Locking and Unlocking File Ranges

PBLockRange

You can use the PBLockRange function to lock a portion of a file.

FUNCTION PBLockRange (paramBlock: ParmBlkPtr; async: Boolean): 
                        OSErr;

paramBlock

A pointer to a basic File Manager 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.
-->	ioRefNum	Integer	A file reference number.
-->	ioReqCount	LongInt	The number of bytes in the range.
-->	ioPosMode	Integer	The positioning mode.
-->	ioPosOffset	LongInt	The positioning offset.

DESCRIPTION

The PBLockRange 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. Set ioReqCount to -1 to lock the maximum number of bytes from the position specified in ioPosOffset.

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

When you're finished with the data (typically after a call to PBWrite), be sure to call PBUnlockRange to free that portion of the file for subsequent PBRead calls.

SPECIAL CONSIDERATIONS

The PBLockRange 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. See "Locking and Unlocking File Ranges" on page 2-50 for a simple way to determine whether calling PBLockRange on an open file would in fact lock a range of bytes.

WARNING

In system software versions 6.0.7 and earlier, specifying ioPosMode as fsFromLEOF results in the wrong byte range being locked.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for PBLockRange are

Trap macro	Selector
_HFSDispatch	$0010

RESULT CODES

noErr	0	No error
ioErr	-36	I/O error
fnOpnErr	-38	File not open
eofErr	-39	Logical end-of-file reached
fLckdErr	-45	File is locked by another user
paramErr	-50	Negative ioReqCount
rfNumErr	-51	Bad reference number
extFSErr	-58	External file system
volGoneErr	-124	Server volume has been disconnected
afpNoMoreLocks	-5015	No more ranges can be locked
afpRangeOverlap	-5021	Part of range is already locked