NSProcessInfo Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Interacting with the Operating System
Declared in
NSProcessInfo.h
Related sample code

Overview

The NSProcessInfo class provides methods to access information about the current process. Each process has a single, shared NSProcessInfo object, known as process information agent.

The process information agent can return such information as the arguments, environment variables, host name, or process name. The processInfo class method returns the shared agent for the current process—that is, the process whose object sent the message. For example, the following line returns the NSProcessInfo object, which then provides the name of the current process:

NSString *processName = [[NSProcessInfo processInfo] processName];

The NSProcessInfo class also includes the operatingSystem method, which returns an enum constant identifying the operating system on which the process is executing.

NSProcessInfo objects attempt to interpret environment variables and command-line arguments in the user's default C string encoding if they cannot be converted to Unicode as UTF-8 strings. If neither conversion works, these values are ignored by the NSProcessInfo object.

Managing Activities

The system has heuristics to improve battery life, performance, and responsiveness of applications for the benefit of the user. You can use the following methods to manage activities that give hints to the system that your application has special requirements:

In response to creating an activity, the system will disable some or all of the heuristics so your application can finish quickly while still providing responsive behavior if the user needs it.

You use activities when your application is performing a long-running operation. If the activity can take different amounts of time (for example, calculating the next move in a chess game), it should use this API. This will ensure correct behavior when the amount of data or the capabilities of the user's computer varies. You should put your activity into one of two major categories:

  1. User initiated: These are finite length activities that the user has explicitly started. Examples include exporting or downloading a user specified file.

  2. Background: These are finite length activities that are part of the normal operation of your application but are not explicitly started by the user. Examples include autosaving, indexing, and automatic downloading of files.

In addition, if your application requires high priority I/O, you can include the NSActivityLatencyCritical flag (using a bitwise OR). You should only use this flag for activities like audio or video recording that really do require high priority.

If your activity takes place synchronously inside an event callback on the main thread, you do not need to use this API.

Be aware that failing to end these activities for an extended period of time can have significant negative impacts to the performance of your user's computer, so be sure to use only the minimum amount of time required. User preferences may override your application’s request.

You can also use this API to control automatic termination or sudden termination (see “Sudden Termination”). For example:

id activity = [[NSProcessInfo processInfo] beginActivityWithOptions:NSActivityAutomaticTerminationDisabled reason:@"Good Reason"];
// Perform some work.
[[NSProcessInfo processInfo] endActivity:activity];

is equivalent to:

[[NSProcessInfo processInfo] disableAutomaticTermination:@"Good Reason"];
// Perform some work.
[[NSProcessInfo processInfo] enableAutomaticTermination:@"Good Reason"];

Because this API returns an object, it may be easier to pair begins and ends than when using the automatic termination API—if the object is deallocated before the endActivity: call, the activity will be automatically ended.

This API also provides a mechanism to disable system-wide idle sleep and display idle sleep. These can have a large impact on the user experience, so be sure not to forget to end activities that disable sleep (including NSActivityUserInitiated).

Sudden Termination

OS X v10.6 and later includes a mechanism that allows the system to log out or shut down more quickly by, whenever possible, killing applications instead of requesting that they quit themselves.

Your application can enable this capability on a global basis and then manually override its availability during actions that could cause data corruption or a poor user experience by allowing sudden termination. Alternately, your application can just manually enable and disable this functionality.

The methods enableSuddenTermination and disableSuddenTermination decrement or increment, respectively, a counter whose value is 1 when the process is first created. When the counter's value is 0 the application is considered to be safely killable and may be killed by the system without any notification or event being sent to the process first.

Your application can support sudden termination upon launch by adding a key to the application’s Info.plist. If the NSSupportsSuddenTermination key exists in the Info.plist and has a value of YES, it is the equivalent of calling enableSuddenTermination during your application launch. This renders the application process killable right away. You can still override this behavior by invoking disableSuddenTermination.

Typically, you disable sudden termination whenever your application defers work that must be done before the application terminates. If, for example, your application defers writing data to disk, and sudden termination is enabled, you should bracket the sensitive operations with a call to disableSuddenTermination, perform the necessary operations, and then send a balancing enableSuddenTermination message.

