Files(3)

NAME
Mac::Files - Macintosh Toolbox Interface to the File and Alias Manager

DESCRIPTION

  Constants
Constants for file access permissions. Use these constants to request a type of access to a file or fork, or to deny a type of access to a file or fork to other paths that may request access.

Note that it is possible, on Mac OS 8 and 9, to open a file residing on read-only media with write access. On Mac OS X, however, you cannot open a file with write access on read-only media; the attempt to open the file fails with a wrPermErr error.

fsCurPerm
    Requests whatever permissions are currently allowed. If write access is unavailable (because the file is locked or the file is already open with write permission), then read permission is granted. Otherwise read/write permission is granted.

fsRdPerm
    Requests permission to read the file.

fsWrPerm
    Requests permission to write to the file. If write permission is granted, no other access paths are granted write permission. Note, however, that the File Manager does not support write-only access to a file. Thus, fsWrPerm is synonymous with fsRdWrPerm.

fsRdWrPerm
    Requests exclusive read and write permission. If exclusive read/write permission is granted, no other users are granted permission to write to the file. Other users may, however, be granted permission to read the file.

fsRdWrShPerm
    Requests shared read and write permission. Shared read/write permission allows mutliple access paths for reading and writing. This is safe only if there is some way of locking portions of the file before writing to them. Use the functions PBLockRangeSync and PBUnlockRangeSync to lock and unlock ranges of bytes within a file. On Mac OS 8 and 9, these functions are supported only on remotely mounted volumes, or on local volumes that are shareable on the network. You should check that range locking is available before requesting shared read/ write permission. On Mac OS X, range locking is available on all volumes.

fsRdDenyPerm
    Requests that any other paths be prevented from having read access. A path cannot be opened if you request read permission (with the fsRdPerm constant) but some other path has requested deny-read access. Similarly, the path cannot be opened if you request deny-read permission, but some other path already has read access. This constant is used with the PBHOpenDenySync and PBHOpenRFDenySync functions.

fsWrDenyPerm
    Requests that any other paths be prevented from having write access. A path cannot be opened if you request write permission (with the fsWrPerm constant) but some other path has requested deny-write access. Similarly, the path cannot be opened if you request deny-write permission, but some other path already has write access. This constant is used with the PBHOpenDenySync and PBHOpenRFDenySync functions.

ioFlAttrib bits, returned by FSpGetCatInfo.

kioFlAttribLocked
    Set if file or directory is locked

kioFlAttribResOpen
    Set if resource fork is open

kioFlAttribDataOpen
    Set if data fork is open

kioFlAttribDir
    Set if this is a directory

kioFlAttribCopyProt
    Set if AppleShare server "copy-protects" the file

kioFlAttribFileOpen
    Set if file (either fork) is open

kioFlAttribInShared
    Set if the directory is within a shared area of the directory hierarchy

kioFlAttribMounted
    Set if the directory is a share point that is mounted by some user

kioFlAttribSharePoint
    Set if the directory is a share point

Finder flags

kIsOnDesk
    Files and folders (System 6)

kColor
    Files and folders; bit 0x0020 was kRequireSwitchLaunch, but is now reserved for future use

kIsShared
    Files only (Applications only); if clear, the application needs to write to its resource fork, and therefore cannot be shared on a server

kHasNoINITs
    Files only (Extensions/Control Panels only); this file contains no INIT resource

kHasBeenInited
    Files only; clear if the file contains desktop database; resources ('BNDL', 'FREF', 'open', 'kind'...) that have not been added yet. Set only by the Finder; reserved for folders - make sure this bit is cleared for folders; bit 0x0200 was the letter bit for AOCE, but is now reserved for future use

kHasCustomIcon
    Files and folders

kIsStationery
    Files only

kNameLocked
    Files and folders

kHasBundle
    Files only

kIsInvisible
    Files and folders

kIsAlias
    Files only

AppleTalk/GetAliasInfo Constants

asiZoneName
    Return AppleTalk zone name from GetAliasInfo.

asiServerName
    Return AppleTalk server name from GetAliasInfo.

asiVolumeName
    Return volume name from GetAliasInfo.

asiAliasName
    Return last component of target file name from GetAliasInfo.

asiParentName
    Return name of enclosing folder from GetAliasInfo. This index value is 1. Higher indices will return folder names higher up the hierarchy.

