When To Use What API

The following general guiding principles apply to the CFPreferences API:

• You should typically use CFPreferencesCopyAppValue to read preference keys.

• You should use CFPreferencesSetAppValue to write preference keys for “current user/any host.”

• If you need to write a by-host preference for the current user, use CFPreferencesSetValue. Make sure this is absolutely necessary.

Note that, although they are treated separately in the documentation, high-level API and low-level API are not exclusive. It may be appropriate to use high-level API in some parts of an application, and low-level API in another. For example, you can set a preference key/value pair with CFPreferencesSetValue(key, value, app, user, host) and then read it with CFPreferencesCopyAppValue(key, value, app)— indeed you probably do want to read it with the latter function since it traverses the search path.

Synchronizing Preferences Across Process Boundaries

The Rule of Thumb on CFPreferences synchronization:

1. Only synchronize when absolutely necessary

2. If you have to communicate across process boundaries, use notifications with appropriate granularity, keeping 1) in mind. Typically, this means setting a flag in client processes, and only if a changed key is required should you trigger a synchronize.

Many processes in OS X write a preference key-value pair for use in another process. While it would be convenient for preference key-value pairs to auto-update in other processes, guaranteeing auto-update in all circumstances would incur a performance penalty and also make it difficult to ensure related preferences are read and written consistently. Processes should always have the choice of when to elect to accept new information into their space. For preference values, CFPreferencesSynchronize and CFPreferencesAppSynchronize are the function calls that providing the information choke-point. You should typically not, however, call these functions before every read of a preference key.

Preference File Locations and Debugging

Preferences files are stored in the system’s or user’s preferences directories. On OS X versions 10.0 to 10.4 these are in /Library/Preferences and in /Library/Preferences in the user’s home directory respectively. When debugging an application, it may sometimes be useful to inspect these files to determine that preferences have been saved correctly, however you should never hardcode these paths into an application. If you do need to access the directory programmatically you should use the NSSearchPathForDirectoriesInDomains API, although there should typically be no reason to do so.

Note that preferences you set up in the registration domain (see Defaults Domains in Preferences and Settings Programming Guide) are not stored in the preferences file. Put another way, the preferences file stores only values that are different from those in the registration domain, so you should not expect to see “default defaults” in the preferences file after you run your application.

Managed Preferences

OS X v10.2 introduced the concept of “managed preferences.” The function CFPreferencesAppValueIsForced determines whether or not a given key has been imposed on the user. For managed keys, you should disable any user interface that allows the user to modify the value for the key.