2 Copyright (C) 2003, 2010 - Wolfire Games
4 This file is part of Lugaru.
6 Lugaru is free software; you can redistribute it and/or
7 modify it under the terms of the GNU General Public License
8 as published by the Free Software Foundation; either version 2
9 of the License, or (at your option) any later version.
11 This program is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
15 See the GNU General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with this program; if not, write to the Free Software
19 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
25 Contains: A collection of useful high-level File Manager routines
26 which use the HFS Plus APIs wherever possible.
28 Version: MoreFilesX 1.0.1
30 Copyright: © 1992-2002 by Apple Computer, Inc., all rights reserved.
32 Disclaimer: IMPORTANT: This Apple software is supplied to you by Apple Computer, Inc.
33 ("Apple") in consideration of your agreement to the following terms, and your
34 use, installation, modification or redistribution of this Apple software
35 constitutes acceptance of these terms. If you do not agree with these terms,
36 please do not use, install, modify or redistribute this Apple software.
38 In consideration of your agreement to abide by the following terms, and subject
39 to these terms, Apple grants you a personal, non-exclusive license, under AppleÕs
40 copyrights in this original Apple software (the "Apple Software"), to use,
41 reproduce, modify and redistribute the Apple Software, with or without
42 modifications, in source and/or binary forms; provided that if you redistribute
43 the Apple Software in its entirety and without modifications, you must retain
44 this notice and the following text and disclaimers in all such redistributions of
45 the Apple Software. Neither the name, trademarks, service marks or logos of
46 Apple Computer, Inc. may be used to endorse or promote products derived from the
47 Apple Software without specific prior written permission from Apple. Except as
48 expressly stated in this notice, no other rights or licenses, express or implied,
49 are granted by Apple herein, including but not limited to any patent rights that
50 may be infringed by your derivative works or by other works in which the Apple
51 Software may be incorporated.
53 The Apple Software is provided by Apple on an "AS IS" basis. APPLE MAKES NO
54 WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED
55 WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
56 PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN
57 COMBINATION WITH YOUR PRODUCTS.
59 IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR
60 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
61 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
62 ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION
63 OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT
64 (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN
65 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
69 DRI: Apple Macintosh Developer Technical Support
71 Other Contact: For bug reports, consult the following page on
73 http://developer.apple.com/bugreporter/
75 Technology: DTS Sample Code
81 Change History (most recent first):
83 <3> 4/19/02 JL [2853905] Fixed #if test around header includes.
84 <2> 4/19/02 JL [2853901] Updated standard disclaimer.
85 <1> 1/25/02 JL MoreFilesX 1.0
88 What do those arrows in the documentation for each routine mean?
90 --> The parameter is an input
92 <-- The parameter is an output. The pointer to the variable
93 where the output will be returned (must not be NULL).
95 <** The parameter is an optional output. If it is not a
96 NULL pointer, it points to the variable where the output
97 will be returned. If it is a NULL pointer, the output will
98 not be returned and will possibly let the routine and the
99 File Manager do less work. If you don't need an optional output,
101 **> The parameter is an optional input. If it is not a
102 NULL pointer, it points to the variable containing the
103 input data. If it is a NULL pointer, the input is not used
104 and will possibly let the routine and the File Manager
108 #ifndef __MOREFILESX__
109 #define __MOREFILESX__
112 #if defined(__MACH__)
113 #include <Carbon/Carbon.h>
131 #if PRAGMA_STRUCT_ALIGN
132 #pragma options align=mac68k
133 #elif PRAGMA_STRUCT_PACKPUSH
134 #pragma pack(push, 2)
135 #elif PRAGMA_STRUCT_PACK
139 /*****************************************************************************/
142 #pragma mark ----- FinderInfo and ExtendedFinderInfo -----
146 * FSGetFinderInfo and FSSetFinderInfo use these unions for Finder information.
154 typedef union FinderInfo FinderInfo;
156 union ExtendedFinderInfo
158 ExtendedFileInfo file;
159 ExtendedFolderInfo folder;
161 typedef union ExtendedFinderInfo ExtendedFinderInfo;
163 /*****************************************************************************/
165 #pragma mark ----- GetVolParmsInfoBuffer Macros -----
168 * Macros to get information out of GetVolParmsInfoBuffer.
171 /* version 1 field getters */
172 #define GetVolParmsInfoVersion(volParms) \
173 ((volParms)->vMVersion)
174 #define GetVolParmsInfoAttrib(volParms) \
175 ((volParms)->vMAttrib)
176 #define GetVolParmsInfoLocalHand(volParms) \
177 ((volParms)->vMLocalHand)
178 #define GetVolParmsInfoServerAdr(volParms) \
179 ((volParms)->vMServerAdr)
181 /* version 2 field getters (assume zero result if version < 2) */
182 #define GetVolParmsInfoVolumeGrade(volParms) \
183 (((volParms)->vMVersion >= 2) ? (volParms)->vMVolumeGrade : 0)
184 #define GetVolParmsInfoForeignPrivID(volParms) \
185 (((volParms)->vMVersion >= 2) ? (volParms)->vMForeignPrivID : 0)
187 /* version 3 field getters (assume zero result if version < 3) */
188 #define GetVolParmsInfoExtendedAttributes(volParms) \
189 (((volParms)->vMVersion >= 3) ? (volParms)->vMExtendedAttributes : 0)
191 /* attribute bits supported by all versions of GetVolParmsInfoBuffer */
192 #define VolIsNetworkVolume(volParms) \
193 ((volParms)->vMServerAdr != 0)
194 #define VolHasLimitFCBs(volParms) \
195 (((volParms)->vMAttrib & (1L << bLimitFCBs)) != 0)
196 #define VolHasLocalWList(volParms) \
197 (((volParms)->vMAttrib & (1L << bLocalWList)) != 0)
198 #define VolHasNoMiniFndr(volParms) \
199 (((volParms)->vMAttrib & (1L << bNoMiniFndr)) != 0)
200 #define VolHasNoVNEdit(volParms) \
201 (((volParms)->vMAttrib & (1L << bNoVNEdit)) != 0)
202 #define VolHasNoLclSync(volParms) \
203 (((volParms)->vMAttrib & (1L << bNoLclSync)) != 0)
204 #define VolHasTrshOffLine(volParms) \
205 (((volParms)->vMAttrib & (1L << bTrshOffLine)) != 0)
206 #define VolHasNoSwitchTo(volParms) \
207 (((volParms)->vMAttrib & (1L << bNoSwitchTo)) != 0)
208 #define VolHasNoDeskItems(volParms) \
209 (((volParms)->vMAttrib & (1L << bNoDeskItems)) != 0)
210 #define VolHasNoBootBlks(volParms) \
211 (((volParms)->vMAttrib & (1L << bNoBootBlks)) != 0)
212 #define VolHasAccessCntl(volParms) \
213 (((volParms)->vMAttrib & (1L << bAccessCntl)) != 0)
214 #define VolHasNoSysDir(volParms) \
215 (((volParms)->vMAttrib & (1L << bNoSysDir)) != 0)
216 #define VolHasExtFSVol(volParms) \
217 (((volParms)->vMAttrib & (1L << bHasExtFSVol)) != 0)
218 #define VolHasOpenDeny(volParms) \
219 (((volParms)->vMAttrib & (1L << bHasOpenDeny)) != 0)
220 #define VolHasCopyFile(volParms) \
221 (((volParms)->vMAttrib & (1L << bHasCopyFile)) != 0)
222 #define VolHasMoveRename(volParms) \
223 (((volParms)->vMAttrib & (1L << bHasMoveRename)) != 0)
224 #define VolHasDesktopMgr(volParms) \
225 (((volParms)->vMAttrib & (1L << bHasDesktopMgr)) != 0)
226 #define VolHasShortName(volParms) \
227 (((volParms)->vMAttrib & (1L << bHasShortName)) != 0)
228 #define VolHasFolderLock(volParms) \
229 (((volParms)->vMAttrib & (1L << bHasFolderLock)) != 0)
230 #define VolHasPersonalAccessPrivileges(volParms) \
231 (((volParms)->vMAttrib & (1L << bHasPersonalAccessPrivileges)) != 0)
232 #define VolHasUserGroupList(volParms) \
233 (((volParms)->vMAttrib & (1L << bHasUserGroupList)) != 0)
234 #define VolHasCatSearch(volParms) \
235 (((volParms)->vMAttrib & (1L << bHasCatSearch)) != 0)
236 #define VolHasFileIDs(volParms) \
237 (((volParms)->vMAttrib & (1L << bHasFileIDs)) != 0)
238 #define VolHasBTreeMgr(volParms) \
239 (((volParms)->vMAttrib & (1L << bHasBTreeMgr)) != 0)
240 #define VolHasBlankAccessPrivileges(volParms) \
241 (((volParms)->vMAttrib & (1L << bHasBlankAccessPrivileges)) != 0)
242 #define VolSupportsAsyncRequests(volParms) \
243 (((volParms)->vMAttrib & (1L << bSupportsAsyncRequests)) != 0)
244 #define VolSupportsTrashVolumeCache(volParms) \
245 (((volParms)->vMAttrib & (1L << bSupportsTrashVolumeCache)) != 0)
247 /* attribute bits supported by version 3 and greater versions of GetVolParmsInfoBuffer */
248 #define VolIsEjectable(volParms) \
249 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bIsEjectable)) != 0)
250 #define VolSupportsHFSPlusAPIs(volParms) \
251 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsHFSPlusAPIs)) != 0)
252 #define VolSupportsFSCatalogSearch(volParms) \
253 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsFSCatalogSearch)) != 0)
254 #define VolSupportsFSExchangeObjects(volParms) \
255 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsFSExchangeObjects)) != 0)
256 #define VolSupports2TBFiles(volParms) \
257 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupports2TBFiles)) != 0)
258 #define VolSupportsLongNames(volParms) \
259 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsLongNames)) != 0)
260 #define VolSupportsMultiScriptNames(volParms) \
261 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsMultiScriptNames)) != 0)
262 #define VolSupportsNamedForks(volParms) \
263 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsNamedForks)) != 0)
264 #define VolSupportsSubtreeIterators(volParms) \
265 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsSubtreeIterators)) != 0)
266 #define VolL2PCanMapFileBlocks(volParms) \
267 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bL2PCanMapFileBlocks)) != 0)
268 #define VolParentModDateChanges(volParms) \
269 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bParentModDateChanges)) != 0)
270 #define VolAncestorModDateChanges(volParms) \
271 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bAncestorModDateChanges)) != 0)
272 #define VolSupportsSymbolicLinks(volParms) \
273 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsSymbolicLinks)) != 0)
274 #define VolIsAutoMounted(volParms) \
275 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bIsAutoMounted)) != 0)
277 /*****************************************************************************/
279 #pragma mark ----- userPrivileges Bit Masks and Macros -----
282 * Bit masks and macros to get common information out of userPrivileges byte
283 * returned by FSGetCatalogInfo.
285 * Note: The userPrivileges byte is the same as the ioACUser byte returned
286 * by PBGetCatInfo, and is the 1's complement of the user's privileges
287 * byte returned in ioACAccess by PBHGetDirAccess. That's where the
288 * ioACUser names came from.
290 * The userPrivileges are user's effective privileges based on the
291 * user ID and the groups that user belongs to, and the owner, group,
292 * and everyone privileges for the given directory.
297 /* mask for just the access restriction bits */
298 kioACUserAccessMask = (kioACUserNoSeeFolderMask +
299 kioACUserNoSeeFilesMask +
300 kioACUserNoMakeChangesMask),
301 /* common access privilege settings */
302 kioACUserFull = 0x00, /* no access restiction bits on */
303 kioACUserNone = kioACUserAccessMask, /* all access restiction bits on */
304 kioACUserDropBox = (kioACUserNoSeeFolderMask +
305 kioACUserNoSeeFilesMask), /* make changes, but not see files or folders */
306 kioACUserBulletinBoard = kioACUserNoMakeChangesMask /* see files and folders, but not make changes */
310 /* Macros for testing ioACUser bits. */
312 #define UserIsOwner(userPrivileges) \
313 (((userPrivileges) & kioACUserNotOwnerMask) == 0)
314 #define UserHasFullAccess(userPrivileges) \
315 (((userPrivileges) & (kioACUserAccessMask)) == kioACUserFull)
316 #define UserHasDropBoxAccess(userPrivileges) \
317 (((userPrivileges) & kioACUserAccessMask) == kioACUserDropBox)
318 #define UserHasBulletinBoard(userPrivileges) \
319 (((userPrivileges) & kioACUserAccessMask) == kioACUserBulletinBoard)
320 #define UserHasNoAccess(userPrivileges) \
321 (((userPrivileges) & kioACUserAccessMask) == kioACUserNone)
323 /*****************************************************************************/
325 #pragma mark ----- File Access Routines -----
327 /*****************************************************************************/
329 #pragma mark FSCopyFork
336 ByteCount copyBufferSize);
339 The FSCopyFork function copies all data from the source fork to the
340 destination fork of open file forks and makes sure the destination EOF
341 is equal to the source EOF.
343 srcRefNum --> The source file reference number.
344 dstRefNum --> The destination file reference number.
345 copyBufferPtr --> Pointer to buffer to use during copy. The
346 buffer should be at least 4K-bytes minimum.
347 The larger the buffer, the faster the copy
349 copyBufferSize --> The size of the copy buffer.
352 /*****************************************************************************/
354 #pragma mark ----- Volume Access Routines -----
356 /*****************************************************************************/
358 #pragma mark FSGetVolParms
362 FSVolumeRefNum volRefNum,
364 GetVolParmsInfoBuffer *volParmsInfo,
365 UInt32 *actualInfoSize);
368 The FSGetVolParms function returns information about the characteristics
369 of a volume. A result of paramErr usually just means the volume doesn't
370 support GetVolParms and the feature you were going to check
373 volRefNum --> Volume specification.
374 bufferSize --> Size of buffer pointed to by volParmsInfo.
375 volParmsInfo <-- A GetVolParmsInfoBuffer record where the volume
376 attributes information is returned.
377 actualInfoSize <-- The number of bytes actually returned
382 Also see: The GetVolParmsInfoBuffer Macros for checking attribute bits
386 /*****************************************************************************/
388 #pragma mark FSGetVRefNum
393 FSVolumeRefNum *vRefNum);
396 The FSGetVRefNum function determines the volume reference
397 number of a volume from a FSRef.
400 vRefNum <-- The volume reference number.
403 /*****************************************************************************/
405 #pragma mark FSGetVInfo
409 FSVolumeRefNum volume,
410 HFSUniStr255 *volumeName, /* can be NULL */
411 UInt64 *freeBytes, /* can be NULL */
412 UInt64 *totalBytes); /* can be NULL */
415 The FSGetVInfo function returns the name, available space (in bytes),
416 and total space (in bytes) for the specified volume.
418 volume --> The volume reference number.
419 volumeName <** An optional pointer to a HFSUniStr255.
420 If not NULL, the volume name will be returned in
422 freeBytes <** An optional pointer to a UInt64.
423 If not NULL, the number of free bytes on the
424 volume will be returned in the UInt64.
425 totalBytes <** An optional pointer to a UInt64.
426 If not NULL, the total number of bytes on the
427 volume will be returned in the UInt64.
430 /*****************************************************************************/
432 #pragma mark FSGetVolFileSystemID
435 FSGetVolFileSystemID(
436 FSVolumeRefNum volume,
437 UInt16 *fileSystemID, /* can be NULL */
438 UInt16 *signature); /* can be NULL */
441 The FSGetVolFileSystemID function returns the file system ID and signature
442 of a mounted volume. The file system ID identifies the file system
443 that handles requests to a particular volume. The signature identifies the
444 volume type of the volume (for example, FSID 0 is Macintosh HFS Plus, HFS
445 or MFS, where a signature of 0x4244 identifies the volume as HFS).
446 Here's a partial list of file system ID numbers (only Apple's file systems
449 ----- -----------------------------------------------------
450 $0000 Macintosh HFS Plus, HFS or MFS
451 $0100 ProDOS File System
452 $0101 PowerTalk Mail Enclosures
453 $4147 ISO 9660 File Access (through Foreign File Access)
454 $4242 High Sierra File Access (through Foreign File Access)
455 $464D QuickTake File System (through Foreign File Access)
456 $4953 Macintosh PC Exchange (MS-DOS)
457 $4A48 Audio CD Access (through Foreign File Access)
458 $4D4B Apple Photo Access (through Foreign File Access)
459 $6173 AppleShare (later versions of AppleShare only)
461 See the Technical Note "FL 35 - Determining Which File System
462 Is Active" and the "Guide to the File System Manager" for more
465 volume --> The volume reference number.
466 fileSystemID <** An optional pointer to a UInt16.
467 If not NULL, the volume's file system ID will
468 be returned in the UInt16.
469 signature <** An optional pointer to a UInt16.
470 If not NULL, the volume's signature will
471 be returned in the UInt16.
474 /*****************************************************************************/
476 #pragma mark FSGetMountedVolumes
480 FSRef ***volumeRefsHandle, /* pointer to handle of FSRefs */
481 ItemCount *numVolumes);
484 The FSGetMountedVolumes function returns the list of volumes currently
485 mounted in an array of FSRef records. The array of FSRef records is
486 returned in a Handle, volumeRefsHandle, which is allocated by
487 FSGetMountedVolumes. The caller is responsible for disposing of
488 volumeRefsHandle if the FSGetMountedVolumes returns noErr.
490 volumeRefsHandle <-- Pointer to an FSRef Handle where the array of
491 FSRefs is to be returned.
492 numVolumes <-- The number of volumes returned in the array.
495 /*****************************************************************************/
497 #pragma mark ----- FSRef/FSpec/Path/Name Conversion Routines -----
499 /*****************************************************************************/
501 #pragma mark FSRefMakeFSSpec
509 The FSRefMakeFSSpec function returns an FSSpec for the file or
510 directory specified by the ref parameter.
512 ref --> An FSRef specifying the file or directory.
516 /*****************************************************************************/
518 #pragma mark FSMakeFSRef
522 FSVolumeRefNum volRefNum,
524 ConstStr255Param name,
528 The FSMakeFSRef function creates an FSRef from the traditional
529 volume reference number, directory ID and pathname inputs. It is
530 functionally equivalent to FSMakeFSSpec followed by FSpMakeFSRef.
532 volRefNum --> Volume specification.
533 dirID --> Directory specification.
534 name --> The file or directory name, or NULL.
538 /*****************************************************************************/
540 #pragma mark FSMakePath
546 ConstStr255Param name,
551 The FSMakePath function creates a pathname from the traditional volume reference
552 number, directory ID, and pathname inputs. It is functionally equivalent to
553 FSMakeFSSpec, FSpMakeFSRef, FSRefMakePath.
555 volRefNum --> Volume specification.
556 dirID --> Directory specification.
557 name --> The file or directory name, or NULL.
558 path <-- A pointer to a buffer which FSMakePath will
559 fill with a C string representing the pathname
560 to the file or directory specified. The format of
561 the pathname returned can be determined with the
562 Gestalt selector gestaltFSAttr's
563 gestaltFSUsesPOSIXPathsForConversion bit.
564 If the gestaltFSUsesPOSIXPathsForConversion bit is
565 clear, the pathname is a Mac OS File Manager full
566 pathname in a C string, and file or directory names
567 in the pathname may be mangled as returned by
568 the File Manager. If the
569 gestaltFSUsesPOSIXPathsForConversion bit is set,
570 the pathname is a UTF8 encoded POSIX absolute
571 pathname in a C string. In either case, the
572 pathname returned can be passed back to
573 FSPathMakeRef to create an FSRef to the file or
574 directory, or FSPathMakeFSSpec to craete an FSSpec
575 to the file or directory.
576 maxPathSize --> The size of the path buffer in bytes. If the path
577 buffer is too small for the pathname string,
578 FSMakePath returns pathTooLongErr or
582 /*****************************************************************************/
584 #pragma mark FSPathMakeFSSpec
590 Boolean *isDirectory); /* can be NULL */
593 The FSPathMakeFSSpec function converts a pathname to an FSSpec.
595 path --> A pointer to a C String that is the pathname. The
596 format of the pathname you must supply can be
597 determined with the Gestalt selector gestaltFSAttr's
598 gestaltFSUsesPOSIXPathsForConversion bit.
599 If the gestaltFSUsesPOSIXPathsForConversion bit is
600 clear, the pathname must be a Mac OS File Manager
601 full pathname in a C string. If the
602 gestaltFSUsesPOSIXPathsForConversion bit is set,
603 the pathname must be a UTF8 encoded POSIX absolute
604 pathname in a C string.
606 isDirectory <** An optional pointer to a Boolean.
607 If not NULL, true will be returned in the Boolean
608 if the specified path is a directory, or false will
609 be returned in the Boolean if the specified path is
613 /*****************************************************************************/
615 #pragma mark UnicodeNameGetHFSName
618 UnicodeNameGetHFSName(
619 UniCharCount nameLength,
621 TextEncoding textEncodingHint,
622 Boolean isVolumeName,
626 The UnicodeNameGetHFSName function converts a Unicode string
627 to a Pascal Str31 (or Str27) string using an algorithm similar to that used
628 by the File Manager. Note that if the name is too long or cannot be converted
629 using the given text encoding hint, you will get an error instead of the
630 mangled name that the File Manager would return.
632 nameLength --> Number of UniChar in name parameter.
633 name --> The Unicode string to convert.
634 textEncodingHint --> The text encoding hint used for the conversion.
635 You can pass kTextEncodingUnknown to use the
636 "default" textEncodingHint.
637 isVolumeName --> If true, the output name will be limited to
638 27 characters (kHFSMaxVolumeNameChars). If false,
639 the output name will be limited to 31 characters
640 (kHFSMaxFileNameChars).
641 hfsName <-- The hfsName as a Pascal string.
645 Also see: HFSNameGetUnicodeName
648 /*****************************************************************************/
650 #pragma mark HFSNameGetUnicodeName
653 HFSNameGetUnicodeName(
654 ConstStr31Param hfsName,
655 TextEncoding textEncodingHint,
656 HFSUniStr255 *unicodeName);
659 The HFSNameGetUnicodeName function converts a Pascal Str31 string to an
660 Unicode HFSUniStr255 string using the same routines as the File Manager.
662 hfsName --> The Pascal string to convert.
663 textEncodingHint --> The text encoding hint used for the conversion.
664 You can pass kTextEncodingUnknown to use the
665 "default" textEncodingHint.
666 unicodeName <-- The Unicode string.
670 Also see: UnicodeNameGetHFSName
673 /*****************************************************************************/
675 #pragma mark ----- File/Directory Manipulation Routines -----
677 /*****************************************************************************/
679 #pragma mark FSRefValid
681 Boolean FSRefValid(const FSRef *ref);
684 The FSRefValid function determines if an FSRef is valid. If the result is
685 true, then the FSRef refers to an existing file or directory.
687 ref --> FSRef to a file or directory.
690 /*****************************************************************************/
692 #pragma mark FSGetParentRef
700 The FSGetParentRef function gets the parent directory FSRef of the
703 Note: FSRefs always point to real file system objects. So, there cannot
704 be a FSRef to the parent of volume root directories. If you call
705 FSGetParentRef with a ref to the root directory of a volume, the
706 function result will be noErr and the parentRef will be invalid (using it
707 for other file system requests will fail).
709 ref --> FSRef to a file or directory.
710 parentRef <-- The parent directory's FSRef.
713 /*****************************************************************************/
715 #pragma mark FSGetFileDirName
720 HFSUniStr255 *outName);
723 The FSGetFileDirName function gets the name of the file or directory
726 ref --> FSRef to a file or directory.
727 outName <-- The file or directory name.
730 /*****************************************************************************/
732 #pragma mark FSGetNodeID
737 long *nodeID, /* can be NULL */
738 Boolean *isDirectory); /* can be NULL */
741 The GetNodeIDFromFSRef function gets the node ID number of the
742 file or directory specified (note: the node ID is the directory ID
745 ref --> FSRef to a file or directory.
746 nodeID <** An optional pointer to a long.
747 If not NULL, the node ID will be returned in
749 isDirectory <** An optional pointer to a Boolean.
750 If not NULL, true will be returned in the Boolean
751 if the object is a directory, or false will be
752 returned in the Boolean if object is a file.
755 /*****************************************************************************/
757 #pragma mark FSGetUserPrivilegesPermissions
760 FSGetUserPrivilegesPermissions(
762 UInt8 *userPrivileges, /* can be NULL */
763 UInt32 permissions[4]); /* can be NULL */
766 The FSGetUserPrivilegesPermissions function gets the userPrivileges and/or
767 permissions of the file or directory specified.
769 ref --> FSRef to a file or directory.
770 userPrivileges <** An optional pointer to a UInt8.
771 If not NULL, the userPrivileges will be returned
773 permissions <** An optional pointer to an UInt32[4] array.
774 If not NULL, the permissions will be returned
775 in the UInt32[4] array.
778 /*****************************************************************************/
780 #pragma mark FSCheckLock
787 The FSCheckLock function determines if a file or directory is locked.
788 If FSCheckLock returns noErr, then the file or directory is not locked
789 and the volume it is on is not locked either. If FSCheckLock returns
790 fLckdErr, then the file or directory is locked. If FSCheckLock returns
791 wPrErr, then the volume is locked by hardware (i.e., locked tab on
792 removable media). If FSCheckLock returns vLckdErr, then the volume is
795 ref --> FSRef to a file or directory.
798 /*****************************************************************************/
800 #pragma mark FSGetForkSizes
805 UInt64 *dataLogicalSize, /* can be NULL */
806 UInt64 *rsrcLogicalSize); /* can be NULL */
809 The FSGetForkSizes returns the size of the data and/or resource fork for
812 ref --> FSRef to a file or directory.
813 dataLogicalSize <** An optional pointer to a UInt64.
814 If not NULL, the data fork's size will be
815 returned in the UInt64.
816 rsrcLogicalSize <** An optional pointer to a UInt64.
817 If not NULL, the resource fork's size will be
818 returned in the UInt64.
822 Also see: FSGetTotalForkSizes
825 /*****************************************************************************/
827 #pragma mark FSGetTotalForkSizes
832 UInt64 *totalLogicalSize, /* can be NULL */
833 UInt64 *totalPhysicalSize, /* can be NULL */
834 ItemCount *forkCount); /* can be NULL */
837 The FSGetTotalForkSizes returns the total logical size and/or the total
838 physical size of the specified file (i.e., it adds the sizes of all file
839 forks). It optionally returns the number of file forks.
841 ref --> FSRef to a file or directory.
842 totalLogicalSize <** An optional pointer to a UInt64.
843 If not NULL, the sum of all fork logical sizes
844 will be returned in the UInt64.
845 totalPhysicalSize <** An optional pointer to a UInt64.
846 If not NULL, the sum of all fork physical sizes
847 will be returned in the UInt64.
848 forkCount <** An optional pointer to a ItemCount.
849 If not NULL, the number of file forks
850 will be returned in the ItemCount.
854 Also see: FSGetForkSizes
857 /*****************************************************************************/
859 #pragma mark FSBumpDate
866 The FSBumpDate function changes the content modification date of a file
867 or directory to the current date/time. If the content modification date
868 is already equal to the current date/time, then add one second to the
869 content modification date.
871 ref --> FSRef to a file or directory.
874 /*****************************************************************************/
876 #pragma mark FSGetFinderInfo
881 FinderInfo *info, /* can be NULL */
882 ExtendedFinderInfo *extendedInfo, /* can be NULL */
883 Boolean *isDirectory); /* can be NULL */
886 The FSGetFinderInfo function gets the finder information for a file or
889 ref --> FSRef to a file or directory.
890 info <** An optional pointer to a FinderInfo.
891 If not NULL, the FileInfo (if ref is a file) or
892 the FolderInfo (if ref is a folder) will be
893 returned in the FinderInfo.
894 extendedInfo <** An optional pointer to a ExtendedFinderInfo.
895 If not NULL, the ExtendedFileInfo (if ref is a file)
896 or the ExtendedFolderInfo (if ref is a folder) will
897 be returned in the ExtendedFinderInfo.
898 isDirectory <** An optional pointer to a Boolean.
899 If not NULL, true will be returned in the Boolean
900 if the object is a directory, or false will be
901 returned in the Boolean if object is a file.
905 Also see: FSSetFinderInfo
908 /*****************************************************************************/
910 #pragma mark FSSetFinderInfo
915 const FinderInfo *info, /* can be NULL */
916 const ExtendedFinderInfo *extendedInfo); /* can be NULL */
919 The FSSetFinderInfo function sets the finder information for a file or
922 ref --> FSRef to a file or directory.
923 info **> A pointer to a FinderInfo record with the new
924 FileInfo (if ref is a file) or new FolderInfo
925 (if ref is a folder), or NULL if the FinderInfo
926 is not to be changed.
927 extendedInfo **> A pointer to a FinderInfo record with the new
928 ExtendedFileInfo (if ref is a file) or new
929 ExtendedFolderInfo (if ref is a folder), or NULL
930 if the ExtendedFinderInfo is not to be changed.
934 Also see: FSGetFinderInfo
937 /*****************************************************************************/
939 #pragma mark FSChangeCreatorType
948 The FSChangeCreatorType function changes the creator and/or file type of a file.
950 ref --> FSRef to a file.
951 creator --> The new creator type or 0x00000000 to leave
952 the creator type alone.
953 fileType --> The new file type or 0x00000000 to leave the
957 /*****************************************************************************/
959 #pragma mark FSChangeFinderFlags
968 The FSChangeFinderFlags function sets or clears flag bits in
969 the finderFlags field of a file's FileInfo record or a
970 directory's FolderInfo record.
972 ref --> FSRef to a file or directory.
973 setBits --> If true, then set the bits specified in flagBits.
974 If false, then clear the bits specified in flagBits.
975 flagBits --> The flagBits parameter specifies which Finder Flag
976 bits to set or clear. If a bit in flagBits is set,
977 then the same bit in fdFlags is either set or
978 cleared depending on the state of the setBits
982 /*****************************************************************************/
984 #pragma mark FSSetInvisible
990 #pragma mark FSClearInvisible
997 The FSSetInvisible and FSClearInvisible functions set or clear the
998 kIsInvisible bit in the finderFlags field of the specified file or
999 directory's finder information.
1001 ref --> FSRef to a file or directory.
1004 /*****************************************************************************/
1006 #pragma mark FSSetNameLocked
1012 #pragma mark FSClearNameLocked
1019 The FSSetNameLocked and FSClearNameLocked functions set or clear the
1020 kNameLocked bit bit in the finderFlags field of the specified file or
1021 directory's finder information.
1023 ref --> FSRef to a file or directory.
1026 /*****************************************************************************/
1028 #pragma mark FSSetIsStationery
1034 #pragma mark FSClearIsStationery
1037 FSClearIsStationery(
1041 The FSSetIsStationery and FSClearIsStationery functions set or clear the
1042 kIsStationery bit bit in the finderFlags field of the specified file or
1043 directory's finder information.
1045 ref --> FSRef to a file or directory.
1048 /*****************************************************************************/
1050 #pragma mark FSSetHasCustomIcon
1056 #pragma mark FSClearHasCustomIcon
1059 FSClearHasCustomIcon(
1063 The FSSetHasCustomIcon and FSClearHasCustomIcon functions set or clear the
1064 kHasCustomIcon bit bit in the finderFlags field of the specified file or
1065 directory's finder information.
1067 ref --> FSRef to a file or directory.
1070 /*****************************************************************************/
1072 #pragma mark FSClearHasBeenInited
1075 FSClearHasBeenInited(
1079 The FSClearHasBeenInited function clears the kHasBeenInited bit in the
1080 finderFlags field of the specified file or directory's finder information.
1082 Note: There is no FSSetHasBeenInited function because ONLY the Finder
1083 should set the kHasBeenInited bit.
1085 ref --> FSRef to a file or directory.
1088 /*****************************************************************************/
1090 #pragma mark FSCopyFileMgrAttributes
1093 FSCopyFileMgrAttributes(
1094 const FSRef *sourceRef,
1095 const FSRef *destinationRef,
1096 Boolean copyLockBit);
1099 The CopyFileMgrAttributes function copies all File Manager attributes
1100 from the source file or directory to the destination file or directory.
1101 If copyLockBit is true, then set the locked state of the destination
1102 to match the source.
1104 sourceRef --> FSRef to a file or directory.
1105 destinationRef --> FSRef to a file or directory.
1106 copyLockBit --> If true, set the locked state of the destination
1107 to match the source.
1110 /*****************************************************************************/
1112 #pragma mark FSMoveRenameObjectUnicode
1115 FSMoveRenameObjectUnicode(
1117 const FSRef *destDirectory,
1118 UniCharCount nameLength,
1119 const UniChar *name, /* can be NULL (no rename during move) */
1120 TextEncoding textEncodingHint,
1121 FSRef *newRef); /* if function fails along the way, newRef is final location of file */
1124 The FSMoveRenameObjectUnicode function moves a file or directory and
1125 optionally renames it. The source and destination locations must be on
1128 Note: If the input ref parameter is invalid, this call will fail and
1129 newRef, like ref, will be invalid.
1131 ref --> FSRef to a file or directory.
1132 destDirectory --> FSRef to the destination directory.
1133 nameLength --> Number of UniChar in name parameter.
1134 name --> An Unicode string with the new name for the
1135 moved object, or NULL if no rename is wanted.
1136 textEncodingHint --> The text encoding hint used for the rename.
1137 You can pass kTextEncodingUnknown to use the
1138 "default" textEncodingHint.
1139 newRef <-- The new FSRef of the object moved. Note that if
1140 this function fails at any step along the way,
1141 newRef is still then final location of the object.
1144 /*****************************************************************************/
1146 #pragma mark FSDeleteContainerContents
1149 FSDeleteContainerContents(
1150 const FSRef *container);
1153 The FSDeleteContainerContents function deletes the contents of a container
1154 directory. All files and subdirectories in the specified container are
1155 deleted. If a locked file or directory is encountered, it is unlocked and
1156 then deleted. If any unexpected errors are encountered,
1157 FSDeleteContainerContents quits and returns to the caller.
1159 container --> FSRef to a directory.
1163 Also see: FSDeleteContainer
1166 /*****************************************************************************/
1168 #pragma mark FSDeleteContainer
1172 const FSRef *container);
1175 The FSDeleteContainer function deletes a container directory and its contents.
1176 All files and subdirectories in the specified container are deleted.
1177 If a locked file or directory is encountered, it is unlocked and then
1178 deleted. After deleting the container's contents, the container is
1179 deleted. If any unexpected errors are encountered, FSDeleteContainer
1180 quits and returns to the caller.
1182 container --> FSRef to a directory.
1186 Also see: FSDeleteContainerContents
1189 /*****************************************************************************/
1191 #pragma mark IterateContainerFilterProcPtr
1193 typedef CALLBACK_API( Boolean , IterateContainerFilterProcPtr ) (
1194 Boolean containerChanged,
1195 ItemCount currentLevel,
1196 const FSCatalogInfo *catalogInfo,
1199 const HFSUniStr255 *name,
1203 This is the prototype for the IterateContainerFilterProc function which
1204 is called once for each file and directory found by FSIterateContainer.
1205 The IterateContainerFilterProc can use the read-only data it receives for
1208 The result of the IterateContainerFilterProc function indicates if
1209 iteration should be stopped. To stop iteration, return true; to continue
1210 iteration, return false.
1212 The yourDataPtr parameter can point to whatever data structure you might
1213 want to access from within the IterateContainerFilterProc.
1215 containerChanged --> Set to true if the container's contents changed
1217 currentLevel --> The current recursion level into the container.
1218 1 = the container, 2 = the container's immediate
1219 subdirectories, etc.
1220 catalogInfo --> The catalog information for the current object.
1221 Only the fields requested by the whichInfo
1222 parameter passed to FSIterateContainer are valid.
1223 ref --> The FSRef to the current object.
1224 spec --> The FSSpec to the current object if the wantFSSpec
1225 parameter passed to FSIterateContainer is true.
1226 name --> The name of the current object if the wantName
1227 parameter passed to FSIterateContainer is true.
1228 yourDataPtr --> An optional pointer to whatever data structure you
1229 might want to access from within the
1231 result <-- To stop iteration, return true; to continue
1232 iteration, return false.
1236 Also see: FSIterateContainer
1239 /*****************************************************************************/
1241 #pragma mark CallIterateContainerFilterProc
1243 #define CallIterateContainerFilterProc(userRoutine, containerChanged, currentLevel, catalogInfo, ref, spec, name, yourDataPtr) \
1244 (*(userRoutine))((containerChanged), (currentLevel), (catalogInfo), (ref), (spec), (name), (yourDataPtr))
1246 /*****************************************************************************/
1248 #pragma mark FSIterateContainer
1252 const FSRef *container,
1253 ItemCount maxLevels,
1254 FSCatalogInfoBitmap whichInfo,
1257 IterateContainerFilterProcPtr iterateFilter,
1261 The FSIterateContainer function performs a recursive iteration (scan) of the
1262 specified container directory and calls your IterateContainerFilterProc
1263 function once for each file and directory found.
1265 The maxLevels parameter lets you control how deep the recursion goes.
1266 If maxLevels is 1, FSIterateContainer only scans the specified directory;
1267 if maxLevels is 2, FSIterateContainer scans the specified directory and
1268 one subdirectory below the specified directory; etc. Set maxLevels to
1269 zero to scan all levels.
1271 The yourDataPtr parameter can point to whatever data structure you might
1272 want to access from within your IterateContainerFilterProc.
1274 container --> The FSRef to the container directory to iterate.
1275 maxLevels --> Maximum number of directory levels to scan or
1276 zero to scan all directory levels.
1277 whichInfo --> The fields of the FSCatalogInfo you wish to get.
1278 wantFSSpec --> Set to true if you want the FSSpec to each
1279 object passed to your IterateContainerFilterProc.
1280 wantName --> Set to true if you want the name of each
1281 object passed to your IterateContainerFilterProc.
1282 iterateFilter --> A pointer to the IterateContainerFilterProc you
1283 want called once for each file and directory found
1284 by FSIterateContainer.
1285 yourDataPtr --> An optional pointer to whatever data structure you
1286 might want to access from within the
1290 /*****************************************************************************/
1292 #pragma mark FSGetDirectoryItems
1295 FSGetDirectoryItems(
1296 const FSRef *container,
1297 FSRef ***refsHandle, /* pointer to handle of FSRefs */
1299 Boolean *containerChanged);
1302 The FSGetDirectoryItems function returns the list of items in the specified
1303 container. The array of FSRef records is returned in a Handle, refsHandle,
1304 which is allocated by FSGetDirectoryItems. The caller is responsible for
1305 disposing of refsHandle if the FSGetDirectoryItems returns noErr.
1307 container --> FSRef to a directory.
1308 refsHandle <-- Pointer to an FSRef Handle where the array of
1309 FSRefs is to be returned.
1310 numRefs <-- The number of FSRefs returned in the array.
1311 containerChanged <-- Set to true if the container changes while the
1312 list of items is being obtained.
1315 /*****************************************************************************/
1317 #pragma mark FSExchangeObjectsCompat
1320 FSExchangeObjectsCompat(
1321 const FSRef *sourceRef,
1322 const FSRef *destRef,
1323 FSRef *newSourceRef,
1327 The FSExchangeObjectsCompat function exchanges the data between two files.
1329 The FSExchangeObjectsCompat function is an enhanced version of
1330 FSExchangeObjects function. The two enhancements FSExchangeObjectsCompat
1333 1, FSExchangeObjectsCompat will work on volumes which do not support
1334 FSExchangeObjects. FSExchangeObjectsCompat does this by emulating
1335 FSExchangeObjects through a series of File Manager operations. If
1336 there is a failure at any step along the way, FSExchangeObjectsCompat
1337 attempts to undo any steps already taken to leave the files in their
1338 original state in their original locations.
1340 2. FSExchangeObjectsCompat returns new FSRefs to the source and
1341 destination files. Note that if this function fails at any step along
1342 the way, newSourceRef and newDestRef still give you access to the final
1343 locations of the files being exchanged -- even if they are renamed or
1344 not in their original locations.
1346 sourceRef --> FSRef to the source file.
1347 destRef --> FSRef to the destination file.
1348 newSourceRef <-- The new FSRef to the source file.
1349 newDestRef <-- The new FSRef to the destination file.
1352 /*****************************************************************************/
1354 #pragma mark ----- Shared Environment Routines -----
1356 /*****************************************************************************/
1358 #pragma mark FSLockRange
1367 The LockRange function locks (denies access to) a portion of a file
1368 that was opened with shared read/write permission.
1370 refNum --> The file reference number of an open file.
1371 rangeLength --> The number of bytes in the range.
1372 rangeStart --> The starting byte in the range to lock.
1376 Also see: UnlockRange
1379 /*****************************************************************************/
1381 #pragma mark FSUnlockRange
1390 The UnlockRange function unlocks (allows access to) a previously locked
1391 portion of a file that was opened with shared read/write permission.
1393 refNum --> The file reference number of an open file.
1394 rangeLength --> The number of bytes in the range.
1395 rangeStart --> The starting byte in the range to unlock.
1402 /*****************************************************************************/
1404 #pragma mark FSGetDirAccess
1409 SInt32 *ownerID, /* can be NULL */
1410 SInt32 *groupID, /* can be NULL */
1411 SInt32 *accessRights); /* can be NULL */
1414 The FSGetDirAccess function retrieves the directory access control
1415 information for a directory on a shared volume.
1417 ref --> An FSRef specifying the directory.
1418 ownerID <** An optional pointer to a SInt32.
1419 If not NULL, the directory's owner ID
1420 will be returned in the SInt32.
1421 groupID <** An optional pointer to a SInt32.
1422 If not NULL, the directory's group ID, or 0
1423 if no group affiliation, will be returned in
1425 accessRights <** An optional pointer to a SInt32.
1426 If not NULL, the directory's access rights
1427 will be returned in the SInt32.
1431 Also see: FSSetDirAccess, FSMapID, FSMapName
1434 /*****************************************************************************/
1436 #pragma mark FSSetDirAccess
1443 SInt32 accessRights);
1446 The FSpSetDirAccess function changes the directory access control
1447 information for a directory on a shared volume. You must be the owner of
1448 a directory to change its access control information.
1450 ref --> An FSRef specifying the directory.
1451 ownerID --> The directory's owner ID.
1452 groupID --> The directory's group ID or 0 if no group affiliation.
1453 accessRights --> The directory's access rights.
1457 Also see: FSGetDirAccess, FSMapID, FSMapName
1460 /*****************************************************************************/
1462 #pragma mark FSGetVolMountInfoSize
1465 FSGetVolMountInfoSize(
1466 FSVolumeRefNum volRefNum,
1470 The FSGetVolMountInfoSize function determines the how much space the
1471 program needs to allocate for a volume mounting information record.
1473 volRefNum --> Volume specification.
1474 size <-- The space needed (in bytes) of the volume
1475 mounting information record.
1479 Also see: FSGetVolMountInfo, VolumeMount
1482 /*****************************************************************************/
1484 #pragma mark FSGetVolMountInfo
1488 FSVolumeRefNum volRefNum,
1489 void *volMountInfo);
1492 The FSGetVolMountInfo function retrieves a volume mounting information
1493 record containing all the information needed to mount the volume,
1494 except for passwords.
1496 volRefNum --> Volume specification.
1497 volMountInfo <-- The volume mounting information.
1501 Also see: FSGetVolMountInfoSize, VolumeMount
1504 /*****************************************************************************/
1506 #pragma mark FSVolumeMount
1510 const void *volMountInfo,
1511 FSVolumeRefNum *volRefNum);
1514 The VolumeMount function mounts a volume using a volume mounting
1517 volMountInfo --> A volume mounting information record.
1518 volRefNum <-- The volume reference number.
1522 Also see: FSGetVolMountInfoSize, FSGetVolMountInfo
1525 /*****************************************************************************/
1527 #pragma mark FSMapID
1531 FSVolumeRefNum volRefNum,
1537 The FSMapID function determines the name of a user or group if you know
1538 the user or group ID.
1540 volRefNum --> Volume specification.
1541 objType --> The mapping function code:
1542 kOwnerID2Name to map a user ID to a user name
1543 kGroupID2Name to map a group ID to a group name
1544 name <** An optional pointer to a buffer (minimum Str31).
1545 If not NULL, the user or group name
1546 will be returned in the buffer.
1550 Also see: FSGetDirAccess, FSSetDirAccess, FSMapName
1553 /*****************************************************************************/
1555 #pragma mark FSMapName
1559 FSVolumeRefNum volRefNum,
1560 ConstStr255Param name,
1565 The FSMapName function determines the user or group ID if you know the
1568 volRefNum --> Volume specification.
1569 name --> The user or group name.
1570 objType --> The mapping function code:
1571 kOwnerName2ID to map a user name to a user ID
1572 kGroupName2ID to map a user name to a group ID
1573 ugID <-- The user or group ID.
1577 Also see: FSGetDirAccess, FSSetDirAccess, FSMapID
1580 /*****************************************************************************/
1582 #pragma mark FSCopyFile
1586 const FSRef *srcFileRef,
1587 const FSRef *dstDirectoryRef,
1588 UniCharCount nameLength,
1589 const UniChar *copyName, /* can be NULL (no rename during copy) */
1590 TextEncoding textEncodingHint,
1591 FSRef *newRef); /* can be NULL */
1594 The FSCopyFile function duplicates a file and optionally renames it.
1595 The source and destination volumes must be on the same file server.
1596 This function instructs the server to copy the file.
1598 srcFileRef --> An FSRef specifying the source file.
1599 dstDirectoryRef --> An FSRef specifying the destination directory.
1600 nameLength --> Number of UniChar in copyName parameter (ignored
1601 if copyName is NULL).
1602 copyName --> Points to the new file name if the file is to be
1603 renamed, or NULL if the file isn't to be renamed.
1604 textEncodingHint --> The text encoding hint used for the rename.
1605 You can pass kTextEncodingUnknown to use the
1606 "default" textEncodingHint.
1607 newRef <** An optional pointer to a FSRef.
1608 If not NULL, the FSRef of the duplicated file
1609 will be returned in the FSRef.
1612 /*****************************************************************************/
1614 #pragma mark FSMoveRename
1618 const FSRef *srcFileRef,
1619 const FSRef *dstDirectoryRef,
1620 UniCharCount nameLength,
1621 const UniChar *moveName, /* can be NULL (no rename during move) */
1622 TextEncoding textEncodingHint,
1623 FSRef *newRef); /* can be NULL */
1626 The FSMoveRename function moves a file or directory (object), and
1627 optionally renames it. The source and destination locations must be on
1628 the same shared volume.
1630 srcFileRef --> An FSRef specifying the source file.
1631 dstDirectoryRef --> An FSRef specifying the destination directory.
1632 nameLength --> Number of UniChar in moveName parameter (ignored
1633 if copyName is NULL)
1634 moveName --> Points to the new object name if the object is to be
1635 renamed, or NULL if the object isn't to be renamed.
1636 textEncodingHint --> The text encoding hint used for the rename.
1637 You can pass kTextEncodingUnknown to use the
1638 "default" textEncodingHint.
1639 newRef <** An optional pointer to a FSRef.
1640 If not NULL, the FSRef of the moved object
1641 will be returned in the FSRef.
1644 /*****************************************************************************/
1646 #pragma mark ----- File ID Routines -----
1648 /*****************************************************************************/
1650 #pragma mark FSResolveFileIDRef
1654 FSVolumeRefNum volRefNum,
1659 The FSResolveFileIDRef function returns an FSRef for the file with the
1660 specified file ID reference.
1662 volRefNum --> Volume specification.
1663 fileID --> The file ID reference.
1664 ref <-- The FSRef for the file ID reference.
1668 Also see: FSCreateFileIDRef, FSDeleteFileIDRef
1671 /*****************************************************************************/
1673 #pragma mark FSCreateFileIDRef
1681 The FSCreateFileIDRef function creates a file ID reference for the
1682 specified file, or if a file ID reference already exists, supplies
1683 the file ID reference and returns the result code fidExists or afpIDExists.
1685 ref --> The FSRef for the file.
1686 fileID <-- The file ID reference (if result is noErr,
1687 fidExists, or afpIDExists).
1691 Also see: GetFSRefFromFileIDRef, FSDeleteFileIDRef
1694 /*****************************************************************************/
1696 #pragma mark FSDeleteFileIDRef
1699 Why is there no FSDeleteFileIDRef routine? There are two reasons:
1701 1. Since Mac OS 8.1, PBDeleteFileIDRef hasn't deleted file ID references.
1702 On HFS volumes, deleting a file ID reference breaks aliases (which
1703 use file ID references to track files as they are moved around on a
1704 volume) and file ID references are automatically deleted when the file
1705 they refer to is deleted. On HFS Plus volumes, file ID references are
1706 always created when a file is created, deleted when the file is deleted,
1707 and cannot be deleted at any other time.
1709 2. PBDeleteFileIDRef causes a memory access fault under Mac OS X 10.0
1710 through 10.1.x. While this will be fixed in a future release, the
1711 implementation, like the Mac OS 8/9 implementation, does not delete
1716 Also see: GetFSRefFromFileIDRef, FSCreateFileIDRef
1719 /*****************************************************************************/
1721 #pragma mark ----- Utility Routines -----
1723 /*****************************************************************************/
1725 #pragma mark GetTempBuffer
1729 ByteCount buffReqSize,
1730 ByteCount *buffActSize);
1733 The GetTempBuffer function allocates a temporary buffer for file system
1734 operations which is at least 4K bytes and a multiple of 4K bytes.
1736 buffReqSize --> Size you'd like the buffer to be.
1737 buffActSize <-- The size of the buffer allocated.
1738 function result <-- Pointer to memory allocated, or NULL if no memory
1739 was available. The caller is responsible for
1740 disposing of this buffer with DisposePtr.
1743 /*****************************************************************************/
1745 #pragma mark FileRefNumGetFSRef
1753 The FileRefNumGetFSRef function gets the FSRef of an open file.
1755 refNum --> The file reference number of an open file.
1756 ref <-- The FSRef to the open file.
1759 /*****************************************************************************/
1761 #pragma mark FSSetDefault
1765 const FSRef *newDefault,
1769 The FSSetDefault function sets the current working directory to the
1770 directory specified by newDefault. The previous current working directory
1771 is returned in oldDefault and must be used to restore the current working
1772 directory to its previous state with the FSRestoreDefault function.
1773 These two functions are designed to be used as a wrapper around
1774 Standard I/O routines where the location of the file is implied to be the
1775 current working directory. This is how you should use these functions:
1777 result = FSSetDefault(&newDefault, &oldDefault);
1778 if ( noErr == result )
1780 // call the Stdio functions like remove, rename,
1781 // fopen, freopen, etc here!
1783 result = FSRestoreDefault(&oldDefault);
1786 newDefault --> An FSRef that specifies the new current working
1788 oldDefault <-- The previous current working directory's FSRef.
1792 Also see: FSRestoreDefault
1795 /*****************************************************************************/
1797 #pragma mark FSRestoreDefault
1801 const FSRef *oldDefault);
1804 The FSRestoreDefault function restores the current working directory
1805 to the directory specified by oldDefault. The oldDefault parameter was
1806 previously obtained from the FSSetDefault function.
1807 These two functions are designed to be used as a wrapper around
1808 Standard I/O routines where the location of the file is implied to be the
1809 current working directory. This is how you should use these functions:
1811 result = FSSetDefault(&newDefault, &oldDefault);
1812 if ( noErr == result )
1814 // call the Stdio functions like remove, rename,
1815 // fopen, freopen, etc here!
1817 result = FSRestoreDefault(&oldDefault);
1820 oldDefault --> The FSRef of the location to restore.
1824 Also see: FSSetDefault
1827 /*****************************************************************************/
1829 #if PRAGMA_STRUCT_ALIGN
1830 #pragma options align=reset
1831 #elif PRAGMA_STRUCT_PACKPUSH
1833 #elif PRAGMA_STRUCT_PACK
1837 #ifdef PRAGMA_IMPORT_OFF
1840 #pragma import reset
1847 #endif /* __MOREFILESX__ */