PBRenameSync
PBRename Rename a file, volume, or directory
#include <Files.h> File Manager (PBxxx)
OSErr PBRename(pb, async ); Boolean async ; 0=await completion; 1=immediate return PBRename changes the name of a file or volume. It does NOT move a file
from one directory to another (use PBCatMove for that).
pb is the address of a 50-byte IOParam structure. The relevant fields are as follows:
Out-In Name Type Size Offset Description
-> ioCompletion ProcPtr 4 12 Completion routine address (if async =TRUE) -> ioNamePtr StringPtr 4 18 Address of current filename -> ioVRefNum short 2 22 Volume, drive, or directory reference
-> ioRefNum short 2 24 File reference number
-> ioVersNum SignedByte 1 26 Version of file to rename (use 0 on HFS) -> ioMisc Ptr 4 28 Address of desired new filename <- ioResult OSErr 2 16 Error Code (0=no error, 1=not done yet) async is a Boolean value. Use FALSE for normal (synchronous) operation or TRUE to enqueue the request and resume control immediately. See Async I/O.
noErr (0) No error
bdNamErr (-37) Bad name
dirFulErr (-33) Directory full
dupFNErr (-48) Duplicate filename (new name already exists)
extFSErr (-58) External file system
fLckdErr (-45) File is locked
fnfErr (-43) File not found
fsRnErr (-59) File system rename error
ioErr (-36) I/O error
nsvErr (-35) No such volume
paramErr (-50) No default volume
vLckdErr (-46) Volume is locked
wPrErr (-44) Diskette is write-protected
Notes: PBRename works equally well for changing the name of a file, a volume
or directory name.
To Change the Name of a File
1 Set ioNamePtr to point to a pascal-style string of the file's current name.
2 Set ioVRefNum to the volume in which the file resides (0 for the default
volume, or use a working directory number as returned from Standard File
or PBOpenWD).
3 Set ioMisc to point to a pascal-style string of the desired new name for
the file. If ioNamePtr is a multiple-name pathname, the new name must
also describe a file in the same directory.
/* --- using single-name filenames ---
*/
pb.ioVRefNum = theVolNum; /* volume of old and new */
pb.ioMisc = "\pSmith";
rc = PBRename( &pb, FALSE ); /* --- using multiple-name filenames ---
*/
pb.ioNamePtr = (StringPtr) "\pHardDisk:Letters:1988:Jones"; pb.ioVRefNum = 0; /* ignored; we used null pathname above */
pb.ioMisc = (Ptr)"\pHardDisk:Letters:1988:Smith";
rc = PBRename( &pb, FALSE ); To Change the Name of a Volume or Directory
1 Set ioNamePtr to point to a pascal-style string of the current name of the
volume (or directory). If ioVRefNum identifies the volume fully,
ioNamePtr may be set to NIL.
2 Set ioVRefNum to the volume reference number (0 for the default volume,
or a working directory number as returned from Standard File or
PBOpenWD). If ioNamePtr identifies the volume fully, ioVRefNum is
ignored.
3 Set ioMisc to point to a pascal-style string of the desired new name for
the volume.
/* --- renaming a directory ---
*/
pb.ioNamePtr = (StringPtr)"\pHardDisk:Letters:"; pb.ioVRefNum = 0; [TOKEN:12074] ignored in this example */
pb.ioMisc = (Ptr)"\pHardDisk:Ltrs:";
rc = PBRename( &pb, FALSE ); PBRename cannot move a file to a different directory (use PBCatMove
if you need to do that). Use PBSetFInfo to modify other file de scriptive information. The high-level version of this function is Rename. The HFS-specific version is PBHRename.