In agents or daemon executables that don't depend on AppKit you can manually invoke enableSuddenTermination right away. You can then use the enable and disable methods whenever the process has work it must do before it terminates.

Some AppKit functionality automatically disables sudden termination on a temporary basis to ensure data integrity.

  • NSUserDefaults temporarily disables sudden termination to prevent process killing between the time at which a default has been set and the time at which the preferences file including that default has been written to disk.

  • NSDocument temporarily disables sudden termination to prevent process killing between the time at which the user has made a change to a document and the time at which the user's change has been written to disk.

Tasks

Getting the Process Information Agent

Accessing Process Information

Sudden Application Termination

Controlling Automatic Termination

Getting Host Information

Getting Computer Information

Managing Activities

Class Methods

processInfo

Returns the process information agent for the process.

+ (NSProcessInfo *)processInfo
Return Value

Shared process information agent for the process.

Discussion

An NSProcessInfo object is created the first time this method is invoked, and that same object is returned on each subsequent invocation.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSProcessInfo.h

Instance Methods

activeProcessorCount

Provides the number of active processing cores available on the computer.

- (NSUInteger)activeProcessorCount
Return Value

Number of active processing cores.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSProcessInfo.h

arguments

Returns the command-line arguments for the process.

- (NSArray *)arguments
Return Value

Array of strings with the process’s command-line arguments.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSProcessInfo.h

automaticTerminationSupportEnabled

Returns a Boolean value indicating whether the application supports automatic termination.

- (BOOL)automaticTerminationSupportEnabled
Return Value

YES if the application supports automatic termination; otherwise NO.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSProcessInfo.h

beginActivityWithOptions:reason:

Begin an activity using the given options and reason.

- (id<NSObject>)beginActivityWithOptions:(NSActivityOptions)options reason:(NSString *)reason
Parameters
options

Options for the activity. See “Activity Options” for possible values.

reason

A string used in debugging to indicate the reason the activity began.

Return Value

An object token representing the activity.

Discussion

Indicate completion of the activity by calling endActivity: passing the returned object as the argument.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSProcessInfo.h

disableAutomaticTermination:

Disables automatic termination for the application.

- (void)disableAutomaticTermination:(NSString *)reason
Parameters
reason

The reason why automatic termination is being disabled.

Discussion

This method increments the automatic termination counter. When the counter is greater than 0, the application is considered active and ineligible for automatic termination. For example, you could disable automatic termination when the user of an instant messaging application signs on, because the application requires a background connection to be maintained even if the application is otherwise inactive.

The reason parameter is used to track why an application is or is not automatically terminable and can be inspected by debugging tools. For example, you could pass the string @"file transfer in progress" if you disable automatic termination before transferring a file over the network. When you reenable automatic termination after the transfer is complete using enableAutomaticTermination:, you should pass the matching string. A given reason can be used more than once at the same time; for example, if two files were being transferred at the same time, automatic termination could be disabled for each, passing the same reason string.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSProcessInfo.h

disableSuddenTermination

Disables the application for quickly killing using sudden termination.

- (void)disableSuddenTermination
Discussion

This method increments the sudden termination counter. When the termination counter reaches 0 the application allows sudden termination.

By default the sudden termination counter is set to 1. This can be overridden in your application Info.plist. See “Sudden Termination” for more information and debugging suggestions.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSProcessInfo.h

enableAutomaticTermination:

Enables automatic termination for the application.

- (void)enableAutomaticTermination:(NSString *)reason
Parameters
reason

The reason why automatic termination is being enabled.

Discussion

This method decrements the automatic termination counter. When the counter is 0, the application is eligible for automatic termination.

The reason parameter is used to track why an application is or is not automatically terminable and can be inspected by debugging tools. For example, you could pass the string @"file transfer in progress" if you disable automatic termination before transferring a file over the network. When you reenable automatic termination after the transfer is complete using enableAutomaticTermination:, you should pass the matching string. A given reason can be used more than once at the same time; for example, if two files were being transferred at the same time, automatic termination could be disabled for each, passing the same reason string.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSProcessInfo.h

enableSuddenTermination

Enables the application for quick killing using sudden termination.

- (void)enableSuddenTermination
Discussion

This method decrements the sudden termination counter. When the termination counter reaches 0 the application allows sudden termination.

