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 |
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.
Sudden Termination
OS X v10.6 includes a new 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.
NSUserDefaultstemporarily 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.NSDocumenttemporarily 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
-
– arguments -
– environment -
– processIdentifier -
– globallyUniqueString -
– processName -
– setProcessName:
Sudden Application Termination
Controlling Automatic Termination
-
– disableAutomaticTermination: -
– enableAutomaticTermination: -
– setAutomaticTerminationSupportEnabled: -
– automaticTerminationSupportEnabled
Getting Host Information
Getting Computer Information
Class Methods
processInfo
Returns the process information agent for the process.
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.hInstance Methods
activeProcessorCount
Provides the number of active processing cores available on the computer.
Return Value
Number of active processing cores.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSProcessInfo.harguments
Returns the command-line arguments for the process.
Return Value
Array of strings with the process’s command-line arguments.
Availability
- Available in OS X v10.0 and later.
Declared In
NSProcessInfo.hautomaticTerminationSupportEnabled
Returns a Boolean value indicating whether the application supports automatic termination.
Return Value
YES if the application supports automatic termination; otherwise NO.
Availability
- Available in OS X v10.7 and later.
See Also
Declared In
NSProcessInfo.hdisableAutomaticTermination:
Disables automatic termination for the application.
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 transfering 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.
See Also
Declared In
NSProcessInfo.hdisableSuddenTermination
Disables the application for quickly killing using sudden termination.
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.
See Also
Declared In
NSProcessInfo.henableAutomaticTermination:
Enables automatic termination for the application.
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 transfering 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.
See Also
Declared In
NSProcessInfo.henableSuddenTermination
Enables the application for quick killing using sudden termination.
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.
See Also
Declared In
NSProcessInfo.henvironment
Returns the variable names and their values in the environment from which the process was launched.
Return Value
Dictionary of environment-variable names (keys) and their values.
Availability
- Available in OS X v10.0 and later.
Declared In
NSProcessInfo.hgloballyUniqueString
Returns a global unique identifier for the process.
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.
See Also
Declared In
NSProcessInfo.hhostName
Returns the name of the host computer.
Return Value
Host name of the computer.
Availability
- Available in OS X v10.0 and later.
Declared In
NSProcessInfo.hoperatingSystem
Returns a constant to indicate the operating system on which the process is executing.
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.hoperatingSystemName
Returns a string containing the name of the operating system on which the process is executing.
Return Value
Operating system name. In OS X, it’s @"NSMACHOperatingSystem"
Availability
- Available in OS X v10.0 and later.
Declared In
NSProcessInfo.hoperatingSystemVersionString
Returns a string containing the version of the operating system on which the process is executing.
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.hphysicalMemory
Provides the amount of physical memory on the computer.
Return Value
Amount of physical memory in bytes.
Availability
- Available in OS X v10.5 and later.
Declared In
NSProcessInfo.hprocessIdentifier
Returns the identifier of the process.
Return Value
Process ID of the process.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSProcessInfo.hprocessName
Returns the name of the process.
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.
See Also
Declared In
NSProcessInfo.hprocessorCount
Provides the number of processing cores available on the computer.
Return Value
Number of processing cores.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSProcessInfo.hsetAutomaticTerminationSupportEnabled:
Sets whether the application supports automatic termination.
Parameters
- flag
Pass
YESto 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.
See Also
Declared In
NSProcessInfo.hsetProcessName:
Sets the name of the process.
Parameters
- name
New name for the process.
Discussion
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSProcessInfo.hsystemUptime
Returns how long it has been since the computer has been restarted.
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.hConstants
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
NSHPUXOperatingSystemIndicates the HP UX operating system.
Available in OS X v10.0 and later.
Declared in
NSProcessInfo.h.NSMACHOperatingSystemIndicates the OS X operating system.
Available in OS X v10.0 and later.
Declared in
NSProcessInfo.h.NSOSF1OperatingSystemIndicates the OSF/1 operating system.
Available in OS X v10.0 and later.
Declared in
NSProcessInfo.h.NSSolarisOperatingSystemIndicates the Solaris operating system.
Available in OS X v10.0 and later.
Declared in
NSProcessInfo.h.NSSunOSOperatingSystemIndicates the Sun OS operating system.
Available in OS X v10.0 and later.
Declared in
NSProcessInfo.h.NSWindows95OperatingSystemIndicates the Windows 95 operating system.
Available in OS X v10.0 and later.
Declared in
NSProcessInfo.h.NSWindowsNTOperatingSystemIndicates the Windows NT operating system.
Available in OS X v10.0 and later.
Declared in
NSProcessInfo.h.
© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-05-14)