System Utilities¶
Helper functions for working with the underlying system. These are mostly os dependent, only working on linux, osx, and bsd. In almost all cases they’re best-effort, providing None if the lookup fails.
Module Overview:
is_windows - checks if we're running on windows
is_mac - checks if we're running on a mac
is_bsd - checks if we're running on the bsd family of operating systems
is_available - determines if a command is available on this system
is_running - determines if a given process is running
get_name_by_pid - gets the name for a process by the given pid
get_pid_by_name - gets the pid for a process by the given name
get_pid_by_port - gets the pid for a process listening to a given port
get_pid_by_open_file - gets the pid for the process with an open file
get_cwd - provides the current working directory for a given process
get_user - provides the user a process is running under
get_start_time - provides the unix timestamp when the process started
get_bsd_jail_id - provides the BSD jail id a given process is running within
get_bsd_jail_path - provides the path of the given BSD jail
expand_path - expands relative paths and ~ entries
call - runs the given system command and provides back the results
get_process_name - provides our process' name
set_process_name - changes our process' name
- stem.util.system.argc_t¶
alias of LP_c_char_p
- stem.util.system.is_windows()[source]¶
Checks if we are running on Windows.
Returns: bool to indicate if we’re on Windows
- stem.util.system.is_mac()[source]¶
Checks if we are running on Mac OSX.
Returns: bool to indicate if we’re on a Mac
- stem.util.system.is_bsd()[source]¶
Checks if we are within the BSD family of operating systems. This presently recognizes Macs, FreeBSD, and OpenBSD but may be expanded later.
Returns: bool to indicate if we’re on a BSD OS
- stem.util.system.is_available(command, cached=True)[source]¶
Checks the current PATH to see if a command is available or not. If more than one command is present (for instance “ls -a | grep foo”) then this just checks the first.
Note that shell (like cd and ulimit) aren’t in the PATH so this lookup will try to assume that it’s available. This only happends for recognized shell commands (those in SHELL_COMMANDS).
Parameters: - command (str) – command to search for
- cached (bool) – makes use of available cached results if True
Returns: True if an executable we can use by that name exists in the PATH, False otherwise
- stem.util.system.is_running(command)[source]¶
Checks for if a process with a given name is running or not.
Parameters: command (str) – process name to be checked Returns: True if the process is running, False if it’s not among ps results, and None if ps can’t be queried
- stem.util.system.get_name_by_pid(pid)[source]¶
Attempts to determine the name a given process is running under (not including arguments). This uses...
1. Information from /proc 2. ps -p <pid> -o command
Parameters: pid (int) – process id of the process to be queried Returns: str with the process name, None if it can’t be determined
- stem.util.system.get_pid_by_name(process_name, multiple=False)[source]¶
Attempts to determine the process id for a running process, using...
1. pgrep -x <name> 2. pidof <name> 3. ps -o pid -C <name> (linux) ps axc | egrep " <name>$" (bsd) 4. lsof -tc <name>
Parameters: - process_name (str) – process name for which to fetch the pid
- multiple (bool) – provides a list of all pids if True, otherwise results with multiple processes are discarded
Returns: Response depends upon the ‘multiple’ argument as follows...
- if False then this provides an int with the process id or None if it can’t be determined
- if True then this provides a list of all int process ids, and an empty list if it can’t be determined
- stem.util.system.get_pid_by_port(port)[source]¶
Attempts to determine the process id for a process with the given port, using...
1. netstat -npltu | grep 127.0.0.1:<port> 2. sockstat -4l -P tcp -p <port> 3. lsof -wnP -iTCP -sTCP:LISTEN | grep ":<port>"
Most queries limit results to listening TCP connections. This function likely won’t work on Mac OSX.
Parameters: port (int) – port where the process we’re looking for is listening Returns: int with the process id, None if it can’t be determined
- stem.util.system.get_pid_by_open_file(path)[source]¶
Attempts to determine the process id for a process with the given open file, using...
lsof -w <path>
Parameters: path (str) – location of the socket file to query against Returns: int with the process id, None if it can’t be determined
- stem.util.system.get_cwd(pid)[source]¶
Provides the working directory of the given process.
Parameters: pid (int) – process id of the process to be queried Returns: str with the absolute path for the process’ present working directory, None if it can’t be determined
- stem.util.system.get_user(pid)[source]¶
Provides the user a process is running under.
Parameters: pid (int) – process id of the process to be queried Returns: str with the username a process is running under, None if it can’t be determined
- stem.util.system.get_start_time(pid)[source]¶
Provides the unix timestamp when the given process started.
Parameters: pid (int) – process id of the process to be queried Returns: float for the unix timestamp when the process began, None if it can’t be determined
- stem.util.system.get_bsd_jail_id(pid)[source]¶
Gets the jail id for a process. These seem to only exist for FreeBSD (this style for jails does not exist on Linux, OSX, or OpenBSD).
Parameters: pid (int) – process id of the jail id to be queried Returns: int for the jail id, zero if this can’t be determined
- stem.util.system.get_bsd_jail_path(jid)[source]¶
Provides the path of the given FreeBSD jail.
Parameters: jid (int) – jail id to be queried Returns: str of the path prefix, None if this can’t be determined
- stem.util.system.expand_path(path, cwd=None)[source]¶
Provides an absolute path, expanding tildes with the user’s home and appending a current working directory if the path was relative.
Parameters: - path (str) – path to be expanded
- cwd (str) – current working directory to expand relative paths with, our process’ if this is None
Returns: str of the path expanded to be an absolute path, never with an ending slash
- stem.util.system.call(command, default='<Undefined_ >', ignore_exit_status=False)[source]¶
Issues a command in a subprocess, blocking until completion and returning the results. This is not actually ran in a shell so pipes and other shell syntax are not permitted.
Parameters: - command (str) – command to be issued
- default (object) – response if the query fails
- ignore_exit_status (bool) – reports failure if our command’s exit status was non-zero
Returns: list with the lines of output from the command
Raises : OSError if this fails and no default was provided