---

Property List Key Reference

The following sections contain detailed information about the usage and behavior of property-list keys available for use in an information property list file.

Contents:

Key Summary
Key Descriptions

Key Summary

Table 1 contains an alphabetical list of the keys you can use in an information property list file, along with a brief description and the platforms to which they apply (Mac OS X or iPhone). For detailed descriptions of these keys, see “Key Descriptions .”

Key Descriptions

Mac OS X provides a set of core keys for specifying information about a bundle. Some of these keys are given default values by the Xcode application depending on the type of project you create.

APInstallerURL

APInstallerURL (String) identifies the base path to the files you want to install. You must specify this path using the form file://localhost/path/. All installed files must reside within this directory.

APFiles

APFiles (Array) specifies a file or directory you want to install. You specify this key as a dictionary, the contents of which contains information about the file or directory you want to install. To specify multiple items, nest the APFiles key inside itself to specify files inside of a directory. Table 2 lists the keys for specifying information about a single file or directory.

ATSApplicationFontsPath

ATSApplicationFontsPath (String) identifies the location of a font file or directory of fonts in the bundle’s Resources directory. If present, Mac OS X activates the fonts at the specified path for use by the bundled application. The fonts are activated only for the bundled application and not for the system as a whole. The path itself should be specified as a relative directory of the bundle’s Resources directory. For example, if a directory of fonts was at the path /Applications/MyApp.app/Contents/Resources/Stuff/MyFonts/, you should specify the string Stuff/MyFonts/ for the value of this key.

CFAppleHelpAnchor

CFAppleHelpAnchor (String) identifies the name of the bundle’s initial HTML help file, minus the .html or .htm extension. This file must be located in the bundle’s localized resource directories or, if the help is not localized, directly under the Resources directory.

CFBundleAllowMixedLocalizations

CFBundleAllowMixedLocalizations (Boolean) specifies whether the bundle supports the retrieval of localized strings from frameworks. This key is used primarily by Foundation tools that link to other system frameworks and want to retrieve localized resources from those frameworks.

CFBundleDevelopmentRegion

CFBundleDevelopmentRegion (String) specifies the native region for the bundle. This key contains a string value that usually corresponds to the native language of the person who wrote the bundle. The language specified by this value is used as the default language if a resource cannot be located for the user’s preferred region or language.

CFBundleDisplayName

CFBundleDisplayName (String) specifies the display name of the bundle. If you support localized names for your bundle, include this key in both your information property list file and in the InfoPlist.strings files of your language subdirectories. If you localize this key, you should also include a localized version of the CFBundleName key.

If you do not intend to localize your bundle, do not include this key in your Info.plist file. Inclusion of this key does not affect the display of the bundle name but does incur a performance penalty to search for localized versions of this key.

Before displaying a localized name for your bundle, the Finder compares the value of this key against the actual name of your bundle in the file system. If the two names match, the Finder proceeds to display the localized name from the appropriate InfoPlist.strings file of your bundle. If the names do not match, the Finder displays the file-system name.

See File System Overview for more information on display names.

CFBundleDocumentTypes

CFBundleDocumentTypes (DictionaryArray) associates a document type with your application using a set of dictionaries. Each dictionary is called a type-definition dictionary and contains keys used to define the document type. Table 3 lists the keys that are supported in these dictionaries:

When registering document types, you must specify at least one of the keys LSItemContentTypes, CFBundleTypeExtensions, CFBundleTypeMIMETypes, or CFBundleTypeOSTypes along with the appropriate data. If you do not specify at least one of these keys, no document types are bound to the type-name specifier. You may use all three keys when binding your document type, if you so choose. In Mac OS X v10.4 and later, if you specify the LSItemContentTypes key, the other keys are ignored.

CFBundleExecutable

CFBundleExecutable (String) identifies the name of the bundle’s main executable file. For an application, this is the application executable. For a loadable bundle, it is the binary that will be loaded dynamically by the bundle. For a framework, it is the shared library for the framework. Xcode automatically adds this key to the information property list file of appropriate projects.

For frameworks, the value of this key is required to be the same as the framework name, minus the .framework extension. If the keys are not the same, the target system may incur some launch-performance penalties. for launch-performance reasons. The value should not include any extension on the name.

CFBundleGetInfoString

