Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# Copyright (c) 2009, Giampaolo Rodola'. All rights reserved.
2# Use of this source code is governed by a BSD-style license that can be
3# found in the LICENSE file.
5"""Routines common to all posix systems."""
7import enum
8import errno
9import glob
10import os
11import select
12import signal
13import time
15from . import _ntuples as ntp
16from ._common import MACOS
17from ._common import TimeoutExpired
18from ._common import debug
19from ._common import memoize
20from ._common import usage_percent
22if MACOS:
23 from . import _psutil_osx
26__all__ = ['pid_exists', 'wait_pid', 'disk_usage', 'get_terminal_map']
29def pid_exists(pid):
30 """Check whether pid exists in the current process table."""
31 if pid == 0:
32 # According to "man 2 kill" PID 0 has a special meaning:
33 # it refers to <<every process in the process group of the
34 # calling process>> so we don't want to go any further.
35 # If we get here it means this UNIX platform *does* have
36 # a process with id 0.
37 return True
38 try:
39 os.kill(pid, 0)
40 except ProcessLookupError:
41 return False
42 except PermissionError:
43 # EPERM clearly means there's a process to deny access to
44 return True
45 # According to "man 2 kill" possible error values are
46 # (EINVAL, EPERM, ESRCH)
47 else:
48 return True
51Negsignal = enum.IntEnum(
52 'Negsignal', {x.name: -x.value for x in signal.Signals}
53)
56def negsig_to_enum(num):
57 """Convert a negative signal value to an enum."""
58 try:
59 return Negsignal(num)
60 except ValueError:
61 return num
64def convert_exit_code(status):
65 """Convert a os.waitpid() status to an exit code."""
66 if os.WIFEXITED(status):
67 # Process terminated normally by calling exit(3) or _exit(2),
68 # or by returning from main(). The return value is the
69 # positive integer passed to *exit().
70 return os.WEXITSTATUS(status)
71 if os.WIFSIGNALED(status):
72 # Process exited due to a signal. Return the negative value
73 # of that signal.
74 return negsig_to_enum(-os.WTERMSIG(status))
75 # if os.WIFSTOPPED(status):
76 # # Process was stopped via SIGSTOP or is being traced, and
77 # # waitpid() was called with WUNTRACED flag. PID is still
78 # # alive. From now on waitpid() will keep returning (0, 0)
79 # # until the process state doesn't change.
80 # # It may make sense to catch/enable this since stopped PIDs
81 # # ignore SIGTERM.
82 # interval = sleep(interval)
83 # continue
84 # if os.WIFCONTINUED(status):
85 # # Process was resumed via SIGCONT and waitpid() was called
86 # # with WCONTINUED flag.
87 # interval = sleep(interval)
88 # continue
90 # Should never happen.
91 msg = f"unknown process exit status {status!r}"
92 raise ValueError(msg)
95def wait_pid_posix(
96 pid,
97 timeout=None,
98 _waitpid=os.waitpid,
99 _timer=getattr(time, 'monotonic', time.time), # noqa: B008
100 _min=min,
101 _sleep=time.sleep,
102 _pid_exists=pid_exists,
103):
104 """Wait for a process PID to terminate.
106 If the process terminated normally by calling exit(3) or _exit(2),
107 or by returning from main(), the return value is the positive integer
108 passed to *exit().
110 If it was terminated by a signal it returns the negated value of the
111 signal which caused the termination (e.g. -SIGTERM).
113 If PID is not a children of os.getpid() (current process) just
114 wait until the process disappears and return None.
116 If PID does not exist at all return None immediately.
118 If timeout is specified and process is still alive raise
119 TimeoutExpired.
121 If timeout=0 either return immediately or raise TimeoutExpired
122 (non-blocking).
123 """
124 interval = 0.0001
125 max_interval = 0.04
126 flags = 0
127 stop_at = None
129 if timeout is not None:
130 flags |= os.WNOHANG
131 if timeout != 0:
132 stop_at = _timer() + timeout
134 def sleep_or_timeout(interval):
135 # Sleep for some time and return a new increased interval.
136 if timeout == 0 or (stop_at is not None and _timer() >= stop_at):
137 raise TimeoutExpired(timeout)
138 _sleep(interval)
139 return _min(interval * 2, max_interval)
141 # See: https://linux.die.net/man/2/waitpid
142 while True:
143 try:
144 retpid, status = os.waitpid(pid, flags)
145 except ChildProcessError:
146 # This has two meanings:
147 # - PID is not a child of os.getpid() in which case
148 # we keep polling until it's gone
149 # - PID never existed in the first place
150 # In both cases we'll eventually return None as we
151 # can't determine its exit status code.
152 while _pid_exists(pid):
153 interval = sleep_or_timeout(interval)
154 return None
155 else:
156 if retpid == 0:
157 # WNOHANG flag was used and PID is still running.
158 interval = sleep_or_timeout(interval)
159 else:
160 return convert_exit_code(status)
163def _waitpid(pid, timeout):
164 """Wrapper around os.waitpid(). PID is supposed to be gone already,
165 it just returns the exit code.
166 """
167 try:
168 retpid, status = os.waitpid(pid, 0)
169 except ChildProcessError:
170 # PID is not a child of os.getpid().
171 return wait_pid_posix(pid, timeout)
172 else:
173 assert retpid != 0
174 return convert_exit_code(status)
177def wait_pid_pidfd_open(pid, timeout=None):
178 """Wait for PID to terminate using pidfd_open() + poll(). Linux >=
179 5.3 + Python >= 3.9 only.
180 """
181 try:
182 pidfd = os.pidfd_open(pid, 0)
183 except OSError as err:
184 if err.errno == errno.ESRCH:
185 # No such process. os.waitpid() may still be able to return
186 # the status code.
187 return wait_pid_posix(pid, timeout)
188 if err.errno in {errno.EMFILE, errno.ENFILE, errno.ENODEV}:
189 # EMFILE, ENFILE: too many open files
190 # ENODEV: anonymous inode filesystem not supported
191 debug(f"pidfd_open() failed ({err!r}); use fallback")
192 return wait_pid_posix(pid, timeout)
193 raise
195 try:
196 # poll() / select() have the advantage of not requiring any
197 # extra file descriptor, contrary to epoll() / kqueue().
198 # select() crashes if process opens > 1024 FDs, so we use
199 # poll().
200 poller = select.poll()
201 poller.register(pidfd, select.POLLIN)
202 timeout_ms = None if timeout is None else int(timeout * 1000)
203 events = poller.poll(timeout_ms) # wait
205 if not events:
206 raise TimeoutExpired(timeout)
207 return _waitpid(pid, timeout)
208 finally:
209 os.close(pidfd)
212def wait_pid_kqueue(pid, timeout=None):
213 """Wait for PID to terminate using kqueue(). macOS and BSD only."""
214 try:
215 kq = select.kqueue()
216 except OSError as err:
217 if err.errno in {errno.EMFILE, errno.ENFILE}: # too many open files
218 debug(f"kqueue() failed ({err!r}); use fallback")
219 return wait_pid_posix(pid, timeout)
220 raise
222 try:
223 kev = select.kevent(
224 pid,
225 filter=select.KQ_FILTER_PROC,
226 flags=select.KQ_EV_ADD | select.KQ_EV_ONESHOT,
227 fflags=select.KQ_NOTE_EXIT,
228 )
229 try:
230 events = kq.control([kev], 1, timeout) # wait
231 except OSError as err:
232 if err.errno in {errno.EACCES, errno.EPERM, errno.ESRCH}:
233 debug(f"kqueue.control() failed ({err!r}); use fallback")
234 return wait_pid_posix(pid, timeout)
235 raise
236 else:
237 if not events:
238 raise TimeoutExpired(timeout)
239 return _waitpid(pid, timeout)
240 finally:
241 kq.close()
244@memoize
245def can_use_pidfd():
246 # Availability: Linux >= 5.3, Python >= 3.9
247 if not hasattr(os, "pidfd_open"):
248 return False
249 try:
250 pidfd = os.pidfd_open(os.getpid(), 0)
251 except OSError as err:
252 # blocked by security policy like SECCOMP
253 debug(f"can't use pidfd_open() due to {err}")
254 return False
255 else:
256 os.close(pidfd)
257 return True
260@memoize
261def can_use_kqueue():
262 names = (
263 "kqueue",
264 "KQ_EV_ADD",
265 "KQ_EV_ONESHOT",
266 "KQ_FILTER_PROC",
267 "KQ_NOTE_EXIT",
268 )
269 return all(hasattr(select, x) for x in names)
272def wait_pid(pid, timeout=None):
273 # PID 0 passed to waitpid() waits for any child of the current
274 # process to change state.
275 assert pid > 0
276 if timeout is not None:
277 assert timeout >= 0
279 if can_use_pidfd():
280 return wait_pid_pidfd_open(pid, timeout)
281 elif can_use_kqueue():
282 return wait_pid_kqueue(pid, timeout)
283 else:
284 return wait_pid_posix(pid, timeout)
287wait_pid.__doc__ = wait_pid_posix.__doc__
290def disk_usage(path):
291 """Return disk usage associated with path.
292 Note: UNIX usually reserves 5% disk space which is not accessible
293 by user. In this function "total" and "used" values reflect the
294 total and used disk space whereas "free" and "percent" represent
295 the "free" and "used percent" user disk space.
296 """
297 st = os.statvfs(path)
298 # Total space which is only available to root (unless changed
299 # at system level).
300 total = st.f_blocks * st.f_frsize
301 # Remaining free space usable by root.
302 avail_to_root = st.f_bfree * st.f_frsize
303 # Remaining free space usable by user.
304 avail_to_user = st.f_bavail * st.f_frsize
305 # Total space being used in general.
306 used = total - avail_to_root
307 if MACOS:
308 # see: https://github.com/giampaolo/psutil/pull/2152
309 used = _psutil_osx.disk_usage_used(path, used)
310 # Total space which is available to user (same as 'total' but
311 # for the user).
312 total_user = used + avail_to_user
313 # User usage percent compared to the total amount of space
314 # the user can use. This number would be higher if compared
315 # to root's because the user has less space (usually -5%).
316 usage_percent_user = usage_percent(used, total_user, round_=1)
318 # NB: the percentage is -5% than what shown by df due to
319 # reserved blocks that we are currently not considering:
320 # https://github.com/giampaolo/psutil/issues/829#issuecomment-223750462
321 return ntp.sdiskusage(
322 total=total, used=used, free=avail_to_user, percent=usage_percent_user
323 )
326@memoize
327def get_terminal_map():
328 """Get a map of device-id -> path as a dict.
329 Used by Process.terminal().
330 """
331 ret = {}
332 ls = glob.glob('/dev/tty*') + glob.glob('/dev/pts/*')
333 for name in ls:
334 assert name not in ret, name
335 try:
336 ret[os.stat(name).st_rdev] = name
337 except FileNotFoundError:
338 pass
339 return ret