Folder type constants. Specify a type of folder on a particular volume. Use in vRefNum parameter of FindFolder().

kOnSystemDisk
    previously was 0x8000 but that is an unsigned value whereas vRefNum is signed

kOnAppropriateDisk
    Generally, the same as kOnSystemDisk, but it's clearer that this isn't always the 'boot' disk.

Folder Domains - Carbon only. The constants above can continue to be used, but the folder/volume returned will be from one of the domains below.

kSystemDomain
    Read-only system hierarchy.

kLocalDomain
    All users of a single machine have access to these resources.

kNetworkDomain
    All users configured to use a common network server has access to these resources.

kUserDomain
    Read/write. Resources that are private to the user.

kClassicDomain
    Domain referring to the currently configured Classic System Folder

kLastDomainConstant
    The ID of the last domain in the above list, used by the Folder Manager to determine if a given parameter should be treated as a domain or a volume...

Constants for createFolder parameter of FindFolder().

kCreateFolder
kDontCreateFolder

Folder Type Constants for FindFolder().

kSystemFolderType
    the system folder

kDesktopFolderType
    the desktop folder; objects in this folder show on the desk top.

kSystemDesktopFolderType
    the desktop folder at the root of the hard drive, never the redirected user desktop folder

kTrashFolderType
    the trash folder; objects in this folder show up in the trash

kSystemTrashFolderType
    the trash folder at the root of the drive, never the redirected user trash folder

kWhereToEmptyTrashFolderType
    the "empty trash" folder; Finder starts empty from here down

kPrintMonitorDocsFolderType
    Print Monitor documents

kStartupFolderType
    Finder objects (applications, documents, DAs, aliases, to...) to open at startup go here

kShutdownFolderType
    Finder objects (applications, documents, DAs, aliases, to...) to open at shutdown go here

kAppleMenuFolderType
    Finder objects to put into the Apple menu go here

kControlPanelFolderType
    Control Panels go here (may contain INITs)

kSystemControlPanelFolderType
    System control panels folder - never the redirected one, always "Control Panels" inside the System Folder

kExtensionFolderType
    System extensions go here

kFontsFolderType
    Fonts go here

kPreferencesFolderType
    preferences for applications go here

kSystemPreferencesFolderType
    System-type Preferences go here - this is always the system's preferences folder, never a logged in user's