CFBundleGetInfoString (String) provides a brief description of the bundle. For an application bundle, this key provides a short description of the application or the current release that the build or release version number cannot convey; for example, the date of the release. This key can be localized.

CFBundleHelpBookFolder

CFBundleHelpBookFolder (String) identifies the folder containing the bundle’s help files. Help is usually localized to a specific language, so the folder specified by this key represents the folder name inside the .lproj directory for the selected language.

CFBundleHelpBookName

CFBundleHelpBookName (String) identifies the main help page for your application. This key identifies the name of the Help page, which may not correspond to the name of the HTML file. The Help page name is specified in the CONTENT attribute of the help file’s META tag.

CFBundleIconFile

CFBundleIconFile (String) identifies the file containing the icon for the bundle. The filename you specify does not need to include the extension, although it may. The Finder looks for the icon file in the Resources directory of the bundle.

If your bundle uses a custom icon, you must specify this property. If you do not specify this property, the Finder (and other applications) display your bundle with a default icon.

CFBundleIdentifier

CFBundleIdentifier (String) identifies the type of the bundle. This identifier should be a uniform type identifier (UTI) string, for example com.mycompany.MyApp. This key does not uniquely identify a specific bundle in the file system, as multiple copies of an application with the same or different version may exist. See Uniform Type Identifiers Overview for details on UTIs.

The preferences system uses this string to identify the application for which a given preference applies. Launch Services uses the bundle identifier to locate an application capable of opening a particular file, using the first application it finds with the given identifier.

CFBundleInfoDictionaryVersion

CFBundleInfoDictionaryVersion (String) identifies the current version of the property list structure. This key exists to support future versioning of the information property list file format. Xcode generates this key automatically when you build a bundle and you should not change it manually. The value for this key is currently 6.0.

CFBundleLocalizations

CFBundleLocalizations (Array) identifies the localizations handled manually by your application. If your executable is unbundled or does not use the existing bundle localization mechanism, you can include this key to specify the localizations your application does handle.

Each entry in this property’s array is a string identifying the language name or ISO language designator of the supported localization. See “Language Designations” in Internationalization Programming Topics in Internationalization Documentation for information on how to specify language designators.

CFBundleName

CFBundleName (String) identifies the short name of the bundle. This name should be less than 16 characters long and be suitable for displaying in the menu bar and the application’s Info window. You can include this key in the InfoPlist.strings file of an appropriate .lproj subdirectory to provide localized values for it. If you localize this key, you should also include the key “CFBundleDisplayName.”

CFBundlePackageType

CFBundlePackageType (String) identifies the type of the bundle and is analogous to the Mac OS 9 file type code. The value for this key consists of a four-letter code. The type code for applications is APPL; for frameworks, it is FMWK; for loadable bundles, it is BNDL. For loadable bundles, you can also choose a type code that is more specific than BNDL if you want.

CFBundleShortVersionString

CFBundleShortVersionString (String) specifies the release version number of the bundle, which identifies a released iteration of the application. The release version number is a string comprised of three period-separated integers. The first integer represents major revisions to the application, such as revisions that implement new features or major changes. The second integer denotes revisions that implement less prominent features. The third integer represents maintenance releases.

The value for this key differs from the value for “CFBundleVersion,” which identifies an iteration (released or unreleased) of the application.

CFBundleSignature

CFBundleSignature String) identifies the creator of the bundle and is analogous to the Mac OS 9 file creator code. The value for this key is a string containing a four-letter code that is specific to the bundle. For example, the signature for the TextEdit application is ttxt.

CFBundleURLTypes

CFBundleURLTypes DictionaryArray describes the URL schemes (http, ftp, and so on) supported by the application. The purpose of this key is similar to that of “CFBundleDocumentTypes,” but it describes URL schemes instead of document types. Each dictionary entry corresponds to a single URL scheme. Table 4 lists the keys to use in each dictionary entry.

CFBundleVersion

CFBundleVersion (String) specifies the build version number of the bundle, which identifies an iteration (released or unreleased) of the bundle. This is a monotonically increased string, comprised of one or more period-separated integers. This key is not localizable.

CFPlugInDynamicRegistration

CFPlugInDynamicRegistration (String) specifies whether how host loads this plug-in. If the value is YES, the host attempts to load this plug-in using its dynamic registration function. If the value is NO, the host uses the static registration information included in the “CFPlugInFactories,” and “CFPlugInTypes” keys.

