Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

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.
-->ioCompletionProcPtrA pointer to a completion routine.
<--ioResultOSErrThe result code of the function.
-->ioRefNumIntegerA file reference number.
-->ioReqCountLongIntThe number of bytes in the range.
-->ioPosModeIntegerThe positioning mode.
-->ioPosOffsetLongIntThe 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 macroSelector
_HFSDispatch$0010

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

Previous Book Contents Book Index Next

© Apple Computer, Inc.
2 JUL 1996