kTemporaryFolderType
    temporary files go here (deleted periodically, but don't rely on it.)

kExtensionDisabledFolderType
kControlPanelDisabledFolderType
kSystemExtensionDisabledFolderType
kStartupItemsDisabledFolderType
kShutdownItemsDisabledFolderType
kApplicationsFolderType
kDocumentsFolderType

New Constants

kVolumeRootFolderType
    root folder of a volume

kChewableItemsFolderType
    items deleted at boot

kApplicationSupportFolderType
    third-party items and folders

kTextEncodingsFolderType
    encoding tables

kStationeryFolderType
    stationery

kOpenDocFolderType
    OpenDoc root

kOpenDocShellPlugInsFolderType
    OpenDoc Shell Plug-Ins in OpenDoc folder

kEditorsFolderType
    OpenDoc editors in Mac OS Folder

kOpenDocEditorsFolderType
    OpenDoc subfolder of Editors folder

kOpenDocLibrariesFolderType
    OpenDoc libraries folder

kGenEditorsFolderType
    CKH general editors folder at root level of Sys folder

kHelpFolderType
    CKH help folder currently at root of system folder

kInternetPlugInFolderType
    CKH internet plug ins for browsers and stuff

kModemScriptsFolderType
    CKH modem scripts, get 'em OUT of the Extensions folder

kPrinterDescriptionFolderType
    CKH new folder at root of System folder for printer descs.

kPrinterDriverFolderType
    CKH new folder at root of System folder for printer drivers

kScriptingAdditionsFolderType
    CKH at root of system folder

kSharedLibrariesFolderType
    CKH for general shared libs.

kVoicesFolderType
    CKH macintalk can live here

kControlStripModulesFolderType
    CKH for control strip modules

kAssistantsFolderType
    SJF for Assistants (Mac OS Setup Assistant, etc)

kUtilitiesFolderType
    SJF for Utilities folder

kAppleExtrasFolderType
    SJF for Apple Extras folder

kContextualMenuItemsFolderType
    SJF for Contextual Menu items

kMacOSReadMesFolderType
    SJF for Mac OS ReadMes folder

kALMModulesFolderType
    EAS for Location Manager Module files except type 'thng' (within kExtensionFolderType)

kALMPreferencesFolderType
    EAS for Location Manager Preferences (within kPreferencesFolderType; contains kALMLocationsFolderType)

kALMLocationsFolderType
    EAS for Location Manager Locations (within kALMPreferencesFolderType)

kColorSyncProfilesFolderType
    for ColorSync Profiles

kThemesFolderType
    for Theme data files

kFavoritesFolderType
    Favorties folder for Navigation Services

kInternetFolderType
    Internet folder (root level of startup volume)

kAppearanceFolderType
    Appearance folder (root of system folder)

kSoundSetsFolderType
    Sound Sets folder (in Appearance folder)

kDesktopPicturesFolderType
    Desktop Pictures folder (in Appearance folder)

kInternetSearchSitesFolderType
    Internet Search Sites folder

kFindSupportFolderType
    Find support folder

kFindByContentFolderType
    Find by content folder

kInstallerLogsFolderType
    Installer Logs folder

kScriptsFolderType
    Scripts folder

kFolderActionsFolderType
    Folder Actions Scripts folder

kLauncherItemsFolderType
    Launcher Items folder

kRecentApplicationsFolderType
    Recent Applications folder

kRecentDocumentsFolderType
    Recent Documents folder

kRecentServersFolderType
    Recent Servers folder

kSpeakableItemsFolderType
    Speakable Items folder

kKeychainFolderType
    Keychain folder

kQuickTimeExtensionsFolderType
    QuickTime Extensions Folder (in Extensions folder)

kDisplayExtensionsFolderType
    Display Extensions Folder (in Extensions folder)

kMultiprocessingFolderType
    Multiprocessing Folder (in Extensions folder)

kPrintingPlugInsFolderType
    Printing Plug-Ins Folder (in Extensions folder)

New Folder Types to accommodate the Mac OS X Folder Manager These folder types are not applicable on Mac OS 9.

kDomainTopLevelFolderType
    The top-level of a Folder domain, e.g. "/System"

kDomainLibraryFolderType
    the Library subfolder of a particular domain

kColorSyncFolderType
    Contains ColorSync-related folders

kColorSyncCMMFolderType
    ColorSync CMMs

kColorSyncScriptingFolderType
    ColorSync Scripting support

kPrintersFolderType
    Contains Printing-related folders

kSpeechFolderType
    Contains Speech-related folders

kCarbonLibraryFolderType
    Contains Carbon-specific file

kDocumentationFolderType
    Contains Documentation files (not user documents)

kDeveloperDocsFolderType
    Contains Developer Documentation files and folders

kDeveloperHelpFolderType
    Contains Developer Help related files

kISSDownloadsFolderType
    Contains Internet Search Sites downloaded from the Internet

kUserSpecificTmpFolderType
    Contains temporary items created on behalf of the current user

kCachedDataFolderType
    Contains various cache files for different clients

kFrameworksFolderType
    Contains Mac OS X Framework folders

kPrivateFrameworksFolderType
    Contains Mac OS X Private Framework folders

kClassicDesktopFolderType
    Mac OS 9 compatible desktop folder - same as kSystemDesktopFolderType but with a more appropriate name for Mac OS X code.

kDeveloperFolderType
    Contains Mac OS X Developer Resources

kSystemSoundsFolderType
    Contains Mac OS X System Sound Files

kComponentsFolderType
    Contains Mac OS X components

kQuickTimeComponentsFolderType
    Contains QuickTime components for Mac OS X

kCoreServicesFolderType
    Refers to the "CoreServices" folder on Mac OS X

kPictureDocumentsFolderType
    Refers to the "Pictures" folder in a users home directory

kMovieDocumentsFolderType
    Refers to the "Movies" folder in a users home directory

kMusicDocumentsFolderType
    Refers to the "Music" folder in a users home directory

kInternetSitesFolderType
    Refers to the "Sites" folder in a users home directory

kPublicFolderType
    Refers to the "Public" folder in a users home directory

kAudioSupportFolderType
    Refers to the Audio support folder for Mac OS X

kAudioSoundsFolderType
    Refers to the Sounds subfolder of Audio Support

kAudioSoundBanksFolderType
    Refers to the Banks subfolder of the Sounds Folder

kAudioAlertSoundsFolderType
    Refers to the Alert Sounds subfolder of the Sound Folder

kAudioPlugInsFolderType
    Refers to the Plug-ins subfolder of the Audio Folder

kAudioComponentsFolderType
    Refers to the Components subfolder of the Audio Plug-ins Folder

kKernelExtensionsFolderType
    Refers to the Kernel Extensions Folder on Mac OS X

kDirectoryServicesFolderType
    Refers to the Directory Services folder on Mac OS X

kDirectoryServicesPlugInsFolderType
    Refers to the Directory Services Plug-Ins folder on Mac OS X

kInstallerReceiptsFolderType
    Refers to the "Receipts" folder in Mac OS X

kFileSystemSupportFolderType
    Refers to the [domain]/Library/Filesystems folder in Mac OS X

kAppleShareSupportFolderType
    Refers to the [domain]/Library/Filesystems/AppleShare folder in Mac OS X

kAppleShareAuthenticationFolderType
    Refers to the [domain]/Library/Filesystems/AppleShare/Authentication folder in Mac OS X

kMIDIDriversFolderType
    Refers to the MIDI Drivers folder on Mac OS X

kKeyboardLayoutsFolderType
    Refers to the [domain]/Library/KeyboardLayouts folder in Mac OS X

kIndexFilesFolderType
    Refers to the [domain]/Library/Indexes folder in Mac OS X

kFindByContentIndexesFolderType
    Refers to the [domain]/Library/Indexes/FindByContent folder in Mac OS X

kManagedItemsFolderType
    Refers to the Managed Items folder for Mac OS X

kBootTimeStartupItemsFolderType
    Refers to the "StartupItems" folder of Mac OS X

More Folder Constants

kLocalesFolderType
    PKE for Locales folder

kFindByContentPluginsFolderType
    Find By Content Plug-ins

kUsersFolderType
    "Users" folder, contains one folder for each user.

kCurrentUserFolderType
    The folder for the currently logged on user.

kCurrentUserRemoteFolderLocation
    The remote folder for the currently logged on user

kCurrentUserRemoteFolderType
    The remote folder location for the currently logged on user

kSharedUserDataFolderType
    A Shared "Documents" folder, readable & writeable by all users

kVolumeSettingsFolderType
    Volume specific user information goes here

kAppleshareAutomountServerAliasesFolderType
    Appleshare puts volumes to automount inside this folder.

kPreMacOS91ApplicationsFolderType
    The "Applications" folder, pre Mac OS 9.1

kPreMacOS91InstallerLogsFolderType
    The "Installer Logs" folder, pre Mac OS 9.1

kPreMacOS91AssistantsFolderType
    The "Assistants" folder, pre Mac OS 9.1

kPreMacOS91UtilitiesFolderType
    The "Utilities" folder, pre Mac OS 9.1

kPreMacOS91AppleExtrasFolderType
    The "Apple Extras" folder, pre Mac OS 9.1

kPreMacOS91MacOSReadMesFolderType
    The "Mac OS ReadMes" folder, pre Mac OS 9.1

kPreMacOS91InternetFolderType
    The "Internet" folder, pre Mac OS 9.1

kPreMacOS91AutomountedServersFolderType
    The "Servers" folder, pre Mac OS 9.1

kPreMacOS91StationeryFolderType
    The "Stationery" folder, pre Mac OS 9.1

  Types

FInfo
    Information for a file, including:

        OSType     fdType            the type of the file
        OSType     fdCreator         file's creator
        U16        fdFlags           flags ex. hasbundle,invisible,locked, etc.
        Point      fdLocation        file's location in folder

FXInfo
    Further information for a file, including:

        short      fdIconID          Icon ID
        I8         fdScript          Script flag and number
        I8         fdXFlags          More flag bits
        short      fdComment         Comment ID
        long       fdPutAway         Home Dir ID

DInfo
    Information for a directory, including:

        Rect       frRect            folder rect
        U16        frFlags           Flags
        Point      frLocation        folder location
        short      frView            folder view

DXInfo
    Further information for a directory, including:

        Point      frScroll          scroll position
        long       frOpenChain       DirID chain of open folders
        I8         frScript          Script flag and number
        I8         frXFlags          More flag bits
        short      frComment         comment
        long       frPutAway         DirID

CatInfo
    Catalog information of a file or a directory, including:

        Str255     ioNamePtr         ptr to Vol:FileName string
        short      ioVRefNum         volume refnum (DrvNum for Eject and MountVol)
        short      ioFRefNum         reference number
        I8         ioFVersNum        version number
        short      ioFDirIndex       GetFInfo directory index
        I8         ioFlAttrib        GetFInfo: in-use bit=7, lock bit=0
        I8         ioACUser          access rights for directory only
        FInfo      ioFlFndrInfo      user info
        long       ioDirID           A directory ID
        U16        ioFlStBlk         start file block (0 if none)
        long       ioFlLgLen         logical length (EOF)
        long       ioFlPyLen         physical length
        U16        ioFlRStBlk        start block rsrc fork
        long       ioFlRLgLen        file logical length rsrc fork
        long       ioFlRPyLen        file physical length rsrc fork
        time_t     ioFlCrDat         file creation date& time
        time_t     ioFlMdDat         last modified date and time
        time_t     ioFlBkDat
        FXInfo     ioFlXFndrInfo
        long       ioFlParID
        long       ioFlClpSiz
        DInfo      ioDrUsrWds
        long       ioDrDirID
        U16        ioDrNmFls
        time_t     ioDrCrDat
        time_t     ioDrMdDat
        time_t     ioDrBkDat
        DXInfo     ioDrFndrInfo
        long       ioDrParID

  Functions

FSpGetCatInfo FILE [, INDEX ]
    If INDEX is omitted or 0, returns information about the specified file or folder. If INDEX is nonzero, returns information obout the nth item in the specified folder.

FSpSetCatInfo FILE, INFO
    Change information about the specified file.

FSMakeFSSpec VREF, DIRID, NAME
    Creates a file system specification record from a volume number, directory ID, and name. This call never returns a path name.

FSpCreate FILE, CREATOR, TYPE [, SCRIPTTAG]
    Creates a file with the specified file creator and type. You don't want to know what a script tag is.

FSpDirCreate FILE [, SCRIPTTAG]
    Creates a directory and returns its ID.

FSpDelete FILE
    End the sad existence of a file or (empty) folder.

FSpGetFInfo FILE
    Returns finder info about a specified file.

FSpSetFInfo FILE, INFO
    Changes the finder info about a specified file.

FSpSetFLock FILE
    Software lock a file.

FSpRstFLock FILE
    Unlock a file.

FSpRename FILE, NAME
    Rename a file (only the name component).

FSpCatMove FILE, FOLDER
    Move a file into a different folder.

FSpExchangeFiles FILE1, FILE2
    Swap the contents of two files, e.g. if you saved to a temp file and finally swap it with the original.

NewAlias FILE
    Returns an AliasHandle for the file.

NewAliasRelative FROM, FILE
    Returns a AliasHandle relative to FROM for the file.

NewAliasMinimal FILE
    Returns an AliasHandle containing minimal information for the file. This type of alias is best suited for short lived aliases, e.g. in AppleEvents.

NewAliasMinimalFromFullPath NAME [, ZONE [, SERVER]]
    Create a new alias containing only the path name.

UpdateAlias TARGET, ALIAS
    Updates an alias to point to the target file. Returns whether the alias was changed..

UpdateAliasRelative FROM, TARGET, ALIAS
    Updates an alias to point to the target file relative to FROM. Returns whether the alias was changed..

ResolveAlias ALIAS
    Resolves an alias. In scalar context, returns the path to the resolved file. In list context, also returns whether the alias was changed when resolving.

ResolveAliasRelative FROM, ALIAS
    Resolves an alias relative to a file. In scalar context, returns the path to the resolved file. In list context, also returns whether the alias was changed when resolving.

GetAliasInfo ALIAS, INDEX
    Return a component of the alias information.

UnmountVol (VOLUMENAME | VOLUMENR)
    Unmounts a volume.

Eject (VOLUMENAME | VOLUMENR)
    Mac OS only.

    Ejects a volume, placing it offline.

FlushVol (VOLUMENAME | VOLUMENR)
    Flush pending write operations on a volume.

FindFolder VREF, FOLDERTYPE [, CREATE]
    Returns a path to a special folder on the given volume (specify "kOnSystemDisk" for the boot volume). For FOLDERTYPE, you can specify any of the "kXXXFolderType" constants listed above.

AUTHOR
Written by Matthias Ulrich Neeracher <neeracher@mac.com>. Currently maintained by Chris Nandor <pudge@pobox.com>.