See “Plug-in Registration” in Plug-ins for information about registering plug-ins.

CFPlugInDynamicRegisterFunction

CFPlugInDynamicRegisterFunction (String) identifies the function to use when dynamically registering a plug-in. Specify this key if you want to specify one of your own functions instead of implement the default CFPlugInDynamicRegister function.

See “Plug-in Registration” in Plug-ins for information about registering plug-ins.

CFPlugInFactories

CFPlugInFactories (Dictionary) is used for static plug-in registration. It contains a dictionary identifying the interfaces supported by the plug-in. Each key in the dictionary is a universally unique ID (UUID) representing the supported interface. The value for the key is a string with the name of the plug-in factory function to call.

See “Plug-in Registration” in Plug-ins for information about registering plug-ins.

CFPlugInTypes

CFPlugInTypes (Dictionary) is used for static plug-in registration. It contains a dictionary identifying one or more groups of interfaces supported by the plug-in. Each key in the dictionary is a universally unique ID (UUID) representing the group of interfaces. The value for the key is an array of strings, each of which contains the UUID for a specific interface in the group. The UUIDs in the array corresponds to entries in the “CFPlugInFactories” dictionary.

See “Plug-in Registration” in Plug-ins for information about registering plug-ins.

CFPlugInUnloadFunction

CFPlugInUnloadFunction String) specifies the name of the function to call when it is time to unload the plug-in code from memory. This function gives the plug-in an opportunity to clean up any data structures it allocated.

See “Plug-in Registration” in Plug-ins for information about registering plug-ins.

CSResourcesFileMapped

CSResourcesFileMapped Boolean) specifies whether to map this application’s resource files into memory. Otherwise, they are read into memory normally. File mapping can improve performance in situations where you are frequently accessing a small number of resources. However, resources are mapped into memory read-only and cannot be modified.

LSArchitecturePriority

LSArchitecturePriority (StringArray) identifies the architectures this application supports. The order of the strings in this array dictate the preferred execution priority for the architectures. The possible strings for this array are listed in Table 5.

if a PowerPC architecture appears before either of the Intel architectures, Mac OS X runs the executable under Rosetta emulation on Intel-based Macintosh computers regardless by default. To force Mac OS X to use the current platform’s native architecture, include the “LSRequiresNativeExecution” key in your information property list.

LSBackgroundOnly

LSBackgroundOnly (Boolean) specifies whether this application runs only in the background. If this key exists and is set to “1”, Launch Services runs the application in the background only. You can use this key to create faceless background applications. You should also use this key if your application uses higher-level frameworks that connect to the window server, but are not intended to be visible to users. Background applications must be compiled as Mach-O executables. This option is not available for CFM applications.

LSEnvironment

LSEnvironment Dictionary) defines environment variables to be set before launching this application. The names of the environment variables are the keys of the dictionary, with the values being the corresponding environment variable value. Both keys and values must be strings.

These environment variables are set only for applications launched through Launch Services. If you run your executable directly from the command line, these environment variables are not set.

LSFileQuarantineEnabled

LSFileQuarantineEnabled (Boolean) specifies whether files this application creates are quarantined by default.

See

This key is available in Mac OS X v10.5 and later.

LSGetAppDiedEvents

LSGetAppDiedEvents (Boolean) indicates whether the operation system notifies this application when when one of its child process terminates. If you set the value of this key to YES, the system sends your application an kAEApplicationDied Apple event for each child process as it terminates.

LSHasLocalizedDisplayName

LSHasLocalizedDisplayName (String) specifies whether the Finder displays the name of this application as a localized string. When set to “1”, the Finder displays the name of your application as a localized string. Include this key only if you include localized versions of the key “CFBundleDisplayName” in your language-specific InfoPList.strings files.

Including this key significantly improves the performance of localized filename display. If your bundle supports localized display names, you should include this key in your information property list file.

LSMinimumSystemVersion

LSMinimumSystemVersion (String) indicates the minimum version of Mac OS X required for this application to run. This string is usually of the form n.n.n where n is a number. The first number is the major version number of the system. The second and third numbers are minor revision numbers. For example, to support Mac OS X v10.1 and later, you would set the value of this key to "10.1.5".

If the minimum system version is not available, Mac OS X tries to display an alert panel notifying the user of that fact, although it may not always be able to do so.

LSMinimumSystemVersionByArchitecture

