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 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>.
perl v5.16.2 2013-08-25 Files(3)