`_, which was written by Jay Loden,
Dave Daeschler, Giampaolo Rodola' and is under the BSD license.
**These functions are not being vended to stem users. They may change in the
future, use them at your own risk.**
.. versionchanged:: 1.3.0
Dropped the get_* prefix from several function names. The old names still
work, but are deprecated aliases.
**Module Overview:**
::
is_available - checks if proc utilities can be used on this system
system_start_time - unix timestamp for when the system started
physical_memory - memory available on this system
cwd - provides the current working directory for a process
uid - provides the user id a process is running under
memory_usage - provides the memory usage of a process
stats - queries statistics about a process
file_descriptors_used - number of file descriptors used by a process
connections - provides the connections made by a process
.. data:: Stat (enum)
Types of data available via the :func:`~stem.util.proc.stats` function.
============== ===========
Stat Description
============== ===========
**COMMAND** command name under which the process is running
**CPU_UTIME** total user time spent on the process
**CPU_STIME** total system time spent on the process
**START_TIME** when this process began, in unix time
============== ===========
N)logTF) lru_cache
SC_CLK_TCKlittle)COMMANDcommand) CPU_UTIMEutime) CPU_STIMEstime)
START_TIMEz
start timec [ R " 5 S:w a gSn U H) n[ R R U5 ( a M) g g)z
Checks if proc information is available on this platform.
:returns: **True** if proc contents exist on this platform, **False** otherwise
LinuxF)
/proc/stat
/proc/meminfo
/proc/net/tcp
/proc/net/udpT)platformsystemospathexists)
proc_pathsr s H/home/james-whalen/.local/lib/python3.13/site-packages/stem/util/proc.py is_availabler [ sC __'! SJ
WW^^D
!
! c [ R " 5 Sp[ SSU5 n [ UR 5 R 5 S 5 n[ USU 5 U$ ! [
SU- 5 n[ X5 Ue= f)z
Provides the unix time (seconds since epoch) when the system started.
:returns: **float** for the unix time of when the system started
:raises: **IOError** if it can't be determined
zsystem start timer btime z/proc/stat[btime]z.unable to parse the /proc/stat btime entry: %s)time _get_linefloatstripsplit _log_runtimeIOError _log_failure)
start_time parameter
btime_lineresultexcs r system_start_timer- p s| ))+':i w :*
:##%++-a0
1F /< M
BZO
PC
Is 8A A;c [ R " 5 Sp[ SSU5 n [ UR 5 S 5 S- n[ USU 5 U$ ! [ SU- 5 n[
X5 Ue= f)z
Provides the total physical memory on the system in bytes.
:returns: **int** for the bytes of physical memory this system has
:raises: **IOError** if it can't be determined
zsystem physical memoryr z MemTotal:r z/proc/meminfo[MemTotal]z4unable to parse the /proc/meminfo MemTotal entry: %sr r! intr$ r% r& r' )r( r) mem_total_liner+ r, s r physical_memoryr3 sx ))+'?i _k9E.
%%'*
+d
2F 5zB M
H>Y
ZC
Is -A A0c [ R " 5 Sp!SU - nU S:X a SnO [ R " U5 n[
X#U5 U$ ! [ a [ SU- 5 n[ X%5 Uef = f)z
Provides the current working directory for the given process.
:param int pid: process id of the process to be queried
:returns: **str** with the path of the working directory for the process
:raises: **IOError** if it can't be determined
cwdz /proc/%s/cwdr zunable to read %s)r r readlinkOSErrorr& r' r% )pidr( r)
proc_cwd_linkr5 r, s r r5 r5 sy ))+ui 3&-AX
C KK
&c y4 *
'-7 8c9" is A
&A0c [ R " 5 Sp!SU - n[ USU5 n [ UR 5 S 5 n[ USU- U5 U$ ! [ SU< SU< 35 n[
X&5 Ue= f)z
Provides the user ID the given process is running under.
:param int pid: process id of the process to be queried
:returns: **int** with the user id for the owner of the process
:raises: **IOError** if it can't be determined
uid/proc/%s/statuszUid:r z%s[Uid]unable to parse the z Uid entry: r0 )r9 r( r) status_pathuid_liner+ r, s r r< r< s} ))+ui!C'+
{FI
6(
!!$
%FI 3Z@ M
KR
SC
Is -A "A:c x U S:X a g[ R " 5 Sp!SU - n[ USU5 n [ US R 5 S 5 S- n[ US R 5 S 5 S- n[ US
U- U5 XV4$ ! [ S U< S S
R
U5 < 35 n[ X'5 Ue= f)a
Provides the memory usage in bytes for the given process.
:param int pid: process id of the process to be queried
:returns: **tuple** of two ints with the memory usage of the process, of the
form **(resident_size, virtual_size)**
:raises: **IOError** if it can't be determined
r )r r z memory usager= )VmRSS:VmSize:rB r r/ rC z%s[VmRSS|VmSize]r> z VmRSS and VmSize entries: , )r
_get_linesr1 r$ r% r& joinr' )r9 r( r) r? mem_lines residentSize virtualSizer, s r memory_usagerJ s AX ))+~i!C'+&;YG) y*002156=Li *002156=K . ? dnn $ ss52 /+=>? doo % ""
Yr]+k9 s<*;*==>?1 4 yZ0 w r c [ U 5 n U S: a [ SU - 5 e [ [
R " SU - 5 5 $ ! [ [ 4 a [ SU - 5 ef = f! [ a n[ SU- 5 eSnAff = f)a
Provides the number of file descriptors currently being used by a process.
.. versionadded:: 1.3.0
:param int pid: process id of the process to be queried
:returns: **int** of the number of file descriptors used
:raises: **IOError** if it can't be determined
r "Process pids can't be negative: %s Process pid was non-numeric: %sz /proc/%i/fdz3Unable to check number of file descriptors used: %sN)r1 r&
ValueError TypeErrorrY r listdir Exception)r9 r, s r file_descriptors_usedrn 8 s ;
c(C
Qw 83> ??
O rzz-#-. // i ;
3c9
::;
O
G#M
NNOs" A !A' A$'
B1A??Bc
L [ R " 5 / p2U ( a& SU - n [ U 5 n U S: a [ SU - 5 eOU( a SU- nOSn [
( d [ S5 eU ( a [
U 5 O [ 5 nU( aP [ R R R [ [ R " U5 R 5 5 OSnS GH nUR! S
5 ( a& [" R$ R' U5 ( d M@ US S R) S
5 nUR! S
5 n [+ US 5 n
U
R- 5 U
GH n U R/ 5 SS u
pp n nn nU( a UU; a M/ U( a UU:w a M> US
:X a US:w a ML U
R1 S5 n[3 U
SU 5 n[ U
US- S S5 nUR1 S5 n[3 USU 5 n[ UUS- S S5 nUS:X d US:X a M US:X d US:X a M UR5 [ R R6 R9 UUUUX5 5 GM SSS5 GM [= USU5 U$ ! [ [ 4 a [ SU - 5 ef = f! , ( d f GM = f! [ a n[ SU< SU< 35 eSnAf[: a n[ SU< SU< 35 eSnAff = f! [ a n[? UU5 e SnAff = f)a
Queries connections from the proc contents. This matches netstat, lsof, and
friends but is much faster. If no **pid** or **user** are provided this
provides all present connections.
:param int pid: pid to provide connections for
:param str user: username to look up connections for
:returns: **list** of :class:`~stem.util.connection.Connection` instances
:raises: **IOError** if it can't be determined
zconnections for pid %sr rh ri zconnections for user %szall connectionszCThis requires python's pwd module, which is unavailable on Windows.N)r z/proc/net/tcp6r z/proc/net/udp66
rbtcps 01 :r z0.0.0.0z 0000:0000:0000:0000:0000:0000zunable to read 'z': zunable to parse 'z/proc/net/[tcp|udp]) r r1 r& rj rk IS_PWD_AVAILABLE_inodes_for_socketssetstemutil str_tools _to_bytesrV pwdgetpwnampw_uidendswithr r r rstripopenreadliner$ rW _unpack_addrrX
connection
Connectionrm r% r' )r9 userr( connr) inodes process_uidproc_file_pathprotocolis_ipv6 proc_fileline_l_dstr_dststatusr< inodedivl_addrl_portr_addrr_portr, s r connectionsr S s YY["d(3.I= Hc q:S@AA
)D0I!I3
Y ZZ),
%#%FSW$))%%//CLL4F4M4M0NO]aK` % %bggnn^.L.L $++C0h '',g J
.$
'9
d>Bjjl3B>O ;AeQ1c1e%v- !3U"v**T"C!%+.FsQwx "-F**T"C!%+.FsQwx "-F"f0O&O1! KK ,,77PVX`j k/ (
' aP 1:> Ko
" = 5; <<=, (
'6 I>3GHH
JNCHIIJ
C
sy J
C2L KD J/1K9L
J,/
J? 9K<L ?K
L K
L,K??LL
L#
L L#c & [ 5 n [ R " SU - 5 nU Hw nSU < SU< 3n [ R
" U5 nUR
S5 ( a= UR [ R R R USS 5 5 Mw My U$ ! [ a n[ SU- 5 eSnAff = f! [ aB n[ R R U5 ( d SnAM [ S U< S
U< 35 eSnAff = f) z
Provides inodes in use by a process for its sockets.
:param int pid: process id of the process to be queried
:returns: **set** with inodes for its sockets
:raises: **IOError** if it can't be determined
z /proc/%s/fdz'Unable to read our file descriptors: %sNz/proc/z/fd/zsocket:[ rN z1unable to determine file descriptor destination (): )rx r rl r8 r& r7
startswithaddry rz r{ r| r r )r9 r fd_contentsr, fdfd_pathfd_names r rw rw s 5&C**]S 01K
b"%r*G a G$g J ' '
499&&002 ?@
(
"
-)
C
;cA
BBC a
WW^^G
$
$
RUW^_ `` as5 B$ A'C$
C.B<<C
D$D 8D Dc
U [ ; GaY [ U 5 S:X ar [ ( a [ R " U 5 SSS2 O[ R " U 5 n[
R " [
R U5 [ U ' [ U $ [ ( ad / n[ S5 HA nU SU- SUS- - nU[ S5 Vs/ s H o4SU- SUS- - PM snSSS2 -
nMC SR U5 nOU n[ R R R [
R " [
R [ R " U5 5 5 [ U ' [ U $ s snf )an
Translates an address entry in the /proc/net/* contents to a human readable
form (`reference `_,
for instance:
::
"0500000A" -> "10.0.0.5"
"F804012A4A5190010000000002000000" -> "2a01:4f8:190:514a::2"
:param str addr: proc address entry to be decoded
:returns: **str** of the decoded address
r NrN r r ) ENCODED_ADDRrY IS_LITTLE_ENDIANbase64 b16decodesocket inet_ntopAF_INETrangerF ry rz r expand_ipv6_addressAF_INET6)addrdecodedinvertedigroupingencodeds r r r sD
4yA~0@0@ &tt,fFVFVW[F\g!++FNNGDl4*
d #
qA!a%QU ,(
E!HEHqAa1q5k2HEddK
K( ((8$ 99//CCFDTDTU[UdUdflfvfvw~f EA Bl4 d Fs E.c N U H n[ U5 M g! [ a gf = f)NTF)r" rj )valuevs r rZ rZ s/
Ah s
$$c " [ X4U5 U $ )N)rE ) file_path line_prefixr) s r r! r! s I :; GGr c [ U5 n[ U 5 0 pTU HC nU( d O;U H1 nUR U5 ( d M XeU' UR U5 MA ME UR 5 U( aA [ U5 S:X a U < SUS < S3nOU < SSR
U5 < S3n[ U5 eU$ ! [ a n [ X)5 e Sn A ff = f) a
Fetches lines with the given prefixes from a file. This only provides back
the first instance of each prefix.
:param str file_path: path of the file to read
:param tuple line_prefixes: string prefixes of the lines to return
:param str parameter: description of the proc attribute being fetch
:returns: mapping of prefixes to the matching line
:raises: **IOError** if unable to read the file or can't find all of the prefixes
r z did not contain a r z entryz did not contain rD z entriesN) listr r removecloserY rF r& r' )
r
line_prefixesr) remaining_prefixesr rc r prefixmsgr, s
r rE rE s
m, i "w
&& ??6 " " &/
#
#F
+
' OO
A %1:B< A7B< <
C CCc j [ R " 5 U-
n[ R " SXU4- 5 g)z
Logs a message indicating a successful proc query.
:param str parameter: description of the proc attribute being fetch
:param str proc_location: proc files we were querying
:param int start_time: unix time for when this query was started
z#proc call (%s): %s (runtime: %0.4f)N)r r debug)r)
proc_locationr( runtimes r r% r% 4 s+
IIK* $')) 1Yw4W WXr c @ [ R " SU < SU< 35 g)z
Logs a message indicating that the proc query failed.
:param str parameter: description of the proc attribute being fetch
:param Exception exc: exception that we're raising
zproc call failed (r N)r r )r) r, s r r' r' A s ))9c :;r )NN)8__doc__r r r r sysr stem.prereqry stem.util.connectionstem.util.enumstem.util.str_tools stem.utilr r} rv ImportErrorprereq_is_lru_cache_available functoolsr stem.util.lru_cachesysconf
sysconf_namesrU AttributeError byteorderr r rz enumEnumr[ r r- r3 r5 r< rJ rf rn r rw r rZ r! rE r% r' get_system_start_timeget_physical_memoryget_cwdget_uidget_memory_usage get_statsget_connections r r r s ,\
;;&&((!+
2++L9:+ ==H, yy~~06
(
,
,
82 BAHO6R
j#L) XH)
X
Y< * %
e +s# D % D* D'&D'*D54D5