LSMinimumSystemVersionByArchitecture (Dictionary) specifies the earliest Mac OS X version for a set of architectures. This key contains a dictionary of key-value pairs. Each key corresponds to one of the architectures associated with the “LSExecutableArchitectures” key. The value for each key is the minimum version of Mac OS X required for the application to run under that architecture. This string is usually of the form n.n.n where n is a number. The first number is the major version number of the system. The second and third numbers are minor revision numbers. For example, to support Mac OS X v10.4.9 and later, you would set the value of this key to "10.4.9".

If the current system version is less than the required minimum version, Launch Services does not attempt to use the corresponding architecture. This key applies only to the selection of an execution architecture and can be used in conjunction with the “LSMinimumSystemVersion” key, which specifies the overall minimum system version requirement for the application.

LSMultipleInstancesProhibited

LSMultipleInstancesProhibited (Boolean) indicates whether an application is prohibited from running simultaneously in multiple user sessions. If true, the application runs in only one user session at a time. You can use this key to prevent resource conflicts that might arise by sharing an application across multiple user sessions. For example, you might want to prevent users from accessing a custom USB device when it is already in use by a different user.

Launch Services returns an appropriate error code if the target application cannot be launched. If a user in another session is running the application, Launch Services returns a kLSMultipleSessionsNotSupportedErr error. If you attempt to launch a separate instance of an application in the current session, it returns kLSMultipleInstancesProhibitedErr.

LSRequiresIPhoneOS

LSRequiresIPhoneOS (Boolean) specifies whether the application can run only on iPhone OS. If this key is set to YES, Launch Services allows the application to launch only when the host platform is iPhone OS.

LSRequiresNativeExecution

LSRequiresNativeExecution (Boolean) specifies whether to launch the application using the subbinary for the current architecture. If this key is set to YES, Launch Services always runs the application using the binary compiled for the current architecture. You can use this key to prevent a universal binary from being run under Rosetta emulation on an Intel-based Macintosh computer. For more information about configuring the execution architectures, see “LSExecutableArchitectures.”

LSUIElement

LSUIElement (String). If this key is set to “1”, Launch Services runs the application as an agent application. Agent applications do not appear in the Dock or in the Force Quit window. Although they typically run as background applications, they can come to the foreground to present a user interface if desired. A click on a window belonging to an agent application brings that application forward to handle events.

The Dock and loginwindow are two applications that run as agent applications.

LSUIPresentationMode

LSUIPresentationMode (Number) identifies the initial user-interface mode for the application. You would use this in applications that may need to take over portions of the screen that contain UI elements such as the Dock and menu bar. Most modes affect only UI elements that appear in the content area of the screen, that is, the area of the screen that does not include the menu bar. However, you can request that all UI elements be hidden as well.

This key is applicable to both Carbon and Cocoa applications and can be one of the following values:

LSVisibleInClassic

LSVisibleInClassic (String). If this key is set to “1”, any agent applications or background-only applications with this key appears as background-only processes to the Classic environment. Agent applications and background-only applications without this key do not appear as running processes to Classic at all. Unless your process needs to communicate explicitly with a Classic application, you do not need to include this key.

NSAppleScriptEnabled

NSAppleScriptEnabled (Boolean or String). This key identifies whether the application is scriptable. Set the value of this key to true (when typed as Boolean) or “YES” (when typed as String) if your application supports AppleScript.

NSHumanReadableCopyright

NSHumanReadableCopyright (String). This key contains a string with the copyright notice for the bundle; for example, © 2008, My Company. You can load this string and display it in an About dialog box. This key can be localized by including it in your InfoPlist.strings files. This key replaces the obsolete CFBundleGetInfoString key.

NSJavaNeeded

NSJavaNeeded (Boolean or String). This key specifies whether the Java VM must be loaded and started up prior to executing the bundle code. This key is required only for Cocoa Java applications to tell the system to launch the Java environment. If you are writing a pure Java application, do not include this key.

You can also specify a string type with the value “YES” instead of a Boolean value if desired.

Deprecated in Mac OS X v10.5.

NSJavaPath

NSJavaPath (Array). This key contains an array of paths. Each path points to a Java class. The path can be either an absolute path or a relative path from the location specified by the key “NSJavaRoot.” The development environment (or, specifically, its jamfiles) automatically maintains the values in the array.

Deprecated in Mac OS X v10.5.

