4 Contains: A collection of useful high-level File Manager routines
5 which use the HFS Plus APIs wherever possible.
7 Version: MoreFilesX 1.0.1
9 Copyright: © 1992-2002 by Apple Computer, Inc., all rights reserved.
11 Disclaimer: IMPORTANT: This Apple software is supplied to you by Apple Computer, Inc.
12 ("Apple") in consideration of your agreement to the following terms, and your
13 use, installation, modification or redistribution of this Apple software
14 constitutes acceptance of these terms. If you do not agree with these terms,
15 please do not use, install, modify or redistribute this Apple software.
17 In consideration of your agreement to abide by the following terms, and subject
18 to these terms, Apple grants you a personal, non-exclusive license, under AppleÕs
19 copyrights in this original Apple software (the "Apple Software"), to use,
20 reproduce, modify and redistribute the Apple Software, with or without
21 modifications, in source and/or binary forms; provided that if you redistribute
22 the Apple Software in its entirety and without modifications, you must retain
23 this notice and the following text and disclaimers in all such redistributions of
24 the Apple Software. Neither the name, trademarks, service marks or logos of
25 Apple Computer, Inc. may be used to endorse or promote products derived from the
26 Apple Software without specific prior written permission from Apple. Except as
27 expressly stated in this notice, no other rights or licenses, express or implied,
28 are granted by Apple herein, including but not limited to any patent rights that
29 may be infringed by your derivative works or by other works in which the Apple
30 Software may be incorporated.
32 The Apple Software is provided by Apple on an "AS IS" basis. APPLE MAKES NO
33 WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED
34 WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
35 PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN
36 COMBINATION WITH YOUR PRODUCTS.
38 IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR
39 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
40 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
41 ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION
42 OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT
43 (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN
44 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
48 DRI: Apple Macintosh Developer Technical Support
50 Other Contact: For bug reports, consult the following page on
52 http://developer.apple.com/bugreporter/
54 Technology: DTS Sample Code
60 Change History (most recent first):
62 <3> 4/19/02 JL [2853905] Fixed #if test around header includes.
63 <2> 4/19/02 JL [2853901] Updated standard disclaimer.
64 <1> 1/25/02 JL MoreFilesX 1.0
67 What do those arrows in the documentation for each routine mean?
69 --> The parameter is an input
71 <-- The parameter is an output. The pointer to the variable
72 where the output will be returned (must not be NULL).
74 <** The parameter is an optional output. If it is not a
75 NULL pointer, it points to the variable where the output
76 will be returned. If it is a NULL pointer, the output will
77 not be returned and will possibly let the routine and the
78 File Manager do less work. If you don't need an optional output,
80 **> The parameter is an optional input. If it is not a
81 NULL pointer, it points to the variable containing the
82 input data. If it is a NULL pointer, the input is not used
83 and will possibly let the routine and the File Manager
87 #ifndef __MOREFILESX__
88 #define __MOREFILESX__
92 #include <Carbon/Carbon.h>
110 #if PRAGMA_STRUCT_ALIGN
111 #pragma options align=mac68k
112 #elif PRAGMA_STRUCT_PACKPUSH
113 #pragma pack(push, 2)
114 #elif PRAGMA_STRUCT_PACK
118 /*****************************************************************************/
121 #pragma mark ----- FinderInfo and ExtendedFinderInfo -----
125 * FSGetFinderInfo and FSSetFinderInfo use these unions for Finder information.
133 typedef union FinderInfo FinderInfo;
135 union ExtendedFinderInfo
137 ExtendedFileInfo file;
138 ExtendedFolderInfo folder;
140 typedef union ExtendedFinderInfo ExtendedFinderInfo;
142 /*****************************************************************************/
144 #pragma mark ----- GetVolParmsInfoBuffer Macros -----
147 * Macros to get information out of GetVolParmsInfoBuffer.
150 /* version 1 field getters */
151 #define GetVolParmsInfoVersion(volParms) \
152 ((volParms)->vMVersion)
153 #define GetVolParmsInfoAttrib(volParms) \
154 ((volParms)->vMAttrib)
155 #define GetVolParmsInfoLocalHand(volParms) \
156 ((volParms)->vMLocalHand)
157 #define GetVolParmsInfoServerAdr(volParms) \
158 ((volParms)->vMServerAdr)
160 /* version 2 field getters (assume zero result if version < 2) */
161 #define GetVolParmsInfoVolumeGrade(volParms) \
162 (((volParms)->vMVersion >= 2) ? (volParms)->vMVolumeGrade : 0)
163 #define GetVolParmsInfoForeignPrivID(volParms) \
164 (((volParms)->vMVersion >= 2) ? (volParms)->vMForeignPrivID : 0)
166 /* version 3 field getters (assume zero result if version < 3) */
167 #define GetVolParmsInfoExtendedAttributes(volParms) \
168 (((volParms)->vMVersion >= 3) ? (volParms)->vMExtendedAttributes : 0)
170 /* attribute bits supported by all versions of GetVolParmsInfoBuffer */
171 #define VolIsNetworkVolume(volParms) \
172 ((volParms)->vMServerAdr != 0)
173 #define VolHasLimitFCBs(volParms) \
174 (((volParms)->vMAttrib & (1L << bLimitFCBs)) != 0)
175 #define VolHasLocalWList(volParms) \
176 (((volParms)->vMAttrib & (1L << bLocalWList)) != 0)
177 #define VolHasNoMiniFndr(volParms) \
178 (((volParms)->vMAttrib & (1L << bNoMiniFndr)) != 0)
179 #define VolHasNoVNEdit(volParms) \
180 (((volParms)->vMAttrib & (1L << bNoVNEdit)) != 0)
181 #define VolHasNoLclSync(volParms) \
182 (((volParms)->vMAttrib & (1L << bNoLclSync)) != 0)
183 #define VolHasTrshOffLine(volParms) \
184 (((volParms)->vMAttrib & (1L << bTrshOffLine)) != 0)
185 #define VolHasNoSwitchTo(volParms) \
186 (((volParms)->vMAttrib & (1L << bNoSwitchTo)) != 0)
187 #define VolHasNoDeskItems(volParms) \
188 (((volParms)->vMAttrib & (1L << bNoDeskItems)) != 0)
189 #define VolHasNoBootBlks(volParms) \
190 (((volParms)->vMAttrib & (1L << bNoBootBlks)) != 0)
191 #define VolHasAccessCntl(volParms) \
192 (((volParms)->vMAttrib & (1L << bAccessCntl)) != 0)
193 #define VolHasNoSysDir(volParms) \
194 (((volParms)->vMAttrib & (1L << bNoSysDir)) != 0)
195 #define VolHasExtFSVol(volParms) \
196 (((volParms)->vMAttrib & (1L << bHasExtFSVol)) != 0)
197 #define VolHasOpenDeny(volParms) \
198 (((volParms)->vMAttrib & (1L << bHasOpenDeny)) != 0)
199 #define VolHasCopyFile(volParms) \
200 (((volParms)->vMAttrib & (1L << bHasCopyFile)) != 0)
201 #define VolHasMoveRename(volParms) \
202 (((volParms)->vMAttrib & (1L << bHasMoveRename)) != 0)
203 #define VolHasDesktopMgr(volParms) \
204 (((volParms)->vMAttrib & (1L << bHasDesktopMgr)) != 0)
205 #define VolHasShortName(volParms) \
206 (((volParms)->vMAttrib & (1L << bHasShortName)) != 0)
207 #define VolHasFolderLock(volParms) \
208 (((volParms)->vMAttrib & (1L << bHasFolderLock)) != 0)
209 #define VolHasPersonalAccessPrivileges(volParms) \
210 (((volParms)->vMAttrib & (1L << bHasPersonalAccessPrivileges)) != 0)
211 #define VolHasUserGroupList(volParms) \
212 (((volParms)->vMAttrib & (1L << bHasUserGroupList)) != 0)
213 #define VolHasCatSearch(volParms) \
214 (((volParms)->vMAttrib & (1L << bHasCatSearch)) != 0)
215 #define VolHasFileIDs(volParms) \
216 (((volParms)->vMAttrib & (1L << bHasFileIDs)) != 0)
217 #define VolHasBTreeMgr(volParms) \
218 (((volParms)->vMAttrib & (1L << bHasBTreeMgr)) != 0)
219 #define VolHasBlankAccessPrivileges(volParms) \
220 (((volParms)->vMAttrib & (1L << bHasBlankAccessPrivileges)) != 0)
221 #define VolSupportsAsyncRequests(volParms) \
222 (((volParms)->vMAttrib & (1L << bSupportsAsyncRequests)) != 0)
223 #define VolSupportsTrashVolumeCache(volParms) \
224 (((volParms)->vMAttrib & (1L << bSupportsTrashVolumeCache)) != 0)
226 /* attribute bits supported by version 3 and greater versions of GetVolParmsInfoBuffer */
227 #define VolIsEjectable(volParms) \
228 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bIsEjectable)) != 0)
229 #define VolSupportsHFSPlusAPIs(volParms) \
230 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsHFSPlusAPIs)) != 0)
231 #define VolSupportsFSCatalogSearch(volParms) \
232 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsFSCatalogSearch)) != 0)
233 #define VolSupportsFSExchangeObjects(volParms) \
234 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsFSExchangeObjects)) != 0)
235 #define VolSupports2TBFiles(volParms) \
236 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupports2TBFiles)) != 0)
237 #define VolSupportsLongNames(volParms) \
238 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsLongNames)) != 0)
239 #define VolSupportsMultiScriptNames(volParms) \
240 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsMultiScriptNames)) != 0)
241 #define VolSupportsNamedForks(volParms) \
242 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsNamedForks)) != 0)
243 #define VolSupportsSubtreeIterators(volParms) \
244 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsSubtreeIterators)) != 0)
245 #define VolL2PCanMapFileBlocks(volParms) \
246 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bL2PCanMapFileBlocks)) != 0)
247 #define VolParentModDateChanges(volParms) \
248 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bParentModDateChanges)) != 0)
249 #define VolAncestorModDateChanges(volParms) \
250 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bAncestorModDateChanges)) != 0)
251 #define VolSupportsSymbolicLinks(volParms) \
252 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsSymbolicLinks)) != 0)
253 #define VolIsAutoMounted(volParms) \
254 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bIsAutoMounted)) != 0)
256 /*****************************************************************************/
258 #pragma mark ----- userPrivileges Bit Masks and Macros -----
261 * Bit masks and macros to get common information out of userPrivileges byte
262 * returned by FSGetCatalogInfo.
264 * Note: The userPrivileges byte is the same as the ioACUser byte returned
265 * by PBGetCatInfo, and is the 1's complement of the user's privileges
266 * byte returned in ioACAccess by PBHGetDirAccess. That's where the
267 * ioACUser names came from.
269 * The userPrivileges are user's effective privileges based on the
270 * user ID and the groups that user belongs to, and the owner, group,
271 * and everyone privileges for the given directory.
276 /* mask for just the access restriction bits */
277 kioACUserAccessMask = (kioACUserNoSeeFolderMask +
278 kioACUserNoSeeFilesMask +
279 kioACUserNoMakeChangesMask),
280 /* common access privilege settings */
281 kioACUserFull = 0x00, /* no access restiction bits on */
282 kioACUserNone = kioACUserAccessMask, /* all access restiction bits on */
283 kioACUserDropBox = (kioACUserNoSeeFolderMask +
284 kioACUserNoSeeFilesMask), /* make changes, but not see files or folders */
285 kioACUserBulletinBoard = kioACUserNoMakeChangesMask /* see files and folders, but not make changes */
289 /* Macros for testing ioACUser bits. */
291 #define UserIsOwner(userPrivileges) \
292 (((userPrivileges) & kioACUserNotOwnerMask) == 0)
293 #define UserHasFullAccess(userPrivileges) \
294 (((userPrivileges) & (kioACUserAccessMask)) == kioACUserFull)
295 #define UserHasDropBoxAccess(userPrivileges) \
296 (((userPrivileges) & kioACUserAccessMask) == kioACUserDropBox)
297 #define UserHasBulletinBoard(userPrivileges) \
298 (((userPrivileges) & kioACUserAccessMask) == kioACUserBulletinBoard)
299 #define UserHasNoAccess(userPrivileges) \
300 (((userPrivileges) & kioACUserAccessMask) == kioACUserNone)
302 /*****************************************************************************/
304 #pragma mark ----- File Access Routines -----
306 /*****************************************************************************/
308 #pragma mark FSCopyFork
315 ByteCount copyBufferSize);
318 The FSCopyFork function copies all data from the source fork to the
319 destination fork of open file forks and makes sure the destination EOF
320 is equal to the source EOF.
322 srcRefNum --> The source file reference number.
323 dstRefNum --> The destination file reference number.
324 copyBufferPtr --> Pointer to buffer to use during copy. The
325 buffer should be at least 4K-bytes minimum.
326 The larger the buffer, the faster the copy
328 copyBufferSize --> The size of the copy buffer.
331 /*****************************************************************************/
333 #pragma mark ----- Volume Access Routines -----
335 /*****************************************************************************/
337 #pragma mark FSGetVolParms
341 FSVolumeRefNum volRefNum,
343 GetVolParmsInfoBuffer *volParmsInfo,
344 UInt32 *actualInfoSize);
347 The FSGetVolParms function returns information about the characteristics
348 of a volume. A result of paramErr usually just means the volume doesn't
349 support GetVolParms and the feature you were going to check
352 volRefNum --> Volume specification.
353 bufferSize --> Size of buffer pointed to by volParmsInfo.
354 volParmsInfo <-- A GetVolParmsInfoBuffer record where the volume
355 attributes information is returned.
356 actualInfoSize <-- The number of bytes actually returned
361 Also see: The GetVolParmsInfoBuffer Macros for checking attribute bits
365 /*****************************************************************************/
367 #pragma mark FSGetVRefNum
372 FSVolumeRefNum *vRefNum);
375 The FSGetVRefNum function determines the volume reference
376 number of a volume from a FSRef.
379 vRefNum <-- The volume reference number.
382 /*****************************************************************************/
384 #pragma mark FSGetVInfo
388 FSVolumeRefNum volume,
389 HFSUniStr255 *volumeName, /* can be NULL */
390 UInt64 *freeBytes, /* can be NULL */
391 UInt64 *totalBytes); /* can be NULL */
394 The FSGetVInfo function returns the name, available space (in bytes),
395 and total space (in bytes) for the specified volume.
397 volume --> The volume reference number.
398 volumeName <** An optional pointer to a HFSUniStr255.
399 If not NULL, the volume name will be returned in
401 freeBytes <** An optional pointer to a UInt64.
402 If not NULL, the number of free bytes on the
403 volume will be returned in the UInt64.
404 totalBytes <** An optional pointer to a UInt64.
405 If not NULL, the total number of bytes on the
406 volume will be returned in the UInt64.
409 /*****************************************************************************/
411 #pragma mark FSGetVolFileSystemID
414 FSGetVolFileSystemID(
415 FSVolumeRefNum volume,
416 UInt16 *fileSystemID, /* can be NULL */
417 UInt16 *signature); /* can be NULL */
420 The FSGetVolFileSystemID function returns the file system ID and signature
421 of a mounted volume. The file system ID identifies the file system
422 that handles requests to a particular volume. The signature identifies the
423 volume type of the volume (for example, FSID 0 is Macintosh HFS Plus, HFS
424 or MFS, where a signature of 0x4244 identifies the volume as HFS).
425 Here's a partial list of file system ID numbers (only Apple's file systems
428 ----- -----------------------------------------------------
429 $0000 Macintosh HFS Plus, HFS or MFS
430 $0100 ProDOS File System
431 $0101 PowerTalk Mail Enclosures
432 $4147 ISO 9660 File Access (through Foreign File Access)
433 $4242 High Sierra File Access (through Foreign File Access)
434 $464D QuickTake File System (through Foreign File Access)
435 $4953 Macintosh PC Exchange (MS-DOS)
436 $4A48 Audio CD Access (through Foreign File Access)
437 $4D4B Apple Photo Access (through Foreign File Access)
438 $6173 AppleShare (later versions of AppleShare only)
440 See the Technical Note "FL 35 - Determining Which File System
441 Is Active" and the "Guide to the File System Manager" for more
444 volume --> The volume reference number.
445 fileSystemID <** An optional pointer to a UInt16.
446 If not NULL, the volume's file system ID will
447 be returned in the UInt16.
448 signature <** An optional pointer to a UInt16.
449 If not NULL, the volume's signature will
450 be returned in the UInt16.
453 /*****************************************************************************/
455 #pragma mark FSGetMountedVolumes
459 FSRef ***volumeRefsHandle, /* pointer to handle of FSRefs */
460 ItemCount *numVolumes);
463 The FSGetMountedVolumes function returns the list of volumes currently
464 mounted in an array of FSRef records. The array of FSRef records is
465 returned in a Handle, volumeRefsHandle, which is allocated by
466 FSGetMountedVolumes. The caller is responsible for disposing of
467 volumeRefsHandle if the FSGetMountedVolumes returns noErr.
469 volumeRefsHandle <-- Pointer to an FSRef Handle where the array of
470 FSRefs is to be returned.
471 numVolumes <-- The number of volumes returned in the array.
474 /*****************************************************************************/
476 #pragma mark ----- FSRef/FSpec/Path/Name Conversion Routines -----
478 /*****************************************************************************/
480 #pragma mark FSRefMakeFSSpec
488 The FSRefMakeFSSpec function returns an FSSpec for the file or
489 directory specified by the ref parameter.
491 ref --> An FSRef specifying the file or directory.
495 /*****************************************************************************/
497 #pragma mark FSMakeFSRef
501 FSVolumeRefNum volRefNum,
503 ConstStr255Param name,
507 The FSMakeFSRef function creates an FSRef from the traditional
508 volume reference number, directory ID and pathname inputs. It is
509 functionally equivalent to FSMakeFSSpec followed by FSpMakeFSRef.
511 volRefNum --> Volume specification.
512 dirID --> Directory specification.
513 name --> The file or directory name, or NULL.
517 /*****************************************************************************/
519 #pragma mark FSMakePath
525 ConstStr255Param name,
530 The FSMakePath function creates a pathname from the traditional volume reference
531 number, directory ID, and pathname inputs. It is functionally equivalent to
532 FSMakeFSSpec, FSpMakeFSRef, FSRefMakePath.
534 volRefNum --> Volume specification.
535 dirID --> Directory specification.
536 name --> The file or directory name, or NULL.
537 path <-- A pointer to a buffer which FSMakePath will
538 fill with a C string representing the pathname
539 to the file or directory specified. The format of
540 the pathname returned can be determined with the
541 Gestalt selector gestaltFSAttr's
542 gestaltFSUsesPOSIXPathsForConversion bit.
543 If the gestaltFSUsesPOSIXPathsForConversion bit is
544 clear, the pathname is a Mac OS File Manager full
545 pathname in a C string, and file or directory names
546 in the pathname may be mangled as returned by
547 the File Manager. If the
548 gestaltFSUsesPOSIXPathsForConversion bit is set,
549 the pathname is a UTF8 encoded POSIX absolute
550 pathname in a C string. In either case, the
551 pathname returned can be passed back to
552 FSPathMakeRef to create an FSRef to the file or
553 directory, or FSPathMakeFSSpec to craete an FSSpec
554 to the file or directory.
555 maxPathSize --> The size of the path buffer in bytes. If the path
556 buffer is too small for the pathname string,
557 FSMakePath returns pathTooLongErr or
561 /*****************************************************************************/
563 #pragma mark FSPathMakeFSSpec
569 Boolean *isDirectory); /* can be NULL */
572 The FSPathMakeFSSpec function converts a pathname to an FSSpec.
574 path --> A pointer to a C String that is the pathname. The
575 format of the pathname you must supply can be
576 determined with the Gestalt selector gestaltFSAttr's
577 gestaltFSUsesPOSIXPathsForConversion bit.
578 If the gestaltFSUsesPOSIXPathsForConversion bit is
579 clear, the pathname must be a Mac OS File Manager
580 full pathname in a C string. If the
581 gestaltFSUsesPOSIXPathsForConversion bit is set,
582 the pathname must be a UTF8 encoded POSIX absolute
583 pathname in a C string.
585 isDirectory <** An optional pointer to a Boolean.
586 If not NULL, true will be returned in the Boolean
587 if the specified path is a directory, or false will
588 be returned in the Boolean if the specified path is
592 /*****************************************************************************/
594 #pragma mark UnicodeNameGetHFSName
597 UnicodeNameGetHFSName(
598 UniCharCount nameLength,
600 TextEncoding textEncodingHint,
601 Boolean isVolumeName,
605 The UnicodeNameGetHFSName function converts a Unicode string
606 to a Pascal Str31 (or Str27) string using an algorithm similar to that used
607 by the File Manager. Note that if the name is too long or cannot be converted
608 using the given text encoding hint, you will get an error instead of the
609 mangled name that the File Manager would return.
611 nameLength --> Number of UniChar in name parameter.
612 name --> The Unicode string to convert.
613 textEncodingHint --> The text encoding hint used for the conversion.
614 You can pass kTextEncodingUnknown to use the
615 "default" textEncodingHint.
616 isVolumeName --> If true, the output name will be limited to
617 27 characters (kHFSMaxVolumeNameChars). If false,
618 the output name will be limited to 31 characters
619 (kHFSMaxFileNameChars).
620 hfsName <-- The hfsName as a Pascal string.
624 Also see: HFSNameGetUnicodeName
627 /*****************************************************************************/
629 #pragma mark HFSNameGetUnicodeName
632 HFSNameGetUnicodeName(
633 ConstStr31Param hfsName,
634 TextEncoding textEncodingHint,
635 HFSUniStr255 *unicodeName);
638 The HFSNameGetUnicodeName function converts a Pascal Str31 string to an
639 Unicode HFSUniStr255 string using the same routines as the File Manager.
641 hfsName --> The Pascal string to convert.
642 textEncodingHint --> The text encoding hint used for the conversion.
643 You can pass kTextEncodingUnknown to use the
644 "default" textEncodingHint.
645 unicodeName <-- The Unicode string.
649 Also see: UnicodeNameGetHFSName
652 /*****************************************************************************/
654 #pragma mark ----- File/Directory Manipulation Routines -----
656 /*****************************************************************************/
658 #pragma mark FSRefValid
660 Boolean FSRefValid(const FSRef *ref);
663 The FSRefValid function determines if an FSRef is valid. If the result is
664 true, then the FSRef refers to an existing file or directory.
666 ref --> FSRef to a file or directory.
669 /*****************************************************************************/
671 #pragma mark FSGetParentRef
679 The FSGetParentRef function gets the parent directory FSRef of the
682 Note: FSRefs always point to real file system objects. So, there cannot
683 be a FSRef to the parent of volume root directories. If you call
684 FSGetParentRef with a ref to the root directory of a volume, the
685 function result will be noErr and the parentRef will be invalid (using it
686 for other file system requests will fail).
688 ref --> FSRef to a file or directory.
689 parentRef <-- The parent directory's FSRef.
692 /*****************************************************************************/
694 #pragma mark FSGetFileDirName
699 HFSUniStr255 *outName);
702 The FSGetFileDirName function gets the name of the file or directory
705 ref --> FSRef to a file or directory.
706 outName <-- The file or directory name.
709 /*****************************************************************************/
711 #pragma mark FSGetNodeID
716 long *nodeID, /* can be NULL */
717 Boolean *isDirectory); /* can be NULL */
720 The GetNodeIDFromFSRef function gets the node ID number of the
721 file or directory specified (note: the node ID is the directory ID
724 ref --> FSRef to a file or directory.
725 nodeID <** An optional pointer to a long.
726 If not NULL, the node ID will be returned in
728 isDirectory <** An optional pointer to a Boolean.
729 If not NULL, true will be returned in the Boolean
730 if the object is a directory, or false will be
731 returned in the Boolean if object is a file.
734 /*****************************************************************************/
736 #pragma mark FSGetUserPrivilegesPermissions
739 FSGetUserPrivilegesPermissions(
741 UInt8 *userPrivileges, /* can be NULL */
742 UInt32 permissions[4]); /* can be NULL */
745 The FSGetUserPrivilegesPermissions function gets the userPrivileges and/or
746 permissions of the file or directory specified.
748 ref --> FSRef to a file or directory.
749 userPrivileges <** An optional pointer to a UInt8.
750 If not NULL, the userPrivileges will be returned
752 permissions <** An optional pointer to an UInt32[4] array.
753 If not NULL, the permissions will be returned
754 in the UInt32[4] array.
757 /*****************************************************************************/
759 #pragma mark FSCheckLock
766 The FSCheckLock function determines if a file or directory is locked.
767 If FSCheckLock returns noErr, then the file or directory is not locked
768 and the volume it is on is not locked either. If FSCheckLock returns
769 fLckdErr, then the file or directory is locked. If FSCheckLock returns
770 wPrErr, then the volume is locked by hardware (i.e., locked tab on
771 removable media). If FSCheckLock returns vLckdErr, then the volume is
774 ref --> FSRef to a file or directory.
777 /*****************************************************************************/
779 #pragma mark FSGetForkSizes
784 UInt64 *dataLogicalSize, /* can be NULL */
785 UInt64 *rsrcLogicalSize); /* can be NULL */
788 The FSGetForkSizes returns the size of the data and/or resource fork for
791 ref --> FSRef to a file or directory.
792 dataLogicalSize <** An optional pointer to a UInt64.
793 If not NULL, the data fork's size will be
794 returned in the UInt64.
795 rsrcLogicalSize <** An optional pointer to a UInt64.
796 If not NULL, the resource fork's size will be
797 returned in the UInt64.
801 Also see: FSGetTotalForkSizes
804 /*****************************************************************************/
806 #pragma mark FSGetTotalForkSizes
811 UInt64 *totalLogicalSize, /* can be NULL */
812 UInt64 *totalPhysicalSize, /* can be NULL */
813 ItemCount *forkCount); /* can be NULL */
816 The FSGetTotalForkSizes returns the total logical size and/or the total
817 physical size of the specified file (i.e., it adds the sizes of all file
818 forks). It optionally returns the number of file forks.
820 ref --> FSRef to a file or directory.
821 totalLogicalSize <** An optional pointer to a UInt64.
822 If not NULL, the sum of all fork logical sizes
823 will be returned in the UInt64.
824 totalPhysicalSize <** An optional pointer to a UInt64.
825 If not NULL, the sum of all fork physical sizes
826 will be returned in the UInt64.
827 forkCount <** An optional pointer to a ItemCount.
828 If not NULL, the number of file forks
829 will be returned in the ItemCount.
833 Also see: FSGetForkSizes
836 /*****************************************************************************/
838 #pragma mark FSBumpDate
845 The FSBumpDate function changes the content modification date of a file
846 or directory to the current date/time. If the content modification date
847 is already equal to the current date/time, then add one second to the
848 content modification date.
850 ref --> FSRef to a file or directory.
853 /*****************************************************************************/
855 #pragma mark FSGetFinderInfo
860 FinderInfo *info, /* can be NULL */
861 ExtendedFinderInfo *extendedInfo, /* can be NULL */
862 Boolean *isDirectory); /* can be NULL */
865 The FSGetFinderInfo function gets the finder information for a file or
868 ref --> FSRef to a file or directory.
869 info <** An optional pointer to a FinderInfo.
870 If not NULL, the FileInfo (if ref is a file) or
871 the FolderInfo (if ref is a folder) will be
872 returned in the FinderInfo.
873 extendedInfo <** An optional pointer to a ExtendedFinderInfo.
874 If not NULL, the ExtendedFileInfo (if ref is a file)
875 or the ExtendedFolderInfo (if ref is a folder) will
876 be returned in the ExtendedFinderInfo.
877 isDirectory <** An optional pointer to a Boolean.
878 If not NULL, true will be returned in the Boolean
879 if the object is a directory, or false will be
880 returned in the Boolean if object is a file.
884 Also see: FSSetFinderInfo
887 /*****************************************************************************/
889 #pragma mark FSSetFinderInfo
894 const FinderInfo *info, /* can be NULL */
895 const ExtendedFinderInfo *extendedInfo); /* can be NULL */
898 The FSSetFinderInfo function sets the finder information for a file or
901 ref --> FSRef to a file or directory.
902 info **> A pointer to a FinderInfo record with the new
903 FileInfo (if ref is a file) or new FolderInfo
904 (if ref is a folder), or NULL if the FinderInfo
905 is not to be changed.
906 extendedInfo **> A pointer to a FinderInfo record with the new
907 ExtendedFileInfo (if ref is a file) or new
908 ExtendedFolderInfo (if ref is a folder), or NULL
909 if the ExtendedFinderInfo is not to be changed.
913 Also see: FSGetFinderInfo
916 /*****************************************************************************/
918 #pragma mark FSChangeCreatorType
927 The FSChangeCreatorType function changes the creator and/or file type of a file.
929 ref --> FSRef to a file.
930 creator --> The new creator type or 0x00000000 to leave
931 the creator type alone.
932 fileType --> The new file type or 0x00000000 to leave the
936 /*****************************************************************************/
938 #pragma mark FSChangeFinderFlags
947 The FSChangeFinderFlags function sets or clears flag bits in
948 the finderFlags field of a file's FileInfo record or a
949 directory's FolderInfo record.
951 ref --> FSRef to a file or directory.
952 setBits --> If true, then set the bits specified in flagBits.
953 If false, then clear the bits specified in flagBits.
954 flagBits --> The flagBits parameter specifies which Finder Flag
955 bits to set or clear. If a bit in flagBits is set,
956 then the same bit in fdFlags is either set or
957 cleared depending on the state of the setBits
961 /*****************************************************************************/
963 #pragma mark FSSetInvisible
969 #pragma mark FSClearInvisible
976 The FSSetInvisible and FSClearInvisible functions set or clear the
977 kIsInvisible bit in the finderFlags field of the specified file or
978 directory's finder information.
980 ref --> FSRef to a file or directory.
983 /*****************************************************************************/
985 #pragma mark FSSetNameLocked
991 #pragma mark FSClearNameLocked
998 The FSSetNameLocked and FSClearNameLocked functions set or clear the
999 kNameLocked bit bit in the finderFlags field of the specified file or
1000 directory's finder information.
1002 ref --> FSRef to a file or directory.
1005 /*****************************************************************************/
1007 #pragma mark FSSetIsStationery
1013 #pragma mark FSClearIsStationery
1016 FSClearIsStationery(
1020 The FSSetIsStationery and FSClearIsStationery functions set or clear the
1021 kIsStationery bit bit in the finderFlags field of the specified file or
1022 directory's finder information.
1024 ref --> FSRef to a file or directory.
1027 /*****************************************************************************/
1029 #pragma mark FSSetHasCustomIcon
1035 #pragma mark FSClearHasCustomIcon
1038 FSClearHasCustomIcon(
1042 The FSSetHasCustomIcon and FSClearHasCustomIcon functions set or clear the
1043 kHasCustomIcon bit bit in the finderFlags field of the specified file or
1044 directory's finder information.
1046 ref --> FSRef to a file or directory.
1049 /*****************************************************************************/
1051 #pragma mark FSClearHasBeenInited
1054 FSClearHasBeenInited(
1058 The FSClearHasBeenInited function clears the kHasBeenInited bit in the
1059 finderFlags field of the specified file or directory's finder information.
1061 Note: There is no FSSetHasBeenInited function because ONLY the Finder
1062 should set the kHasBeenInited bit.
1064 ref --> FSRef to a file or directory.
1067 /*****************************************************************************/
1069 #pragma mark FSCopyFileMgrAttributes
1072 FSCopyFileMgrAttributes(
1073 const FSRef *sourceRef,
1074 const FSRef *destinationRef,
1075 Boolean copyLockBit);
1078 The CopyFileMgrAttributes function copies all File Manager attributes
1079 from the source file or directory to the destination file or directory.
1080 If copyLockBit is true, then set the locked state of the destination
1081 to match the source.
1083 sourceRef --> FSRef to a file or directory.
1084 destinationRef --> FSRef to a file or directory.
1085 copyLockBit --> If true, set the locked state of the destination
1086 to match the source.
1089 /*****************************************************************************/
1091 #pragma mark FSMoveRenameObjectUnicode
1094 FSMoveRenameObjectUnicode(
1096 const FSRef *destDirectory,
1097 UniCharCount nameLength,
1098 const UniChar *name, /* can be NULL (no rename during move) */
1099 TextEncoding textEncodingHint,
1100 FSRef *newRef); /* if function fails along the way, newRef is final location of file */
1103 The FSMoveRenameObjectUnicode function moves a file or directory and
1104 optionally renames it. The source and destination locations must be on
1107 Note: If the input ref parameter is invalid, this call will fail and
1108 newRef, like ref, will be invalid.
1110 ref --> FSRef to a file or directory.
1111 destDirectory --> FSRef to the destination directory.
1112 nameLength --> Number of UniChar in name parameter.
1113 name --> An Unicode string with the new name for the
1114 moved object, or NULL if no rename is wanted.
1115 textEncodingHint --> The text encoding hint used for the rename.
1116 You can pass kTextEncodingUnknown to use the
1117 "default" textEncodingHint.
1118 newRef <-- The new FSRef of the object moved. Note that if
1119 this function fails at any step along the way,
1120 newRef is still then final location of the object.
1123 /*****************************************************************************/
1125 #pragma mark FSDeleteContainerContents
1128 FSDeleteContainerContents(
1129 const FSRef *container);
1132 The FSDeleteContainerContents function deletes the contents of a container
1133 directory. All files and subdirectories in the specified container are
1134 deleted. If a locked file or directory is encountered, it is unlocked and
1135 then deleted. If any unexpected errors are encountered,
1136 FSDeleteContainerContents quits and returns to the caller.
1138 container --> FSRef to a directory.
1142 Also see: FSDeleteContainer
1145 /*****************************************************************************/
1147 #pragma mark FSDeleteContainer
1151 const FSRef *container);
1154 The FSDeleteContainer function deletes a container directory and its contents.
1155 All files and subdirectories in the specified container are deleted.
1156 If a locked file or directory is encountered, it is unlocked and then
1157 deleted. After deleting the container's contents, the container is
1158 deleted. If any unexpected errors are encountered, FSDeleteContainer
1159 quits and returns to the caller.
1161 container --> FSRef to a directory.
1165 Also see: FSDeleteContainerContents
1168 /*****************************************************************************/
1170 #pragma mark IterateContainerFilterProcPtr
1172 typedef CALLBACK_API( Boolean , IterateContainerFilterProcPtr ) (
1173 Boolean containerChanged,
1174 ItemCount currentLevel,
1175 const FSCatalogInfo *catalogInfo,
1178 const HFSUniStr255 *name,
1182 This is the prototype for the IterateContainerFilterProc function which
1183 is called once for each file and directory found by FSIterateContainer.
1184 The IterateContainerFilterProc can use the read-only data it receives for
1187 The result of the IterateContainerFilterProc function indicates if
1188 iteration should be stopped. To stop iteration, return true; to continue
1189 iteration, return false.
1191 The yourDataPtr parameter can point to whatever data structure you might
1192 want to access from within the IterateContainerFilterProc.
1194 containerChanged --> Set to true if the container's contents changed
1196 currentLevel --> The current recursion level into the container.
1197 1 = the container, 2 = the container's immediate
1198 subdirectories, etc.
1199 catalogInfo --> The catalog information for the current object.
1200 Only the fields requested by the whichInfo
1201 parameter passed to FSIterateContainer are valid.
1202 ref --> The FSRef to the current object.
1203 spec --> The FSSpec to the current object if the wantFSSpec
1204 parameter passed to FSIterateContainer is true.
1205 name --> The name of the current object if the wantName
1206 parameter passed to FSIterateContainer is true.
1207 yourDataPtr --> An optional pointer to whatever data structure you
1208 might want to access from within the
1210 result <-- To stop iteration, return true; to continue
1211 iteration, return false.
1215 Also see: FSIterateContainer
1218 /*****************************************************************************/
1220 #pragma mark CallIterateContainerFilterProc
1222 #define CallIterateContainerFilterProc(userRoutine, containerChanged, currentLevel, catalogInfo, ref, spec, name, yourDataPtr) \
1223 (*(userRoutine))((containerChanged), (currentLevel), (catalogInfo), (ref), (spec), (name), (yourDataPtr))
1225 /*****************************************************************************/
1227 #pragma mark FSIterateContainer
1231 const FSRef *container,
1232 ItemCount maxLevels,
1233 FSCatalogInfoBitmap whichInfo,
1236 IterateContainerFilterProcPtr iterateFilter,
1240 The FSIterateContainer function performs a recursive iteration (scan) of the
1241 specified container directory and calls your IterateContainerFilterProc
1242 function once for each file and directory found.
1244 The maxLevels parameter lets you control how deep the recursion goes.
1245 If maxLevels is 1, FSIterateContainer only scans the specified directory;
1246 if maxLevels is 2, FSIterateContainer scans the specified directory and
1247 one subdirectory below the specified directory; etc. Set maxLevels to
1248 zero to scan all levels.
1250 The yourDataPtr parameter can point to whatever data structure you might
1251 want to access from within your IterateContainerFilterProc.
1253 container --> The FSRef to the container directory to iterate.
1254 maxLevels --> Maximum number of directory levels to scan or
1255 zero to scan all directory levels.
1256 whichInfo --> The fields of the FSCatalogInfo you wish to get.
1257 wantFSSpec --> Set to true if you want the FSSpec to each
1258 object passed to your IterateContainerFilterProc.
1259 wantName --> Set to true if you want the name of each
1260 object passed to your IterateContainerFilterProc.
1261 iterateFilter --> A pointer to the IterateContainerFilterProc you
1262 want called once for each file and directory found
1263 by FSIterateContainer.
1264 yourDataPtr --> An optional pointer to whatever data structure you
1265 might want to access from within the
1269 /*****************************************************************************/
1271 #pragma mark FSGetDirectoryItems
1274 FSGetDirectoryItems(
1275 const FSRef *container,
1276 FSRef ***refsHandle, /* pointer to handle of FSRefs */
1278 Boolean *containerChanged);
1281 The FSGetDirectoryItems function returns the list of items in the specified
1282 container. The array of FSRef records is returned in a Handle, refsHandle,
1283 which is allocated by FSGetDirectoryItems. The caller is responsible for
1284 disposing of refsHandle if the FSGetDirectoryItems returns noErr.
1286 container --> FSRef to a directory.
1287 refsHandle <-- Pointer to an FSRef Handle where the array of
1288 FSRefs is to be returned.
1289 numRefs <-- The number of FSRefs returned in the array.
1290 containerChanged <-- Set to true if the container changes while the
1291 list of items is being obtained.
1294 /*****************************************************************************/
1296 #pragma mark FSExchangeObjectsCompat
1299 FSExchangeObjectsCompat(
1300 const FSRef *sourceRef,
1301 const FSRef *destRef,
1302 FSRef *newSourceRef,
1306 The FSExchangeObjectsCompat function exchanges the data between two files.
1308 The FSExchangeObjectsCompat function is an enhanced version of
1309 FSExchangeObjects function. The two enhancements FSExchangeObjectsCompat
1312 1, FSExchangeObjectsCompat will work on volumes which do not support
1313 FSExchangeObjects. FSExchangeObjectsCompat does this by emulating
1314 FSExchangeObjects through a series of File Manager operations. If
1315 there is a failure at any step along the way, FSExchangeObjectsCompat
1316 attempts to undo any steps already taken to leave the files in their
1317 original state in their original locations.
1319 2. FSExchangeObjectsCompat returns new FSRefs to the source and
1320 destination files. Note that if this function fails at any step along
1321 the way, newSourceRef and newDestRef still give you access to the final
1322 locations of the files being exchanged -- even if they are renamed or
1323 not in their original locations.
1325 sourceRef --> FSRef to the source file.
1326 destRef --> FSRef to the destination file.
1327 newSourceRef <-- The new FSRef to the source file.
1328 newDestRef <-- The new FSRef to the destination file.
1331 /*****************************************************************************/
1333 #pragma mark ----- Shared Environment Routines -----
1335 /*****************************************************************************/
1337 #pragma mark FSLockRange
1346 The LockRange function locks (denies access to) a portion of a file
1347 that was opened with shared read/write permission.
1349 refNum --> The file reference number of an open file.
1350 rangeLength --> The number of bytes in the range.
1351 rangeStart --> The starting byte in the range to lock.
1355 Also see: UnlockRange
1358 /*****************************************************************************/
1360 #pragma mark FSUnlockRange
1369 The UnlockRange function unlocks (allows access to) a previously locked
1370 portion of a file that was opened with shared read/write permission.
1372 refNum --> The file reference number of an open file.
1373 rangeLength --> The number of bytes in the range.
1374 rangeStart --> The starting byte in the range to unlock.
1381 /*****************************************************************************/
1383 #pragma mark FSGetDirAccess
1388 SInt32 *ownerID, /* can be NULL */
1389 SInt32 *groupID, /* can be NULL */
1390 SInt32 *accessRights); /* can be NULL */
1393 The FSGetDirAccess function retrieves the directory access control
1394 information for a directory on a shared volume.
1396 ref --> An FSRef specifying the directory.
1397 ownerID <** An optional pointer to a SInt32.
1398 If not NULL, the directory's owner ID
1399 will be returned in the SInt32.
1400 groupID <** An optional pointer to a SInt32.
1401 If not NULL, the directory's group ID, or 0
1402 if no group affiliation, will be returned in
1404 accessRights <** An optional pointer to a SInt32.
1405 If not NULL, the directory's access rights
1406 will be returned in the SInt32.
1410 Also see: FSSetDirAccess, FSMapID, FSMapName
1413 /*****************************************************************************/
1415 #pragma mark FSSetDirAccess
1422 SInt32 accessRights);
1425 The FSpSetDirAccess function changes the directory access control
1426 information for a directory on a shared volume. You must be the owner of
1427 a directory to change its access control information.
1429 ref --> An FSRef specifying the directory.
1430 ownerID --> The directory's owner ID.
1431 groupID --> The directory's group ID or 0 if no group affiliation.
1432 accessRights --> The directory's access rights.
1436 Also see: FSGetDirAccess, FSMapID, FSMapName
1439 /*****************************************************************************/
1441 #pragma mark FSGetVolMountInfoSize
1444 FSGetVolMountInfoSize(
1445 FSVolumeRefNum volRefNum,
1449 The FSGetVolMountInfoSize function determines the how much space the
1450 program needs to allocate for a volume mounting information record.
1452 volRefNum --> Volume specification.
1453 size <-- The space needed (in bytes) of the volume
1454 mounting information record.
1458 Also see: FSGetVolMountInfo, VolumeMount
1461 /*****************************************************************************/
1463 #pragma mark FSGetVolMountInfo
1467 FSVolumeRefNum volRefNum,
1468 void *volMountInfo);
1471 The FSGetVolMountInfo function retrieves a volume mounting information
1472 record containing all the information needed to mount the volume,
1473 except for passwords.
1475 volRefNum --> Volume specification.
1476 volMountInfo <-- The volume mounting information.
1480 Also see: FSGetVolMountInfoSize, VolumeMount
1483 /*****************************************************************************/
1485 #pragma mark FSVolumeMount
1489 const void *volMountInfo,
1490 FSVolumeRefNum *volRefNum);
1493 The VolumeMount function mounts a volume using a volume mounting
1496 volMountInfo --> A volume mounting information record.
1497 volRefNum <-- The volume reference number.
1501 Also see: FSGetVolMountInfoSize, FSGetVolMountInfo
1504 /*****************************************************************************/
1506 #pragma mark FSMapID
1510 FSVolumeRefNum volRefNum,
1516 The FSMapID function determines the name of a user or group if you know
1517 the user or group ID.
1519 volRefNum --> Volume specification.
1520 objType --> The mapping function code:
1521 kOwnerID2Name to map a user ID to a user name
1522 kGroupID2Name to map a group ID to a group name
1523 name <** An optional pointer to a buffer (minimum Str31).
1524 If not NULL, the user or group name
1525 will be returned in the buffer.
1529 Also see: FSGetDirAccess, FSSetDirAccess, FSMapName
1532 /*****************************************************************************/
1534 #pragma mark FSMapName
1538 FSVolumeRefNum volRefNum,
1539 ConstStr255Param name,
1544 The FSMapName function determines the user or group ID if you know the
1547 volRefNum --> Volume specification.
1548 name --> The user or group name.
1549 objType --> The mapping function code:
1550 kOwnerName2ID to map a user name to a user ID
1551 kGroupName2ID to map a user name to a group ID
1552 ugID <-- The user or group ID.
1556 Also see: FSGetDirAccess, FSSetDirAccess, FSMapID
1559 /*****************************************************************************/
1561 #pragma mark FSCopyFile
1565 const FSRef *srcFileRef,
1566 const FSRef *dstDirectoryRef,
1567 UniCharCount nameLength,
1568 const UniChar *copyName, /* can be NULL (no rename during copy) */
1569 TextEncoding textEncodingHint,
1570 FSRef *newRef); /* can be NULL */
1573 The FSCopyFile function duplicates a file and optionally renames it.
1574 The source and destination volumes must be on the same file server.
1575 This function instructs the server to copy the file.
1577 srcFileRef --> An FSRef specifying the source file.
1578 dstDirectoryRef --> An FSRef specifying the destination directory.
1579 nameLength --> Number of UniChar in copyName parameter (ignored
1580 if copyName is NULL).
1581 copyName --> Points to the new file name if the file is to be
1582 renamed, or NULL if the file isn't to be renamed.
1583 textEncodingHint --> The text encoding hint used for the rename.
1584 You can pass kTextEncodingUnknown to use the
1585 "default" textEncodingHint.
1586 newRef <** An optional pointer to a FSRef.
1587 If not NULL, the FSRef of the duplicated file
1588 will be returned in the FSRef.
1591 /*****************************************************************************/
1593 #pragma mark FSMoveRename
1597 const FSRef *srcFileRef,
1598 const FSRef *dstDirectoryRef,
1599 UniCharCount nameLength,
1600 const UniChar *moveName, /* can be NULL (no rename during move) */
1601 TextEncoding textEncodingHint,
1602 FSRef *newRef); /* can be NULL */
1605 The FSMoveRename function moves a file or directory (object), and
1606 optionally renames it. The source and destination locations must be on
1607 the same shared volume.
1609 srcFileRef --> An FSRef specifying the source file.
1610 dstDirectoryRef --> An FSRef specifying the destination directory.
1611 nameLength --> Number of UniChar in moveName parameter (ignored
1612 if copyName is NULL)
1613 moveName --> Points to the new object name if the object is to be
1614 renamed, or NULL if the object isn't to be renamed.
1615 textEncodingHint --> The text encoding hint used for the rename.
1616 You can pass kTextEncodingUnknown to use the
1617 "default" textEncodingHint.
1618 newRef <** An optional pointer to a FSRef.
1619 If not NULL, the FSRef of the moved object
1620 will be returned in the FSRef.
1623 /*****************************************************************************/
1625 #pragma mark ----- File ID Routines -----
1627 /*****************************************************************************/
1629 #pragma mark FSResolveFileIDRef
1633 FSVolumeRefNum volRefNum,
1638 The FSResolveFileIDRef function returns an FSRef for the file with the
1639 specified file ID reference.
1641 volRefNum --> Volume specification.
1642 fileID --> The file ID reference.
1643 ref <-- The FSRef for the file ID reference.
1647 Also see: FSCreateFileIDRef, FSDeleteFileIDRef
1650 /*****************************************************************************/
1652 #pragma mark FSCreateFileIDRef
1660 The FSCreateFileIDRef function creates a file ID reference for the
1661 specified file, or if a file ID reference already exists, supplies
1662 the file ID reference and returns the result code fidExists or afpIDExists.
1664 ref --> The FSRef for the file.
1665 fileID <-- The file ID reference (if result is noErr,
1666 fidExists, or afpIDExists).
1670 Also see: GetFSRefFromFileIDRef, FSDeleteFileIDRef
1673 /*****************************************************************************/
1675 #pragma mark FSDeleteFileIDRef
1678 Why is there no FSDeleteFileIDRef routine? There are two reasons:
1680 1. Since Mac OS 8.1, PBDeleteFileIDRef hasn't deleted file ID references.
1681 On HFS volumes, deleting a file ID reference breaks aliases (which
1682 use file ID references to track files as they are moved around on a
1683 volume) and file ID references are automatically deleted when the file
1684 they refer to is deleted. On HFS Plus volumes, file ID references are
1685 always created when a file is created, deleted when the file is deleted,
1686 and cannot be deleted at any other time.
1688 2. PBDeleteFileIDRef causes a memory access fault under Mac OS X 10.0
1689 through 10.1.x. While this will be fixed in a future release, the
1690 implementation, like the Mac OS 8/9 implementation, does not delete
1695 Also see: GetFSRefFromFileIDRef, FSCreateFileIDRef
1698 /*****************************************************************************/
1700 #pragma mark ----- Utility Routines -----
1702 /*****************************************************************************/
1704 #pragma mark GetTempBuffer
1708 ByteCount buffReqSize,
1709 ByteCount *buffActSize);
1712 The GetTempBuffer function allocates a temporary buffer for file system
1713 operations which is at least 4K bytes and a multiple of 4K bytes.
1715 buffReqSize --> Size you'd like the buffer to be.
1716 buffActSize <-- The size of the buffer allocated.
1717 function result <-- Pointer to memory allocated, or NULL if no memory
1718 was available. The caller is responsible for
1719 disposing of this buffer with DisposePtr.
1722 /*****************************************************************************/
1724 #pragma mark FileRefNumGetFSRef
1732 The FileRefNumGetFSRef function gets the FSRef of an open file.
1734 refNum --> The file reference number of an open file.
1735 ref <-- The FSRef to the open file.
1738 /*****************************************************************************/
1740 #pragma mark FSSetDefault
1744 const FSRef *newDefault,
1748 The FSSetDefault function sets the current working directory to the
1749 directory specified by newDefault. The previous current working directory
1750 is returned in oldDefault and must be used to restore the current working
1751 directory to its previous state with the FSRestoreDefault function.
1752 These two functions are designed to be used as a wrapper around
1753 Standard I/O routines where the location of the file is implied to be the
1754 current working directory. This is how you should use these functions:
1756 result = FSSetDefault(&newDefault, &oldDefault);
1757 if ( noErr == result )
1759 // call the Stdio functions like remove, rename,
1760 // fopen, freopen, etc here!
1762 result = FSRestoreDefault(&oldDefault);
1765 newDefault --> An FSRef that specifies the new current working
1767 oldDefault <-- The previous current working directory's FSRef.
1771 Also see: FSRestoreDefault
1774 /*****************************************************************************/
1776 #pragma mark FSRestoreDefault
1780 const FSRef *oldDefault);
1783 The FSRestoreDefault function restores the current working directory
1784 to the directory specified by oldDefault. The oldDefault parameter was
1785 previously obtained from the FSSetDefault function.
1786 These two functions are designed to be used as a wrapper around
1787 Standard I/O routines where the location of the file is implied to be the
1788 current working directory. This is how you should use these functions:
1790 result = FSSetDefault(&newDefault, &oldDefault);
1791 if ( noErr == result )
1793 // call the Stdio functions like remove, rename,
1794 // fopen, freopen, etc here!
1796 result = FSRestoreDefault(&oldDefault);
1799 oldDefault --> The FSRef of the location to restore.
1803 Also see: FSSetDefault
1806 /*****************************************************************************/
1808 #if PRAGMA_STRUCT_ALIGN
1809 #pragma options align=reset
1810 #elif PRAGMA_STRUCT_PACKPUSH
1812 #elif PRAGMA_STRUCT_PACK
1816 #ifdef PRAGMA_IMPORT_OFF
1819 #pragma import reset
1826 #endif /* __MOREFILESX__ */