By default the sudden termination counter is set to 1. This can be overridden in your application Info.plist. See “Sudden Termination” for more information and debugging suggestions.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSProcessInfo.h

endActivity:

Ends the given activity.

- (void)endActivity:(id<NSObject>)activity
Parameters
activity

An activity object returned by beginActivityWithOptions:reason:.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSProcessInfo.h

environment

Returns the variable names and their values in the environment from which the process was launched.

- (NSDictionary *)environment
Return Value

Dictionary of environment-variable names (keys) and their values.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSProcessInfo.h

globallyUniqueString

Returns a global unique identifier for the process.

- (NSString *)globallyUniqueString
Return Value

Global ID for the process. The ID includes the host name, process ID, and a time stamp, which ensures that the ID is unique for the network.

Discussion

This method generates a new string each time it is invoked, so it also uses a counter to guarantee that strings created from the same process are unique.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSProcessInfo.h

hostName

Returns the name of the host computer.

- (NSString *)hostName
Return Value

Host name of the computer.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSProcessInfo.h

operatingSystem

Returns a constant to indicate the operating system on which the process is executing.

- (NSUInteger)operatingSystem
Return Value

Operating system identifier. See “Constants” for a list of possible values. In OS X, it’s NSMACHOperatingSystem.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSProcessInfo.h

operatingSystemName

Returns a string containing the name of the operating system on which the process is executing.

- (NSString *)operatingSystemName
Return Value

Operating system name. In OS X, it’s @"NSMACHOperatingSystem"

Availability
  • Available in OS X v10.0 and later.
Declared In
NSProcessInfo.h

operatingSystemVersionString

Returns a string containing the version of the operating system on which the process is executing.

- (NSString *)operatingSystemVersionString
Return Value

Operating system version. This string is human readable, localized, and is appropriate for displaying to the user. This string is not appropriate for parsing.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSProcessInfo.h

performActivityWithOptions:reason:usingBlock:

Synchronously perform an activity defined by a given block using the given options.

- (void)performActivityWithOptions:(NSActivityOptions)options reason:(NSString *)reason usingBlock:(void (^)(void))block
Parameters
options

Options for the activity. See “Activity Options” for possible values.

reason

A string used in debugging to indicate the reason the activity began.

block

A block containing the work to be performed by the activity.

Discussion

The activity will be automatically ended after block returns.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSProcessInfo.h

physicalMemory

Provides the amount of physical memory on the computer.

- (unsigned long long)physicalMemory
Return Value

Amount of physical memory in bytes.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSProcessInfo.h

processIdentifier

Returns the identifier of the process.

- (int)processIdentifier
Return Value

Process ID of the process.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSProcessInfo.h

processName

Returns the name of the process.

- (NSString *)processName
Return Value

Name of the process.

Discussion

The process name is used to register application defaults and is used in error messages. It does not uniquely identify the process.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSProcessInfo.h

processorCount

Provides the number of processing cores available on the computer.

- (NSUInteger)processorCount
Return Value

Number of processing cores.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSProcessInfo.h

setAutomaticTerminationSupportEnabled:

Sets whether the application supports automatic termination.

- (void)setAutomaticTerminationSupportEnabled:(BOOL)flag
Parameters
flag

Pass YES to enable automatic termination support.

Discussion

Without calling this or setting the equivalent Info.plist key (NSSupportsAutomaticTermination), the methods disableAutomaticTermination: and enableAutomaticTermination: have no effect, although the counter tracking automatic termination opt-outs is still kept up to date to ensure correctness if this is called later. Currently, passing NO has no effect. This should be called in the application delegate method applicationDidFinishLaunching: or earlier.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSProcessInfo.h

setProcessName:

Sets the name of the process.

- (void)setProcessName:(NSString *)name
Parameters
name

New name for the process.

Discussion

Availability
  • Available in OS X v10.0 and later.
Declared In
NSProcessInfo.h

systemUptime

Returns how long it has been since the computer has been restarted.

- (NSTimeInterval)systemUptime
Return Value

An NSTimeInterval indicating how long since the computer has been restarted.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSProcessInfo.h

Constants

Activity Options

Option flags used with beginActivityWithOptions:reason: and performActivityWithOptions:reason:usingBlock:.