NSJavaRoot

NSJavaRoot (String). This key contains a string identifying a directory. This directory represents the root directory of the application’s Java class files.

NSMainNibFile

NSMainNibFile (String). This key contains a string with the name of the application’s main nib file (minus the .nib extension). A nib file is an Interface Builder archive containing the description of a user interface along with any connections between the objects of that interface. The main nib file is automatically loaded when an application is launched.

NSPersistentStoreTypeKey

NSPersistentStoreTypeKey (String). This key contains a string that specifies the type of Core Data persistent store associated with a document type (see “CFBundleDocumentTypes”). See NSPersistentStoreCoordinator_Store_Types for possible values.

NSPrefPaneIconFile

NSPrefPaneIconFile (String). This key contains a string with the name of an image file (including extension) containing the preference pane’s icon. This key should only be used by preference pane bundles. The image file should contain an icon 32 by 32 pixels in size. If this key is omitted, the System Preferences application looks for the image file using the CFBundleIconFile key instead.

NSPrefPaneIconLabel

NSPrefPaneIconLabel (String). This key contains a string with the name of a preference pane. This string is displayed below the preference pane’s icon in the System Preferences application. You can split long names onto two lines by including a newline character (‘\n’) in the string. If this key is omitted, the System Preferences application gets the name from the CFBundleName key.

This key can be localized and included in the InfoPlist.strings files of a bundle.

NSPrincipalClass

NSPrincipalClass (String). This key contains a string with the name of a bundle’s principal class. This key is used to identify the entry point for dynamically loaded code, such as plug-ins and other dynamically-loaded bundles. The principal class of a bundle typically controls all other classes in the bundle and mediates between those classes and any classes outside the bundle. The class identified by this value can be retrieved using the principalClass method of NSBundle. For Cocoa applications, the value for this key is NSApplication by default.

NSServices

NSServices (Array). This key contains an array of dictionaries specifying the services provided by the application. Table 6 lists the keys for specifying a service:

UIInterfaceOrientation

UIInterfaceOrientation (String) specifies the initial orientation of the application’s user interface.

This value is based on the Interface Orientation Constants constants declared in the UIApplication.h header file. The default style is UIInterfaceOrientationPortrait.

UIPrerenderedIcon

UIPrerenderedIcon (Boolean) specifies whether the iPhone OS applies sheen and bevel effects to the application icon.

UIRequiresPersistentWiFi

UIRequiresPersistentWiFi (Boolean) specifies whether the application requires a Wi-Fi connection. iPhone OS maintains the active Wi-Fi connection open while the application is running.

UIStatusBarHidden

UIStatusBarHidden (Boolean) specifies whether the status bar is initially hidden when the application launches.

UIStatusBarStyle

UIStatusBarStyle (String) specifies the style of the status bar as the application launches.

This value is based on the Status Bar Style Constants constants declared in UIApplication.h header file. The default style is UIStatusBarStyleGray.

UTExportedTypeDeclarations

UTExportedTypeDeclarations (DictionaryArray) declares the uniform type identifiers (UTIs) owned and exported by the application. You use this key to declare your application’s custom data formats and associate them with UTIs. Exporting a list of UTIs is the preferred way to register your custom file types; however, Launch Services recognizes this key and its contents only in Mac OS X v10.5 and later. This key is ignored on versions of Mac OS X prior to version 10.5.

The value for the UTExportedTypeDeclarations key is an array of dictionaries. Each dictionary contains a set of key-value pairs identifying the attributes of the type declaration. Table 7 lists the keys you can include in this dictionary along with the typical values they contain. These keys can also be included in array of dictionaries associated with the “UTImportedTypeDeclarations” key.

For more information about UTIs and their use, see Uniform Type Identifiers Overview.

UTImportedTypeDeclarations

UTImportedTypeDeclarations (Array) declares the uniform type identifiers (UTIs) inherently supported (but not owned) by the application. You use this key to declare any supported types that your application recognizes and wants to ensure are recognized by Launch Services, regardless of whether the application that owns them is present. For example, you could use this key to specify a file format that is defined by another company but which your program can read and export.

The value for the UTExportedTypeDeclarations key is an array of dictionaries and uses the same keys as those for the “UTExportedTypeDeclarations” key. For a list of these keys, see Table 7.

For more information about UTIs and their use, see Uniform Type Identifiers Overview.

---