ADC Home > Reference Library > Reference > Mac OS X > Mac OS X Man Pages

 

This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

For more information about the manual page format, see the manual page for manpages(5).



Files(3)                             User Contributed Perl Documentation                            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 denyread
           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 denywrite
           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 ColorSyncX 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>.



perl v5.8.8                                      2007-09-23                                         Files(3)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.