typedef NS_OPTIONS(uint64_t,
   NSActivityOptions) {
   NSActivityIdleDisplaySleepDisabled = (1ULL << 40),
   NSActivityIdleSystemSleepDisabled = (1ULL << 20),
   NSActivitySuddenTerminationDisabled = (1ULL << 14),
   NSActivityAutomaticTerminationDisabled = (1ULL << 15),
   NSActivityUserInitiated = (0x00FFFFFFULL | NSActivityIdleSystemSleepDisabled),
   NSActivityUserInitiatedAllowingIdleSystemSleep = (NSActivityUserInitiated & ~NSActivityIdleSystemSleepDisabled),
   NSActivityBackground = 0x000000FFULL,
   NSActivityLatencyCritical = 0xFF00000000ULL,
};
Constants
NSActivityIdleDisplaySleepDisabled

Flag to require the screen to stay powered on.

Available in OS X v10.9 and later.

Declared in NSProcessInfo.h.

NSActivityIdleSystemSleepDisabled

Flag to prevent idle sleep.

This is included in NSActivityUserInitiatedAllowingIdleSystemSleep.

Available in OS X v10.9 and later.

Declared in NSProcessInfo.h.

NSActivitySuddenTerminationDisabled

Flag to prevent sudden termination.

This is included in NSActivityUserInitiatedAllowingIdleSystemSleep.

Available in OS X v10.9 and later.

Declared in NSProcessInfo.h.

NSActivityAutomaticTerminationDisabled

Flag to prevent automatic termination.

This is included in NSActivityUserInitiatedAllowingIdleSystemSleep.

Available in OS X v10.9 and later.

Declared in NSProcessInfo.h.

NSActivityUserInitiated

Flag to indicate the app is performing a user-requested action.

Available in OS X v10.9 and later.

Declared in NSProcessInfo.h.

NSActivityUserInitiatedAllowingIdleSystemSleep

Flag to indicate the app is performing a user-requested action, but that the system can sleep on idle.

Available in OS X v10.9 and later.

Declared in NSProcessInfo.h.

NSActivityBackground

Flag to indicate the app has initiated some kind of work, but not as the direct result of user request.

Available in OS X v10.9 and later.

Declared in NSProcessInfo.h.

NSActivityLatencyCritical

Flag to indicate the activity requires the highest amount of timer and I/O precision available.

Important: Very few applications should need to use this constant.

Available in OS X v10.9 and later.

Declared in NSProcessInfo.h.

Discussion

To include one of these individual flags in one of the sets, use bitwise OR; for example, during a presentation you might use:

NSActivityUserInitiated | NSActivityIdleDisplaySleepDisabled

To exclude from one of the sets, use bitwise AND with NOT; for example, during a user initiated action that may be safely terminated with no application interaction in case of logout you might use:

NSActivityUserInitiated & ~NSActivitySuddenTerminationDisabled

NSProcessInfo—Operating Systems

The following constants are provided by the NSProcessInfo class as return values for operatingSystem.

enum {
   NSWindowsNTOperatingSystem = 1,
   NSWindows95OperatingSystem,
   NSSolarisOperatingSystem,
   NSHPUXOperatingSystem,
   NSMACHOperatingSystem,
   NSSunOSOperatingSystem,
   NSOSF1OperatingSystem
};
Constants
NSHPUXOperatingSystem

Indicates the HP UX operating system.

Available in OS X v10.0 and later.

Declared in NSProcessInfo.h.

NSMACHOperatingSystem

Indicates the OS X operating system.

Available in OS X v10.0 and later.

Declared in NSProcessInfo.h.

NSOSF1OperatingSystem

Indicates the OSF/1 operating system.

Available in OS X v10.0 and later.

Declared in NSProcessInfo.h.

NSSolarisOperatingSystem

Indicates the Solaris operating system.

Available in OS X v10.0 and later.

Declared in NSProcessInfo.h.

NSSunOSOperatingSystem

Indicates the Sun OS operating system.

Available in OS X v10.0 and later.

Declared in NSProcessInfo.h.

NSWindows95OperatingSystem

Indicates the Windows 95 operating system.

Available in OS X v10.0 and later.

Declared in NSProcessInfo.h.

NSWindowsNTOperatingSystem

Indicates the Windows NT operating system.

Available in OS X v10.0 and later.

Declared in NSProcessInfo.h.