Package oshi.software.os

Interface OSProcess

All Known Implementing Classes:
AbstractOSProcess, AixOSProcess, FreeBsdOSProcess, LinuxOSProcess, MacOSProcess, OpenBsdOSProcess, SolarisOSProcess, WindowsOSProcess
@ThreadSafe public interface OSProcess
Represents a Process on the operating system, which may contain multiple threads.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    OSProcess.State
    Process and Thread Execution States

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    getAffinityMask()
    Gets the process affinity mask for this process.
    List<String>
    getArguments()
    Makes a best effort attempt to get a list of the the command-line arguments of the process.
    int
    getBitness()
    Attempts to get the bitness (32 or 64) of the process.
    long
    getBytesRead()
    Gets the bytes read by the process.
    long
    getBytesWritten()
    Gets the bytes written by the process.
    String
    getCommandLine()
    Gets the process command line used to start the process, including arguments if available to be determined.
    default long
    getContextSwitches()
    A snapshot of the context switches the process has done.
    String
    getCurrentWorkingDirectory()
    Makes a best effort attempt to obtain the current working directory for the process.
    Map<String,String>
    getEnvironmentVariables()
    Makes a best effort attempt to obtain the environment variables of the process.
    String
    getGroup()
    Gets the group under which the process is executing.
    String
    getGroupID()
    Gets the group id under which the process is executing.
    long
    getHardOpenFileLimit()
    Gets the hard limit for open file handles (or network connections) that belong to the given process.
    long
    getKernelTime()
    Gets kernel/system (privileged) time used by the process.
    default long
    getMajorFaults()
    Gets the number of major (hard) faults the process has made which have required loading a memory page from disk.
    default long
    getMinorFaults()
    Gets the number of minor (soft) faults the process has made which have not required loading a memory page from disk.
    String
    getName()
    Gets the name of the process, often the executable program.
    long
    getOpenFiles()
    Gets the number of open file handles (or network connections) that belongs to the process.
    int
    getParentProcessID()
    Gets the process ID of this process's parent.
    String
    getPath()
    Gets the full filesystem path of the executing process.
    int
    getPriority()
    Gets the priority of this process.
    double
    getProcessCpuLoadBetweenTicks(OSProcess proc)
    Gets CPU usage of this process since a previous snapshot of the same process, provided as a parameter.
    double
    getProcessCpuLoadCumulative()
    Gets cumulative CPU usage of this process.
    int
    getProcessID()
    Gets the process ID.
    long
    getResidentSetSize()
    Gets the Resident Set Size (RSS).
    long
    getSoftOpenFileLimit()
    Gets the soft limit for open file handles (or network connections) of the given process.
    long
    getStartTime()
    Gets the process start time.
    OSProcess.State
    getState()
    Gets the process state.
    int
    getThreadCount()
    Gets the number of threads being executed by this process.
    List<OSThread>
    getThreadDetails()
    Retrieves the threads of the process and their details.
    long
    getUpTime()
    Gets up time / elapsed time since the process started.
    String
    getUser()
    Gets the user name of the process owner.
    String
    getUserID()
    Gets the user id of the process owner.
    long
    getUserTime()
    Gets user time used by the process.
    long
    getVirtualSize()
    Gets the Virtual Memory Size (VSZ).
    boolean
    updateAttributes()
    Attempts to update process attributes.

  • Method Details

    • getName

      String getName()
      Gets the name of the process, often the executable program.
      Returns:
      the name of the process.

    • getPath

      String getPath()
      Gets the full filesystem path of the executing process.
      Returns:
      the full path of the executing process.

    • getCommandLine

      String getCommandLine()
      Gets the process command line used to start the process, including arguments if available to be determined. This method generally returns the same information as getArguments() in a more user-readable format, and is more robust to non-elevated access.

      The format of this string is platform-dependent, may be truncated, and may require the end user to parse the result. Users should generally prefer getArguments() which already parses the results, and use this method as a backup.

      On AIX and Solaris, the string may be truncated to 80 characters if there was insufficient permission to read the process memory.

      On Windows, attempts to retrieve the value from process memory, which requires that the process be owned by the same user as the executing process, or elevated permissions, and additionally requires the target process to have the same bitness (e.g., this will fail on a 32-bit process if queried by 64-bit and vice versa). If reading process memory fails, by default, performs a single WMI query for this process, with some latency. If this method will be frequently called for multiple processes, see the configuration file to enable a batch query mode leveraging Win32ProcessCached.getCommandLine(int, long) to improve performance, or setting that parameter via GlobalConfig.set(String, Object) before instantiating any OSProcess object.

      Returns:
      the process command line.

    • getArguments

      List<String> getArguments()
      Makes a best effort attempt to get a list of the the command-line arguments of the process. Returns the same information as getCommandLine() but parsed to a list. May require elevated permissions or same-user ownership.
      Returns:
      A list of Strings representing the arguments. May return an empty list if there was a failure (for example, because the process is already dead or permission was denied).

    • getEnvironmentVariables

      Map<String,String> getEnvironmentVariables()
      Makes a best effort attempt to obtain the environment variables of the process. May require elevated permissions or same-user ownership.
      Returns:
      A map representing the environment variables and their values. May return an empty map if there was a failure (for example, because the process is already dead or permission was denied).

    • getCurrentWorkingDirectory

      String getCurrentWorkingDirectory()
      Makes a best effort attempt to obtain the current working directory for the process.
      Returns:
      the process current working directory.

    • getUser

      String getUser()
      Gets the user name of the process owner.
      Returns:
      the user name. On Windows systems, also returns the domain prepended to the username.

    • getUserID

      String getUserID()
      Gets the user id of the process owner.
      Returns:
      the userID. On Windows systems, returns the Security ID (SID)

    • getGroup

      String getGroup()
      Gets the group under which the process is executing.

      On Windows systems, populating this value for processes other than the current user requires administrative privileges (and still may fail for some system processes) and can incur significant latency. When successful, returns a the default primary group with access to this process, corresponding to the SID in getGroupID().

      Returns:
      the group.

    • getGroupID

      String getGroupID()
      Gets the group id under which the process is executing.

      On Windows systems, populating this value for processes other than the current user requires administrative privileges (and still may fail for some system processes) and can incur significant latency. When successful, returns the default primary group SID with access to this process, corresponding to the name in getGroup().

      Returns:
      the groupID.

    • getState

      OSProcess.State getState()
      Gets the process state.
      Returns:
      the execution state of the process.

    • getProcessID

      int getProcessID()
      Gets the process ID.

      While this is a 32-bit value, it is unsigned on Windows and in extremely rare circumstances may return a negative value.

      Returns:
      the processID.

    • getParentProcessID

      int getParentProcessID()
      Gets the process ID of this process's parent.
      Returns:
      the parentProcessID, if any; 0 otherwise.

    • getThreadCount

      int getThreadCount()
      Gets the number of threads being executed by this process. More information is available using getThreadDetails().
      Returns:
      the number of threads in this process.

    • getPriority

      int getPriority()
      Gets the priority of this process.

      For Linux and Unix, priority is a value in the range -20 to 19 (20 on some systems). The default priority is 0; lower priorities cause more favorable scheduling.

      For Windows, priority values can range from 0 (lowest priority) to 31 (highest priority).

      macOS has 128 priority levels, ranging from 0 (lowest priority) to 127 (highest priority). They are divided into several major bands: 0 through 51 are the normal levels; the default priority is 31. 52 through 79 are the highest priority regular threads; 80 through 95 are for kernel mode threads; and 96 through 127 correspond to real-time threads, which are treated differently than other threads by the scheduler.

      Returns:
      the priority of this process.

    • getVirtualSize

      long getVirtualSize()
      Gets the Virtual Memory Size (VSZ). Includes all memory that the process can access, including memory that is swapped out and memory that is from shared libraries.
      Returns:
      the Virtual Memory Size

    • getResidentSetSize

      long getResidentSetSize()
      Gets the Resident Set Size (RSS). Used to show how much memory is allocated to that process and is in RAM. It does not include memory that is swapped out. It does include memory from shared libraries as long as the pages from those libraries are actually in memory. It does include all stack and heap memory.

      On Windows, returns the Private Working Set size, which should match the "Memory" column in the Windows Task Manager.

      On Linux, returns the RSS value from /proc/[pid]/stat, which may be inaccurate because of a kernel-internal scalability optimization. If accurate values are required, read /proc/[pid]/smaps using FileUtil.getKeyValueMapFromFile(String, String).

      Returns:
      the Resident Set Size

    • getKernelTime

      long getKernelTime()
      Gets kernel/system (privileged) time used by the process.
      Returns:
      the number of milliseconds the process has executed in kernel/system mode.

    • getUserTime

      long getUserTime()
      Gets user time used by the process.
      Returns:
      the number of milliseconds the process has executed in user mode.

    • getUpTime

      long getUpTime()
      Gets up time / elapsed time since the process started.
      Returns:
      the number of milliseconds since the process started.

    • getStartTime

      long getStartTime()
      Gets the process start time.
      Returns:
      the start time of the process in number of milliseconds since January 1, 1970 UTC.

    • getBytesRead

      long getBytesRead()
      Gets the bytes read by the process.

      On Solaris, includes both bytes read and written.

      Returns:
      the number of bytes the process has read from disk.

    • getBytesWritten

      long getBytesWritten()
      Gets the bytes written by the process.

      On Solaris, all IO bytes are included read bytes so this value is 0.

      Returns:
      the number of bytes the process has written to disk.

    • getOpenFiles

      long getOpenFiles()
      Gets the number of open file handles (or network connections) that belongs to the process.

      On FreeBSD and Solaris, this value is only populated if information for a single process id is requested.

      Returns:
      open files or -1 if unknown or not supported

    • getSoftOpenFileLimit

      long getSoftOpenFileLimit()
      Gets the soft limit for open file handles (or network connections) of the given process.

      Retrieving the soft limit for processes other than the calling process is only supported on Linux, FreeBsd and Solaris.

      Returns:
      the soft open file limit for the process if available. Returns -1 if the calling process is not the same as this OSProcess instance and the underlying operating system does not support retrieving the soft limit for other processes.

    • getHardOpenFileLimit

      long getHardOpenFileLimit()
      Gets the hard limit for open file handles (or network connections) that belong to the given process.

      Retrieving the hard limit for processes other than the calling process is only supported on Linux, FreeBsd and Solaris.

      Returns:
      the hard open file limit for the process if available. Returns -1 if the calling process is not the same as this OSProcess instance and the underlying operating system does not support retrieving the hard limit for other processes.

    • getProcessCpuLoadCumulative

      double getProcessCpuLoadCumulative()
      Gets cumulative CPU usage of this process.

      This calculation sums CPU ticks across all processors and may exceed 100% for multi-threaded processes. This is consistent with the cumulative CPU presented by the "top" command on Linux/Unix machines.

      Returns:
      The proportion of up time that the process was executing in kernel or user mode.

    • getProcessCpuLoadBetweenTicks

      double getProcessCpuLoadBetweenTicks(OSProcess proc)
      Gets CPU usage of this process since a previous snapshot of the same process, provided as a parameter.

      This calculation sums CPU ticks across all processors and may exceed 100% for multi-threaded processes. This is consistent with process usage calulations on Linux/Unix machines, but should be divided by the number of logical processors to match the value displayed by the Windows Task Manager.

      The accuracy of this calculation is dependent on both the number of threads on which the process is executing, and the precision of the Operating System's tick counters. A polling interval of at least a few seconds is recommended.

      Parameters:
      proc - An OSProcess object containing statistics for this same process collected at a prior point in time. May be null.
      Returns:
      If the prior snapshot is for the same process at a prior point in time, the proportion of elapsed up time between the current process snapshot and the previous one that the process was executing in kernel or user mode. Returns cumulative load otherwise.

    • getBitness

      int getBitness()
      Attempts to get the bitness (32 or 64) of the process.
      Returns:
      The bitness, if able to be determined, 0 otherwise.

    • getAffinityMask

      long getAffinityMask()
      Gets the process affinity mask for this process.

      On Windows systems with more than 64 processors, if the threads of the calling process are in a single processor group, returns the process affinity mask for that group (which may be zero if the specified process is running in a different group). If the calling process contains threads in multiple groups, returns zero.

      Because macOS does not export interfaces that identify processors or control thread placement, explicit thread to processor binding is not supported and this method will return a bitmask of all logical processors.

      If the Operating System fails to retrieve an affinity mask (e.g., the process has terminated), returns zero.

      Returns:
      a bit vector in which each bit represents the processors that a process is allowed to run on.

    • updateAttributes

      boolean updateAttributes()
      Attempts to update process attributes. Returns false if the update fails, which will occur if the process no longer exists.
      Returns:
      true if the update was successful, false if the update failed. In addition, on a failed update the process state will be changed to OSProcess.State.INVALID.

    • getThreadDetails

      List<OSThread> getThreadDetails()
      Retrieves the threads of the process and their details.

      The amount of returned information is operating-system dependent and may incur some latency.

      Returns:
      a list of threads

    • getMinorFaults

      default long getMinorFaults()
      Gets the number of minor (soft) faults the process has made which have not required loading a memory page from disk. Sometimes called reclaims.

      On Windows, this includes the total of major and minor faults.

      Not available on AIX.

      Returns:
      minor page faults (reclaims).

    • getMajorFaults

      default long getMajorFaults()
      Gets the number of major (hard) faults the process has made which have required loading a memory page from disk.

      Windows does not distinguish major and minor faults at the process level, so this value returns 0 and major faults are included in getMinorFaults().

      Not available on AIX.

      Returns:
      major page faults.

    • getContextSwitches

      default long getContextSwitches()
      A snapshot of the context switches the process has done. Since the context switches could be voluntary and non-voluntary, this gives the sum of both.

      Not available on Windows. An approximation may be made by summing associated values from OSThread.getContextSwitches().

      Not available on AIX.

      Returns:
      sum of both voluntary and involuntary context switches if available, 0 otherwise.