blob: 87689cc26901eaa383f30b116ade34cb6d66e9a9 [file] [log] [blame]
Georg Brandlbde4ad42006-01-20 21:36:02 +00001r"""OS routines for Mac, NT, or Posix depending on what system we're on.
Guido van Rossum31104f41992-01-14 18:28:36 +00002
Guido van Rossum54f22ed2000-02-04 15:10:34 +00003This exports:
Alexandre Vassalottieca20b62008-05-16 02:54:33 +00004 - all functions from posix, nt, os2, or ce, e.g. unlink, stat, etc.
5 - os.path is either posixpath or ntpath
6 - os.name is either 'posix', 'nt', 'os2' or 'ce'.
Guido van Rossum54f22ed2000-02-04 15:10:34 +00007 - os.curdir is a string representing the current directory ('.' or ':')
8 - os.pardir is a string representing the parent directory ('..' or '::')
9 - os.sep is the (or a most common) pathname separator ('/' or ':' or '\\')
Georg Brandled5b9b32008-12-05 07:45:54 +000010 - os.extsep is the extension separator (always '.')
Guido van Rossum4b8c6ea2000-02-04 15:39:30 +000011 - os.altsep is the alternate pathname separator (None or '/')
Guido van Rossum54f22ed2000-02-04 15:10:34 +000012 - os.pathsep is the component separator used in $PATH etc
Guido van Rossum4b8c6ea2000-02-04 15:39:30 +000013 - os.linesep is the line separator in text files ('\r' or '\n' or '\r\n')
Guido van Rossum54f22ed2000-02-04 15:10:34 +000014 - os.defpath is the default search path for executables
Martin v. Löwisbdec50f2004-06-08 08:29:33 +000015 - os.devnull is the file path of the null device ('/dev/null', etc.)
Guido van Rossum31104f41992-01-14 18:28:36 +000016
Guido van Rossum54f22ed2000-02-04 15:10:34 +000017Programs that import and use 'os' stand a better chance of being
18portable between different platforms. Of course, they must then
19only use functions that are defined by all platforms (e.g., unlink
20and opendir), and leave all pathname manipulation to os.path
21(e.g., split and join).
22"""
Guido van Rossum31104f41992-01-14 18:28:36 +000023
Skip Montanaro269b83b2001-02-06 01:07:02 +000024#'
25
Christian Heimes45f9af32007-11-27 21:50:00 +000026import sys, errno
Charles-François Natali7372b062012-02-05 15:15:38 +010027import stat as st
Guido van Rossuma28dab51997-08-29 22:36:47 +000028
29_names = sys.builtin_module_names
30
Tim Petersc4e09402003-04-25 07:11:48 +000031# Note: more names are added to __all__ later.
Brett Cannon13962fc2008-08-18 01:45:29 +000032__all__ = ["altsep", "curdir", "pardir", "sep", "pathsep", "linesep",
Petri Lehtinen3bc37f22012-05-23 21:36:16 +030033 "defpath", "name", "path", "devnull", "SEEK_SET", "SEEK_CUR",
34 "SEEK_END", "fsencode", "fsdecode", "get_exec_path", "fdopen",
35 "popen", "extsep"]
Skip Montanaro269b83b2001-02-06 01:07:02 +000036
Charles-François Natali7372b062012-02-05 15:15:38 +010037def _exists(name):
38 return name in globals()
39
Skip Montanaro269b83b2001-02-06 01:07:02 +000040def _get_exports_list(module):
41 try:
42 return list(module.__all__)
43 except AttributeError:
44 return [n for n in dir(module) if n[0] != '_']
45
Brett Cannonfd074152012-04-14 14:10:13 -040046# Any new dependencies of the os module and/or changes in path separator
47# requires updating importlib as well.
Guido van Rossuma28dab51997-08-29 22:36:47 +000048if 'posix' in _names:
Guido van Rossum61de0ac1997-12-05 21:24:30 +000049 name = 'posix'
Guido van Rossume9387ea1998-05-22 15:26:04 +000050 linesep = '\n'
Guido van Rossum61de0ac1997-12-05 21:24:30 +000051 from posix import *
52 try:
53 from posix import _exit
Petri Lehtinen3bc37f22012-05-23 21:36:16 +030054 __all__.append('_exit')
Guido van Rossum61de0ac1997-12-05 21:24:30 +000055 except ImportError:
56 pass
Skip Montanaro117910d2003-02-14 19:35:31 +000057 import posixpath as path
Tim Petersf2715e02003-02-19 02:35:07 +000058
Larry Hastings9cf065c2012-06-22 16:30:09 -070059 try:
60 from posix import _have_functions
61 except ImportError:
62 pass
Skip Montanaro269b83b2001-02-06 01:07:02 +000063
Guido van Rossuma28dab51997-08-29 22:36:47 +000064elif 'nt' in _names:
Guido van Rossum61de0ac1997-12-05 21:24:30 +000065 name = 'nt'
Guido van Rossume9387ea1998-05-22 15:26:04 +000066 linesep = '\r\n'
Guido van Rossum61de0ac1997-12-05 21:24:30 +000067 from nt import *
Tim Peters6757c1e2003-01-08 21:20:57 +000068 try:
69 from nt import _exit
Petri Lehtinen3bc37f22012-05-23 21:36:16 +030070 __all__.append('_exit')
Tim Peters6757c1e2003-01-08 21:20:57 +000071 except ImportError:
72 pass
Skip Montanaro117910d2003-02-14 19:35:31 +000073 import ntpath as path
Tim Petersf2715e02003-02-19 02:35:07 +000074
Skip Montanaro269b83b2001-02-06 01:07:02 +000075 import nt
76 __all__.extend(_get_exports_list(nt))
77 del nt
78
Larry Hastings9cf065c2012-06-22 16:30:09 -070079 try:
80 from nt import _have_functions
81 except ImportError:
82 pass
83
Guido van Rossum8e9ebfd1997-11-22 21:53:48 +000084elif 'os2' in _names:
Guido van Rossum61de0ac1997-12-05 21:24:30 +000085 name = 'os2'
Guido van Rossume9387ea1998-05-22 15:26:04 +000086 linesep = '\r\n'
Guido van Rossum61de0ac1997-12-05 21:24:30 +000087 from os2 import *
88 try:
89 from os2 import _exit
Petri Lehtinen3bc37f22012-05-23 21:36:16 +030090 __all__.append('_exit')
Guido van Rossum61de0ac1997-12-05 21:24:30 +000091 except ImportError:
92 pass
Andrew MacIntyre5cef5712002-02-24 05:32:32 +000093 if sys.version.find('EMX GCC') == -1:
Skip Montanaro117910d2003-02-14 19:35:31 +000094 import ntpath as path
Andrew MacIntyre5cef5712002-02-24 05:32:32 +000095 else:
Skip Montanaro117910d2003-02-14 19:35:31 +000096 import os2emxpath as path
Andrew MacIntyre89f98652003-12-02 12:33:01 +000097 from _emx_link import link
Tim Petersf2715e02003-02-19 02:35:07 +000098
Skip Montanaro269b83b2001-02-06 01:07:02 +000099 import os2
100 __all__.extend(_get_exports_list(os2))
101 del os2
102
Larry Hastings9cf065c2012-06-22 16:30:09 -0700103 try:
104 from os2 import _have_functions
105 except ImportError:
106 pass
107
Guido van Rossum18df5d41999-06-11 01:37:27 +0000108elif 'ce' in _names:
109 name = 'ce'
110 linesep = '\r\n'
Guido van Rossum18df5d41999-06-11 01:37:27 +0000111 from ce import *
Tim Peters6757c1e2003-01-08 21:20:57 +0000112 try:
113 from ce import _exit
Petri Lehtinen3bc37f22012-05-23 21:36:16 +0300114 __all__.append('_exit')
Tim Peters6757c1e2003-01-08 21:20:57 +0000115 except ImportError:
116 pass
Guido van Rossum18df5d41999-06-11 01:37:27 +0000117 # We can use the standard Windows path.
Skip Montanaro117910d2003-02-14 19:35:31 +0000118 import ntpath as path
Tim Petersf2715e02003-02-19 02:35:07 +0000119
Skip Montanaro269b83b2001-02-06 01:07:02 +0000120 import ce
121 __all__.extend(_get_exports_list(ce))
122 del ce
123
Larry Hastings9cf065c2012-06-22 16:30:09 -0700124 try:
125 from ce import _have_functions
126 except ImportError:
127 pass
128
Guido van Rossum2979b011994-08-01 11:18:30 +0000129else:
Collin Winter828f04a2007-08-31 00:04:24 +0000130 raise ImportError('no os specific module found')
Guido van Rossume65cce51993-11-08 15:05:21 +0000131
Skip Montanaro117910d2003-02-14 19:35:31 +0000132sys.modules['os.path'] = path
Georg Brandled5b9b32008-12-05 07:45:54 +0000133from os.path import (curdir, pardir, sep, pathsep, defpath, extsep, altsep,
134 devnull)
Skip Montanaro269b83b2001-02-06 01:07:02 +0000135
Guido van Rossuma28dab51997-08-29 22:36:47 +0000136del _names
137
Larry Hastings9cf065c2012-06-22 16:30:09 -0700138
139if _exists("_have_functions"):
140 _globals = globals()
141 def _add(str, fn):
142 if (fn in _globals) and (str in _have_functions):
143 _set.add(_globals[fn])
144
145 _set = set()
146 _add("HAVE_FACCESSAT", "access")
147 _add("HAVE_FCHMODAT", "chmod")
148 _add("HAVE_FCHOWNAT", "chown")
149 _add("HAVE_FSTATAT", "stat")
150 _add("HAVE_FUTIMESAT", "utime")
151 _add("HAVE_LINKAT", "link")
152 _add("HAVE_MKDIRAT", "mkdir")
153 _add("HAVE_MKFIFOAT", "mkfifo")
154 _add("HAVE_MKNODAT", "mknod")
155 _add("HAVE_OPENAT", "open")
156 _add("HAVE_READLINKAT", "readlink")
157 _add("HAVE_RENAMEAT", "rename")
158 _add("HAVE_SYMLINKAT", "symlink")
159 _add("HAVE_UNLINKAT", "unlink")
Larry Hastingsb698d8e2012-06-23 16:55:07 -0700160 _add("HAVE_UNLINKAT", "rmdir")
Larry Hastings9cf065c2012-06-22 16:30:09 -0700161 _add("HAVE_UTIMENSAT", "utime")
162 supports_dir_fd = _set
163
164 _set = set()
165 _add("HAVE_FACCESSAT", "access")
166 supports_effective_ids = _set
167
168 _set = set()
169 _add("HAVE_FCHDIR", "chdir")
170 _add("HAVE_FCHMOD", "chmod")
171 _add("HAVE_FCHOWN", "chown")
172 _add("HAVE_FDOPENDIR", "listdir")
173 _add("HAVE_FEXECVE", "execve")
174 _set.add(stat) # fstat always works
Georg Brandl306336b2012-06-24 12:55:33 +0200175 _add("HAVE_FTRUNCATE", "truncate")
Larry Hastings9cf065c2012-06-22 16:30:09 -0700176 _add("HAVE_FUTIMENS", "utime")
177 _add("HAVE_FUTIMES", "utime")
Georg Brandl306336b2012-06-24 12:55:33 +0200178 _add("HAVE_FPATHCONF", "pathconf")
Larry Hastings9cf065c2012-06-22 16:30:09 -0700179 if _exists("statvfs") and _exists("fstatvfs"): # mac os x10.3
180 _add("HAVE_FSTATVFS", "statvfs")
181 supports_fd = _set
182
183 _set = set()
184 _add("HAVE_FACCESSAT", "access")
Larry Hastingsdbbc0c82012-06-22 19:50:21 -0700185 # Some platforms don't support lchmod(). Often the function exists
186 # anyway, as a stub that always returns ENOSUP or perhaps EOPNOTSUPP.
187 # (No, I don't know why that's a good design.) ./configure will detect
188 # this and reject it--so HAVE_LCHMOD still won't be defined on such
189 # platforms. This is Very Helpful.
190 #
191 # However, sometimes platforms without a working lchmod() *do* have
192 # fchmodat(). (Examples: Linux kernel 3.2 with glibc 2.15,
193 # OpenIndiana 3.x.) And fchmodat() has a flag that theoretically makes
194 # it behave like lchmod(). So in theory it would be a suitable
195 # replacement for lchmod(). But when lchmod() doesn't work, fchmodat()'s
196 # flag doesn't work *either*. Sadly ./configure isn't sophisticated
197 # enough to detect this condition--it only determines whether or not
198 # fchmodat() minimally works.
199 #
200 # Therefore we simply ignore fchmodat() when deciding whether or not
201 # os.chmod supports follow_symlinks. Just checking lchmod() is
202 # sufficient. After all--if you have a working fchmodat(), your
203 # lchmod() almost certainly works too.
204 #
205 # _add("HAVE_FCHMODAT", "chmod")
Larry Hastings9cf065c2012-06-22 16:30:09 -0700206 _add("HAVE_FCHOWNAT", "chown")
207 _add("HAVE_FSTATAT", "stat")
208 _add("HAVE_LCHFLAGS", "chflags")
209 _add("HAVE_LCHMOD", "chmod")
210 if _exists("lchown"): # mac os x10.3
211 _add("HAVE_LCHOWN", "chown")
212 _add("HAVE_LINKAT", "link")
213 _add("HAVE_LUTIMES", "utime")
214 _add("HAVE_LSTAT", "stat")
215 _add("HAVE_FSTATAT", "stat")
216 _add("HAVE_UTIMENSAT", "utime")
217 _add("MS_WINDOWS", "stat")
218 supports_follow_symlinks = _set
219
Larry Hastings9cf065c2012-06-22 16:30:09 -0700220 del _set
221 del _have_functions
222 del _globals
223 del _add
224
225
Martin v. Löwis22b457e2005-01-16 08:40:58 +0000226# Python uses fixed values for the SEEK_ constants; they are mapped
227# to native constants if necessary in posixmodule.c
Jesus Cea94363612012-06-22 18:32:07 +0200228# Other possible SEEK values are directly imported from posixmodule.c
Martin v. Löwis22b457e2005-01-16 08:40:58 +0000229SEEK_SET = 0
230SEEK_CUR = 1
231SEEK_END = 2
232
Terry Reedy5a22b652010-12-02 07:05:56 +0000233
234def _get_masked_mode(mode):
235 mask = umask(0)
236 umask(mask)
237 return mode & ~mask
238
Guido van Rossum4def7de1998-07-24 20:48:03 +0000239# Super directory utilities.
240# (Inspired by Eric Raymond; the doc strings are mostly his)
241
Terry Reedy5a22b652010-12-02 07:05:56 +0000242def makedirs(name, mode=0o777, exist_ok=False):
243 """makedirs(path [, mode=0o777][, exist_ok=False])
Guido van Rossum4def7de1998-07-24 20:48:03 +0000244
245 Super-mkdir; create a leaf directory and all intermediate ones.
246 Works like mkdir, except that any intermediate path segment (not
Terry Reedy5a22b652010-12-02 07:05:56 +0000247 just the rightmost) will be created if it does not exist. If the
248 target directory with the same mode as we specified already exists,
249 raises an OSError if exist_ok is False, otherwise no exception is
250 raised. This is recursive.
Guido van Rossum4def7de1998-07-24 20:48:03 +0000251
252 """
253 head, tail = path.split(name)
Fred Drake9f2550f2000-07-25 15:16:40 +0000254 if not tail:
255 head, tail = path.split(head)
Guido van Rossum4def7de1998-07-24 20:48:03 +0000256 if head and tail and not path.exists(head):
Thomas Wouters89f507f2006-12-13 04:49:30 +0000257 try:
Terry Reedy5a22b652010-12-02 07:05:56 +0000258 makedirs(head, mode, exist_ok)
Guido van Rossumb940e112007-01-10 16:19:56 +0000259 except OSError as e:
Thomas Wouters89f507f2006-12-13 04:49:30 +0000260 # be happy if someone already created the path
Christian Heimes45f9af32007-11-27 21:50:00 +0000261 if e.errno != errno.EEXIST:
Thomas Wouters89f507f2006-12-13 04:49:30 +0000262 raise
Serhiy Storchaka4ab23bf2013-01-08 11:32:58 +0200263 cdir = curdir
264 if isinstance(tail, bytes):
265 cdir = bytes(curdir, 'ASCII')
266 if tail == cdir: # xxx/newdir/. exists if xxx/newdir exists
Andrew M. Kuchling6fccc8a2003-12-23 16:33:28 +0000267 return
Terry Reedy5a22b652010-12-02 07:05:56 +0000268 try:
269 mkdir(name, mode)
270 except OSError as e:
Gregory P. Smitha81c8562012-06-03 14:30:44 -0700271 dir_exists = path.isdir(name)
272 expected_mode = _get_masked_mode(mode)
273 if dir_exists:
274 # S_ISGID is automatically copied by the OS from parent to child
275 # directories on mkdir. Don't consider it being set to be a mode
276 # mismatch as mkdir does not unset it when not specified in mode.
277 actual_mode = st.S_IMODE(lstat(name).st_mode) & ~st.S_ISGID
278 else:
279 actual_mode = -1
280 if not (e.errno == errno.EEXIST and exist_ok and dir_exists and
281 actual_mode == expected_mode):
282 if dir_exists and actual_mode != expected_mode:
283 e.strerror += ' (mode %o != expected mode %o)' % (
284 actual_mode, expected_mode)
Terry Reedy5a22b652010-12-02 07:05:56 +0000285 raise
Guido van Rossum4def7de1998-07-24 20:48:03 +0000286
287def removedirs(name):
Fred Drakecadb9eb2002-07-02 21:28:04 +0000288 """removedirs(path)
Guido van Rossum4def7de1998-07-24 20:48:03 +0000289
Fredrik Lundh96c1c7a2005-11-12 15:55:04 +0000290 Super-rmdir; remove a leaf directory and all empty intermediate
Guido van Rossum4def7de1998-07-24 20:48:03 +0000291 ones. Works like rmdir except that, if the leaf directory is
292 successfully removed, directories corresponding to rightmost path
Tim Petersc4e09402003-04-25 07:11:48 +0000293 segments will be pruned away until either the whole path is
Guido van Rossum4def7de1998-07-24 20:48:03 +0000294 consumed or an error occurs. Errors during this latter phase are
295 ignored -- they generally mean that a directory was not empty.
296
297 """
298 rmdir(name)
299 head, tail = path.split(name)
Fred Drake9f2550f2000-07-25 15:16:40 +0000300 if not tail:
301 head, tail = path.split(head)
Guido van Rossum4def7de1998-07-24 20:48:03 +0000302 while head and tail:
303 try:
304 rmdir(head)
305 except error:
306 break
307 head, tail = path.split(head)
308
309def renames(old, new):
Fred Drakecadb9eb2002-07-02 21:28:04 +0000310 """renames(old, new)
Guido van Rossum4def7de1998-07-24 20:48:03 +0000311
312 Super-rename; create directories as necessary and delete any left
313 empty. Works like rename, except creation of any intermediate
314 directories needed to make the new pathname good is attempted
315 first. After the rename, directories corresponding to rightmost
316 path segments of the old name will be pruned way until either the
317 whole path is consumed or a nonempty directory is found.
318
319 Note: this function can fail with the new directory structure made
320 if you lack permissions needed to unlink the leaf directory or
321 file.
322
323 """
324 head, tail = path.split(new)
325 if head and tail and not path.exists(head):
326 makedirs(head)
327 rename(old, new)
328 head, tail = path.split(old)
329 if head and tail:
330 try:
331 removedirs(head)
332 except error:
333 pass
334
Skip Montanaro269b83b2001-02-06 01:07:02 +0000335__all__.extend(["makedirs", "removedirs", "renames"])
336
Guido van Rossumd8faa362007-04-27 19:54:29 +0000337def walk(top, topdown=True, onerror=None, followlinks=False):
Tim Petersc4e09402003-04-25 07:11:48 +0000338 """Directory tree generator.
339
340 For each directory in the directory tree rooted at top (including top
341 itself, but excluding '.' and '..'), yields a 3-tuple
342
343 dirpath, dirnames, filenames
344
345 dirpath is a string, the path to the directory. dirnames is a list of
346 the names of the subdirectories in dirpath (excluding '.' and '..').
347 filenames is a list of the names of the non-directory files in dirpath.
348 Note that the names in the lists are just names, with no path components.
349 To get a full path (which begins with top) to a file or directory in
350 dirpath, do os.path.join(dirpath, name).
351
352 If optional arg 'topdown' is true or not specified, the triple for a
353 directory is generated before the triples for any of its subdirectories
354 (directories are generated top down). If topdown is false, the triple
355 for a directory is generated after the triples for all of its
356 subdirectories (directories are generated bottom up).
357
358 When topdown is true, the caller can modify the dirnames list in-place
359 (e.g., via del or slice assignment), and walk will only recurse into the
360 subdirectories whose names remain in dirnames; this can be used to prune
361 the search, or to impose a specific order of visiting. Modifying
362 dirnames when topdown is false is ineffective, since the directories in
363 dirnames have already been generated by the time dirnames itself is
364 generated.
365
Guido van Rossumbf1bef82003-05-13 18:01:19 +0000366 By default errors from the os.listdir() call are ignored. If
367 optional arg 'onerror' is specified, it should be a function; it
368 will be called with one argument, an os.error instance. It can
369 report the error to continue with the walk, or raise the exception
370 to abort the walk. Note that the filename is available as the
371 filename attribute of the exception object.
372
Guido van Rossumd8faa362007-04-27 19:54:29 +0000373 By default, os.walk does not follow symbolic links to subdirectories on
374 systems that support them. In order to get this functionality, set the
375 optional argument 'followlinks' to true.
376
Tim Petersc4e09402003-04-25 07:11:48 +0000377 Caution: if you pass a relative pathname for top, don't change the
378 current working directory between resumptions of walk. walk never
379 changes the current directory, and assumes that the client doesn't
380 either.
381
382 Example:
383
Christian Heimes5d8da202008-05-06 13:58:24 +0000384 import os
Tim Petersc4e09402003-04-25 07:11:48 +0000385 from os.path import join, getsize
Christian Heimes5d8da202008-05-06 13:58:24 +0000386 for root, dirs, files in os.walk('python/Lib/email'):
Neal Norwitz752abd02008-05-13 04:55:24 +0000387 print(root, "consumes", end="")
388 print(sum([getsize(join(root, name)) for name in files]), end="")
389 print("bytes in", len(files), "non-directory files")
Tim Petersc4e09402003-04-25 07:11:48 +0000390 if 'CVS' in dirs:
391 dirs.remove('CVS') # don't visit CVS directories
392 """
393
Benjamin Petersonf6489f92009-11-25 17:46:26 +0000394 islink, join, isdir = path.islink, path.join, path.isdir
Tim Petersc4e09402003-04-25 07:11:48 +0000395
396 # We may not have read permission for top, in which case we can't
Alexandre Vassalotti4e6531e2008-05-09 20:00:17 +0000397 # get a list of the files the directory contains. os.walk
Tim Petersc4e09402003-04-25 07:11:48 +0000398 # always suppressed the exception then, rather than blow up for a
399 # minor reason when (say) a thousand readable directories are still
400 # left to visit. That logic is copied here.
401 try:
402 # Note that listdir and error are globals in this module due
403 # to earlier import-*.
404 names = listdir(top)
Guido van Rossumb940e112007-01-10 16:19:56 +0000405 except error as err:
Guido van Rossumbf1bef82003-05-13 18:01:19 +0000406 if onerror is not None:
407 onerror(err)
Tim Petersc4e09402003-04-25 07:11:48 +0000408 return
409
410 dirs, nondirs = [], []
411 for name in names:
412 if isdir(join(top, name)):
413 dirs.append(name)
414 else:
415 nondirs.append(name)
416
417 if topdown:
418 yield top, dirs, nondirs
419 for name in dirs:
Benjamin Petersonf6489f92009-11-25 17:46:26 +0000420 new_path = join(top, name)
421 if followlinks or not islink(new_path):
Benjamin Peterson569d0872012-05-10 16:17:35 -0500422 yield from walk(new_path, topdown, onerror, followlinks)
Tim Petersc4e09402003-04-25 07:11:48 +0000423 if not topdown:
424 yield top, dirs, nondirs
425
426__all__.append("walk")
427
Larry Hastingsc48fe982012-06-25 04:49:05 -0700428if {open, stat} <= supports_dir_fd and {listdir, stat} <= supports_fd:
Charles-François Natali7372b062012-02-05 15:15:38 +0100429
Larry Hastingsb4038062012-07-15 10:57:38 -0700430 def fwalk(top=".", topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None):
Charles-François Natali7372b062012-02-05 15:15:38 +0100431 """Directory tree generator.
432
433 This behaves exactly like walk(), except that it yields a 4-tuple
434
435 dirpath, dirnames, filenames, dirfd
436
437 `dirpath`, `dirnames` and `filenames` are identical to walk() output,
438 and `dirfd` is a file descriptor referring to the directory `dirpath`.
439
Larry Hastingsc48fe982012-06-25 04:49:05 -0700440 The advantage of fwalk() over walk() is that it's safe against symlink
Larry Hastingsb4038062012-07-15 10:57:38 -0700441 races (when follow_symlinks is False).
Charles-François Natali7372b062012-02-05 15:15:38 +0100442
Larry Hastingsc48fe982012-06-25 04:49:05 -0700443 If dir_fd is not None, it should be a file descriptor open to a directory,
444 and top should be relative; top will then be relative to that directory.
445 (dir_fd is always supported for fwalk.)
446
Charles-François Natali7372b062012-02-05 15:15:38 +0100447 Caution:
448 Since fwalk() yields file descriptors, those are only valid until the
449 next iteration step, so you should dup() them if you want to keep them
450 for a longer period.
451
452 Example:
453
454 import os
455 for root, dirs, files, rootfd in os.fwalk('python/Lib/email'):
456 print(root, "consumes", end="")
Larry Hastings9cf065c2012-06-22 16:30:09 -0700457 print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]),
Charles-François Natali7372b062012-02-05 15:15:38 +0100458 end="")
459 print("bytes in", len(files), "non-directory files")
460 if 'CVS' in dirs:
461 dirs.remove('CVS') # don't visit CVS directories
462 """
463 # Note: To guard against symlink races, we use the standard
464 # lstat()/open()/fstat() trick.
Larry Hastingsc48fe982012-06-25 04:49:05 -0700465 orig_st = stat(top, follow_symlinks=False, dir_fd=dir_fd)
466 topfd = open(top, O_RDONLY, dir_fd=dir_fd)
Charles-François Natali7372b062012-02-05 15:15:38 +0100467 try:
Larry Hastingsb4038062012-07-15 10:57:38 -0700468 if (follow_symlinks or (st.S_ISDIR(orig_st.st_mode) and
469 path.samestat(orig_st, stat(topfd)))):
470 yield from _fwalk(topfd, top, topdown, onerror, follow_symlinks)
Charles-François Natali7372b062012-02-05 15:15:38 +0100471 finally:
472 close(topfd)
473
Larry Hastingsb4038062012-07-15 10:57:38 -0700474 def _fwalk(topfd, toppath, topdown, onerror, follow_symlinks):
Charles-François Natali7372b062012-02-05 15:15:38 +0100475 # Note: This uses O(depth of the directory tree) file descriptors: if
476 # necessary, it can be adapted to only require O(1) FDs, see issue
477 # #13734.
478
Larry Hastings9cf065c2012-06-22 16:30:09 -0700479 names = listdir(topfd)
Charles-François Natali7372b062012-02-05 15:15:38 +0100480 dirs, nondirs = [], []
481 for name in names:
Hynek Schlawack66bfcc12012-05-15 16:32:21 +0200482 try:
483 # Here, we don't use AT_SYMLINK_NOFOLLOW to be consistent with
484 # walk() which reports symlinks to directories as directories.
485 # We do however check for symlinks before recursing into
486 # a subdirectory.
Larry Hastings9cf065c2012-06-22 16:30:09 -0700487 if st.S_ISDIR(stat(name, dir_fd=topfd).st_mode):
Hynek Schlawack66bfcc12012-05-15 16:32:21 +0200488 dirs.append(name)
489 else:
490 nondirs.append(name)
491 except FileNotFoundError:
492 try:
493 # Add dangling symlinks, ignore disappeared files
Larry Hastings9cf065c2012-06-22 16:30:09 -0700494 if st.S_ISLNK(stat(name, dir_fd=topfd, follow_symlinks=False)
Hynek Schlawack66bfcc12012-05-15 16:32:21 +0200495 .st_mode):
496 nondirs.append(name)
497 except FileNotFoundError:
498 continue
Charles-François Natali7372b062012-02-05 15:15:38 +0100499
500 if topdown:
501 yield toppath, dirs, nondirs, topfd
502
503 for name in dirs:
504 try:
Larry Hastingsb4038062012-07-15 10:57:38 -0700505 orig_st = stat(name, dir_fd=topfd, follow_symlinks=follow_symlinks)
Larry Hastings9cf065c2012-06-22 16:30:09 -0700506 dirfd = open(name, O_RDONLY, dir_fd=topfd)
Charles-François Natali7372b062012-02-05 15:15:38 +0100507 except error as err:
508 if onerror is not None:
509 onerror(err)
510 return
511 try:
Larry Hastingsb4038062012-07-15 10:57:38 -0700512 if follow_symlinks or path.samestat(orig_st, stat(dirfd)):
Charles-François Natali7372b062012-02-05 15:15:38 +0100513 dirpath = path.join(toppath, name)
Larry Hastingsb4038062012-07-15 10:57:38 -0700514 yield from _fwalk(dirfd, dirpath, topdown, onerror, follow_symlinks)
Charles-François Natali7372b062012-02-05 15:15:38 +0100515 finally:
516 close(dirfd)
517
518 if not topdown:
519 yield toppath, dirs, nondirs, topfd
520
521 __all__.append("fwalk")
522
Guido van Rossuma28dab51997-08-29 22:36:47 +0000523# Make sure os.environ exists, at least
524try:
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000525 environ
Guido van Rossuma28dab51997-08-29 22:36:47 +0000526except NameError:
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000527 environ = {}
Guido van Rossuma28dab51997-08-29 22:36:47 +0000528
Guido van Rossume65cce51993-11-08 15:05:21 +0000529def execl(file, *args):
Guido van Rossum7da3cc52000-04-25 10:53:22 +0000530 """execl(file, *args)
531
532 Execute the executable file with argument list args, replacing the
533 current process. """
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000534 execv(file, args)
Guido van Rossume65cce51993-11-08 15:05:21 +0000535
536def execle(file, *args):
Guido van Rossum7da3cc52000-04-25 10:53:22 +0000537 """execle(file, *args, env)
538
539 Execute the executable file with argument list args and
540 environment env, replacing the current process. """
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000541 env = args[-1]
542 execve(file, args[:-1], env)
Guido van Rossume65cce51993-11-08 15:05:21 +0000543
544def execlp(file, *args):
Guido van Rossum7da3cc52000-04-25 10:53:22 +0000545 """execlp(file, *args)
546
547 Execute the executable file (which is searched for along $PATH)
548 with argument list args, replacing the current process. """
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000549 execvp(file, args)
Guido van Rossume65cce51993-11-08 15:05:21 +0000550
Guido van Rossum030afb11995-03-14 17:27:18 +0000551def execlpe(file, *args):
Guido van Rossum7da3cc52000-04-25 10:53:22 +0000552 """execlpe(file, *args, env)
553
554 Execute the executable file (which is searched for along $PATH)
555 with argument list args and environment env, replacing the current
Tim Peters2344fae2001-01-15 00:50:52 +0000556 process. """
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000557 env = args[-1]
558 execvpe(file, args[:-1], env)
Guido van Rossum030afb11995-03-14 17:27:18 +0000559
Guido van Rossume65cce51993-11-08 15:05:21 +0000560def execvp(file, args):
Matthias Klosea09c54f2010-01-31 16:48:44 +0000561 """execvp(file, args)
Guido van Rossum7da3cc52000-04-25 10:53:22 +0000562
563 Execute the executable file (which is searched for along $PATH)
564 with argument list args, replacing the current process.
Thomas Wouters7e474022000-07-16 12:04:32 +0000565 args may be a list or tuple of strings. """
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000566 _execvpe(file, args)
Guido van Rossum030afb11995-03-14 17:27:18 +0000567
568def execvpe(file, args, env):
Guido van Rossum683c0fe2002-09-03 16:36:17 +0000569 """execvpe(file, args, env)
Guido van Rossum7da3cc52000-04-25 10:53:22 +0000570
571 Execute the executable file (which is searched for along $PATH)
572 with argument list args and environment env , replacing the
573 current process.
Tim Peters2344fae2001-01-15 00:50:52 +0000574 args may be a list or tuple of strings. """
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000575 _execvpe(file, args, env)
Guido van Rossum030afb11995-03-14 17:27:18 +0000576
Skip Montanaro269b83b2001-02-06 01:07:02 +0000577__all__.extend(["execl","execle","execlp","execlpe","execvp","execvpe"])
578
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000579def _execvpe(file, args, env=None):
580 if env is not None:
Gregory P. Smithb6e8c7e2010-02-27 07:22:22 +0000581 exec_func = execve
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000582 argrest = (args, env)
583 else:
Gregory P. Smithb6e8c7e2010-02-27 07:22:22 +0000584 exec_func = execv
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000585 argrest = (args,)
586 env = environ
Guido van Rossumaed51d82002-08-05 16:13:24 +0000587
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000588 head, tail = path.split(file)
589 if head:
Gregory P. Smithb6e8c7e2010-02-27 07:22:22 +0000590 exec_func(file, *argrest)
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000591 return
Guido van Rossume7ba4952007-06-06 23:52:48 +0000592 last_exc = saved_exc = None
Guido van Rossum683c0fe2002-09-03 16:36:17 +0000593 saved_tb = None
Victor Stinnerb745a742010-05-18 17:17:23 +0000594 path_list = get_exec_path(env)
595 if name != 'nt':
596 file = fsencode(file)
597 path_list = map(fsencode, path_list)
598 for dir in path_list:
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000599 fullname = path.join(dir, file)
600 try:
Gregory P. Smithb6e8c7e2010-02-27 07:22:22 +0000601 exec_func(fullname, *argrest)
Guido van Rossumb940e112007-01-10 16:19:56 +0000602 except error as e:
Guido van Rossume7ba4952007-06-06 23:52:48 +0000603 last_exc = e
Guido van Rossum683c0fe2002-09-03 16:36:17 +0000604 tb = sys.exc_info()[2]
Christian Heimes45f9af32007-11-27 21:50:00 +0000605 if (e.errno != errno.ENOENT and e.errno != errno.ENOTDIR
Guido van Rossum683c0fe2002-09-03 16:36:17 +0000606 and saved_exc is None):
607 saved_exc = e
608 saved_tb = tb
609 if saved_exc:
Benjamin Peterson4b068192009-02-20 03:19:25 +0000610 raise saved_exc.with_traceback(saved_tb)
611 raise last_exc.with_traceback(tb)
Guido van Rossumd74fb6b2001-03-02 06:43:49 +0000612
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000613
Gregory P. Smithb6e8c7e2010-02-27 07:22:22 +0000614def get_exec_path(env=None):
615 """Returns the sequence of directories that will be searched for the
616 named executable (similar to a shell) when launching a process.
617
618 *env* must be an environment variable dict or None. If *env* is None,
619 os.environ will be used.
620 """
Victor Stinner273b7662010-11-06 12:59:33 +0000621 # Use a local import instead of a global import to limit the number of
622 # modules loaded at startup: the os module is always loaded at startup by
623 # Python. It may also avoid a bootstrap issue.
Victor Stinner6f35eda2010-10-29 00:38:58 +0000624 import warnings
625
Gregory P. Smithb6e8c7e2010-02-27 07:22:22 +0000626 if env is None:
627 env = environ
Victor Stinnerb745a742010-05-18 17:17:23 +0000628
Victor Stinnerbb4f2182010-11-07 15:43:39 +0000629 # {b'PATH': ...}.get('PATH') and {'PATH': ...}.get(b'PATH') emit a
630 # BytesWarning when using python -b or python -bb: ignore the warning
Victor Stinner273b7662010-11-06 12:59:33 +0000631 with warnings.catch_warnings():
632 warnings.simplefilter("ignore", BytesWarning)
Victor Stinnerb745a742010-05-18 17:17:23 +0000633
Victor Stinnerb745a742010-05-18 17:17:23 +0000634 try:
Victor Stinner273b7662010-11-06 12:59:33 +0000635 path_list = env.get('PATH')
636 except TypeError:
637 path_list = None
Victor Stinnerb745a742010-05-18 17:17:23 +0000638
Victor Stinner273b7662010-11-06 12:59:33 +0000639 if supports_bytes_environ:
640 try:
641 path_listb = env[b'PATH']
642 except (KeyError, TypeError):
643 pass
644 else:
645 if path_list is not None:
646 raise ValueError(
647 "env cannot contain 'PATH' and b'PATH' keys")
648 path_list = path_listb
649
650 if path_list is not None and isinstance(path_list, bytes):
651 path_list = fsdecode(path_list)
Victor Stinnerb745a742010-05-18 17:17:23 +0000652
653 if path_list is None:
654 path_list = defpath
655 return path_list.split(pathsep)
Gregory P. Smithb6e8c7e2010-02-27 07:22:22 +0000656
657
Skip Montanaro289bc052007-08-17 02:30:27 +0000658# Change environ to automatically call putenv(), unsetenv if they exist.
Raymond Hettinger158c9c22011-02-22 00:41:50 +0000659from collections.abc import MutableMapping
Skip Montanaro289bc052007-08-17 02:30:27 +0000660
661class _Environ(MutableMapping):
Victor Stinner84ae1182010-05-06 22:05:07 +0000662 def __init__(self, data, encodekey, decodekey, encodevalue, decodevalue, putenv, unsetenv):
663 self.encodekey = encodekey
664 self.decodekey = decodekey
665 self.encodevalue = encodevalue
666 self.decodevalue = decodevalue
Skip Montanaro289bc052007-08-17 02:30:27 +0000667 self.putenv = putenv
668 self.unsetenv = unsetenv
Victor Stinner3d75d0c2010-09-10 22:18:16 +0000669 self._data = data
Ezio Melotti19e4acf2010-02-22 15:59:01 +0000670
Skip Montanaro289bc052007-08-17 02:30:27 +0000671 def __getitem__(self, key):
Victor Stinner6d101392013-04-14 16:35:04 +0200672 try:
673 value = self._data[self.encodekey(key)]
674 except KeyError:
675 # raise KeyError with the original key value
Victor Stinner0c2dd0c2013-08-23 19:19:15 +0200676 raise KeyError(key) from None
Victor Stinner84ae1182010-05-06 22:05:07 +0000677 return self.decodevalue(value)
Ezio Melotti19e4acf2010-02-22 15:59:01 +0000678
Skip Montanaro289bc052007-08-17 02:30:27 +0000679 def __setitem__(self, key, value):
Victor Stinner84ae1182010-05-06 22:05:07 +0000680 key = self.encodekey(key)
681 value = self.encodevalue(value)
Skip Montanaro289bc052007-08-17 02:30:27 +0000682 self.putenv(key, value)
Victor Stinner3d75d0c2010-09-10 22:18:16 +0000683 self._data[key] = value
Ezio Melotti19e4acf2010-02-22 15:59:01 +0000684
Skip Montanaro289bc052007-08-17 02:30:27 +0000685 def __delitem__(self, key):
Victor Stinner6d101392013-04-14 16:35:04 +0200686 encodedkey = self.encodekey(key)
687 self.unsetenv(encodedkey)
688 try:
689 del self._data[encodedkey]
690 except KeyError:
691 # raise KeyError with the original key value
Victor Stinner0c2dd0c2013-08-23 19:19:15 +0200692 raise KeyError(key) from None
Ezio Melotti19e4acf2010-02-22 15:59:01 +0000693
Skip Montanaro289bc052007-08-17 02:30:27 +0000694 def __iter__(self):
Victor Stinner3d75d0c2010-09-10 22:18:16 +0000695 for key in self._data:
Victor Stinner84ae1182010-05-06 22:05:07 +0000696 yield self.decodekey(key)
Ezio Melotti19e4acf2010-02-22 15:59:01 +0000697
Skip Montanaro289bc052007-08-17 02:30:27 +0000698 def __len__(self):
Victor Stinner3d75d0c2010-09-10 22:18:16 +0000699 return len(self._data)
Ezio Melotti19e4acf2010-02-22 15:59:01 +0000700
701 def __repr__(self):
Victor Stinnerbed71172010-07-28 21:25:42 +0000702 return 'environ({{{}}})'.format(', '.join(
Victor Stinnerd73c1a32010-07-28 21:23:23 +0000703 ('{!r}: {!r}'.format(self.decodekey(key), self.decodevalue(value))
Victor Stinner3d75d0c2010-09-10 22:18:16 +0000704 for key, value in self._data.items())))
Ezio Melotti19e4acf2010-02-22 15:59:01 +0000705
Skip Montanaro289bc052007-08-17 02:30:27 +0000706 def copy(self):
707 return dict(self)
Ezio Melotti19e4acf2010-02-22 15:59:01 +0000708
Skip Montanaro289bc052007-08-17 02:30:27 +0000709 def setdefault(self, key, value):
710 if key not in self:
711 self[key] = value
712 return self[key]
713
714try:
715 _putenv = putenv
716except NameError:
717 _putenv = lambda key, value: None
Martin v. Löwisa90f4382001-03-07 09:05:45 +0000718else:
Skip Montanaro289bc052007-08-17 02:30:27 +0000719 __all__.append("putenv")
Guido van Rossum3b8e20d1996-07-24 00:55:17 +0000720
Skip Montanaro289bc052007-08-17 02:30:27 +0000721try:
722 _unsetenv = unsetenv
723except NameError:
724 _unsetenv = lambda key: _putenv(key, "")
725else:
726 __all__.append("unsetenv")
Guido van Rossumc524d952001-10-19 01:31:59 +0000727
Victor Stinner84ae1182010-05-06 22:05:07 +0000728def _createenviron():
729 if name in ('os2', 'nt'):
730 # Where Env Var Names Must Be UPPERCASE
731 def check_str(value):
732 if not isinstance(value, str):
733 raise TypeError("str expected, not %s" % type(value).__name__)
734 return value
735 encode = check_str
736 decode = str
737 def encodekey(key):
738 return encode(key).upper()
739 data = {}
740 for key, value in environ.items():
741 data[encodekey(key)] = value
742 else:
743 # Where Env Var Names Can Be Mixed Case
Victor Stinnerdf6d6cb2010-10-24 20:32:26 +0000744 encoding = sys.getfilesystemencoding()
Victor Stinner84ae1182010-05-06 22:05:07 +0000745 def encode(value):
746 if not isinstance(value, str):
747 raise TypeError("str expected, not %s" % type(value).__name__)
Victor Stinnerdf6d6cb2010-10-24 20:32:26 +0000748 return value.encode(encoding, 'surrogateescape')
Victor Stinner84ae1182010-05-06 22:05:07 +0000749 def decode(value):
Victor Stinnerdf6d6cb2010-10-24 20:32:26 +0000750 return value.decode(encoding, 'surrogateescape')
Victor Stinner84ae1182010-05-06 22:05:07 +0000751 encodekey = encode
752 data = environ
753 return _Environ(data,
754 encodekey, decode,
755 encode, decode,
756 _putenv, _unsetenv)
Guido van Rossumc524d952001-10-19 01:31:59 +0000757
Victor Stinner84ae1182010-05-06 22:05:07 +0000758# unicode environ
759environ = _createenviron()
760del _createenviron
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000761
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000762
Jack Jansenb11ce9b2003-01-08 16:33:40 +0000763def getenv(key, default=None):
Tim Peters2c60f7a2003-01-29 03:49:43 +0000764 """Get an environment variable, return None if it doesn't exist.
Victor Stinner84ae1182010-05-06 22:05:07 +0000765 The optional second argument can specify an alternate default.
766 key, default and the result are str."""
Tim Peters2c60f7a2003-01-29 03:49:43 +0000767 return environ.get(key, default)
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000768
Victor Stinnerb745a742010-05-18 17:17:23 +0000769supports_bytes_environ = name not in ('os2', 'nt')
770__all__.extend(("getenv", "supports_bytes_environ"))
771
772if supports_bytes_environ:
Victor Stinner84ae1182010-05-06 22:05:07 +0000773 def _check_bytes(value):
774 if not isinstance(value, bytes):
775 raise TypeError("bytes expected, not %s" % type(value).__name__)
776 return value
777
778 # bytes environ
Victor Stinner3d75d0c2010-09-10 22:18:16 +0000779 environb = _Environ(environ._data,
Victor Stinner84ae1182010-05-06 22:05:07 +0000780 _check_bytes, bytes,
781 _check_bytes, bytes,
782 _putenv, _unsetenv)
783 del _check_bytes
784
785 def getenvb(key, default=None):
786 """Get an environment variable, return None if it doesn't exist.
787 The optional second argument can specify an alternate default.
788 key, default and the result are bytes."""
789 return environb.get(key, default)
Victor Stinner70120e22010-07-29 17:19:38 +0000790
791 __all__.extend(("environb", "getenvb"))
Victor Stinner84ae1182010-05-06 22:05:07 +0000792
Victor Stinnerdf6d6cb2010-10-24 20:32:26 +0000793def _fscodec():
794 encoding = sys.getfilesystemencoding()
795 if encoding == 'mbcs':
Victor Stinnere882aac2010-10-24 21:12:26 +0000796 errors = 'strict'
Victor Stinner313a1202010-06-11 23:56:51 +0000797 else:
Victor Stinnerdf6d6cb2010-10-24 20:32:26 +0000798 errors = 'surrogateescape'
Victor Stinnere8d51452010-08-19 01:05:19 +0000799
Victor Stinnerdf6d6cb2010-10-24 20:32:26 +0000800 def fsencode(filename):
801 """
802 Encode filename to the filesystem encoding with 'surrogateescape' error
803 handler, return bytes unchanged. On Windows, use 'strict' error handler if
804 the file system encoding is 'mbcs' (which is the default encoding).
805 """
806 if isinstance(filename, bytes):
807 return filename
808 elif isinstance(filename, str):
809 return filename.encode(encoding, errors)
Victor Stinnere8d51452010-08-19 01:05:19 +0000810 else:
Victor Stinnerdf6d6cb2010-10-24 20:32:26 +0000811 raise TypeError("expect bytes or str, not %s" % type(filename).__name__)
812
813 def fsdecode(filename):
814 """
815 Decode filename from the filesystem encoding with 'surrogateescape' error
816 handler, return str unchanged. On Windows, use 'strict' error handler if
817 the file system encoding is 'mbcs' (which is the default encoding).
818 """
819 if isinstance(filename, str):
820 return filename
821 elif isinstance(filename, bytes):
822 return filename.decode(encoding, errors)
823 else:
824 raise TypeError("expect bytes or str, not %s" % type(filename).__name__)
825
826 return fsencode, fsdecode
827
828fsencode, fsdecode = _fscodec()
829del _fscodec
Victor Stinner449c4662010-05-08 11:10:09 +0000830
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000831# Supply spawn*() (probably only for Unix)
832if _exists("fork") and not _exists("spawnv") and _exists("execv"):
833
834 P_WAIT = 0
835 P_NOWAIT = P_NOWAITO = 1
836
Petri Lehtinen3bc37f22012-05-23 21:36:16 +0300837 __all__.extend(["P_WAIT", "P_NOWAIT", "P_NOWAITO"])
838
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000839 # XXX Should we support P_DETACH? I suppose it could fork()**2
840 # and close the std I/O streams. Also, P_OVERLAY is the same
841 # as execv*()?
842
843 def _spawnvef(mode, file, args, env, func):
844 # Internal helper; func is the exec*() function to use
845 pid = fork()
846 if not pid:
847 # Child
848 try:
849 if env is None:
850 func(file, args)
851 else:
852 func(file, args, env)
853 except:
854 _exit(127)
855 else:
856 # Parent
857 if mode == P_NOWAIT:
858 return pid # Caller is responsible for waiting!
859 while 1:
860 wpid, sts = waitpid(pid, 0)
861 if WIFSTOPPED(sts):
862 continue
863 elif WIFSIGNALED(sts):
864 return -WTERMSIG(sts)
865 elif WIFEXITED(sts):
866 return WEXITSTATUS(sts)
867 else:
Collin Winter828f04a2007-08-31 00:04:24 +0000868 raise error("Not stopped, signaled or exited???")
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000869
870 def spawnv(mode, file, args):
Guido van Rossume0cd2912000-04-21 18:35:36 +0000871 """spawnv(mode, file, args) -> integer
872
873Execute file with arguments from args in a subprocess.
874If mode == P_NOWAIT return the pid of the process.
875If mode == P_WAIT return the process's exit code if it exits normally;
Tim Peters2344fae2001-01-15 00:50:52 +0000876otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000877 return _spawnvef(mode, file, args, None, execv)
878
879 def spawnve(mode, file, args, env):
Guido van Rossume0cd2912000-04-21 18:35:36 +0000880 """spawnve(mode, file, args, env) -> integer
881
882Execute file with arguments from args in a subprocess with the
883specified environment.
884If mode == P_NOWAIT return the pid of the process.
885If mode == P_WAIT return the process's exit code if it exits normally;
886otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000887 return _spawnvef(mode, file, args, env, execve)
888
Guido van Rossumdd7cbbf1999-11-02 20:44:07 +0000889 # Note: spawnvp[e] is't currently supported on Windows
890
891 def spawnvp(mode, file, args):
Guido van Rossume0cd2912000-04-21 18:35:36 +0000892 """spawnvp(mode, file, args) -> integer
893
894Execute file (which is looked for along $PATH) with arguments from
895args in a subprocess.
896If mode == P_NOWAIT return the pid of the process.
897If mode == P_WAIT return the process's exit code if it exits normally;
898otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossumdd7cbbf1999-11-02 20:44:07 +0000899 return _spawnvef(mode, file, args, None, execvp)
900
901 def spawnvpe(mode, file, args, env):
Guido van Rossume0cd2912000-04-21 18:35:36 +0000902 """spawnvpe(mode, file, args, env) -> integer
903
904Execute file (which is looked for along $PATH) with arguments from
905args in a subprocess with the supplied environment.
906If mode == P_NOWAIT return the pid of the process.
907If mode == P_WAIT return the process's exit code if it exits normally;
908otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossumdd7cbbf1999-11-02 20:44:07 +0000909 return _spawnvef(mode, file, args, env, execvpe)
910
911if _exists("spawnv"):
912 # These aren't supplied by the basic Windows code
913 # but can be easily implemented in Python
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000914
915 def spawnl(mode, file, *args):
Guido van Rossume0cd2912000-04-21 18:35:36 +0000916 """spawnl(mode, file, *args) -> integer
917
918Execute file with arguments from args in a subprocess.
919If mode == P_NOWAIT return the pid of the process.
920If mode == P_WAIT return the process's exit code if it exits normally;
921otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000922 return spawnv(mode, file, args)
923
924 def spawnle(mode, file, *args):
Guido van Rossume0cd2912000-04-21 18:35:36 +0000925 """spawnle(mode, file, *args, env) -> integer
926
927Execute file with arguments from args in a subprocess with the
928supplied environment.
929If mode == P_NOWAIT return the pid of the process.
930If mode == P_WAIT return the process's exit code if it exits normally;
931otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000932 env = args[-1]
933 return spawnve(mode, file, args[:-1], env)
934
Andrew MacIntyre69e18c92004-04-04 07:11:43 +0000935
936 __all__.extend(["spawnv", "spawnve", "spawnl", "spawnle",])
937
938
Guido van Rossumdd7cbbf1999-11-02 20:44:07 +0000939if _exists("spawnvp"):
940 # At the moment, Windows doesn't implement spawnvp[e],
941 # so it won't have spawnlp[e] either.
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000942 def spawnlp(mode, file, *args):
Neal Norwitzb7f68102003-07-02 02:49:33 +0000943 """spawnlp(mode, file, *args) -> integer
Guido van Rossume0cd2912000-04-21 18:35:36 +0000944
945Execute file (which is looked for along $PATH) with arguments from
946args in a subprocess with the supplied environment.
947If mode == P_NOWAIT return the pid of the process.
948If mode == P_WAIT return the process's exit code if it exits normally;
949otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000950 return spawnvp(mode, file, args)
951
952 def spawnlpe(mode, file, *args):
Guido van Rossume0cd2912000-04-21 18:35:36 +0000953 """spawnlpe(mode, file, *args, env) -> integer
954
955Execute file (which is looked for along $PATH) with arguments from
956args in a subprocess with the supplied environment.
957If mode == P_NOWAIT return the pid of the process.
958If mode == P_WAIT return the process's exit code if it exits normally;
959otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000960 env = args[-1]
961 return spawnvpe(mode, file, args[:-1], env)
Guido van Rossume0cd2912000-04-21 18:35:36 +0000962
963
Andrew MacIntyre69e18c92004-04-04 07:11:43 +0000964 __all__.extend(["spawnvp", "spawnvpe", "spawnlp", "spawnlpe",])
Skip Montanaro269b83b2001-02-06 01:07:02 +0000965
Alexandre Vassalottif7fa63d2008-05-11 08:55:36 +0000966import copyreg as _copyreg
Michael W. Hudson0e025302002-03-06 17:11:18 +0000967
968def _make_stat_result(tup, dict):
969 return stat_result(tup, dict)
970
971def _pickle_stat_result(sr):
972 (type, args) = sr.__reduce__()
973 return (_make_stat_result, args)
974
Michael W. Hudsonce00b732002-03-15 10:18:58 +0000975try:
Alexandre Vassalottif7fa63d2008-05-11 08:55:36 +0000976 _copyreg.pickle(stat_result, _pickle_stat_result, _make_stat_result)
Michael W. Hudsonce00b732002-03-15 10:18:58 +0000977except NameError: # stat_result may not exist
978 pass
Michael W. Hudson0e025302002-03-06 17:11:18 +0000979
980def _make_statvfs_result(tup, dict):
981 return statvfs_result(tup, dict)
982
983def _pickle_statvfs_result(sr):
984 (type, args) = sr.__reduce__()
985 return (_make_statvfs_result, args)
986
Michael W. Hudsonce00b732002-03-15 10:18:58 +0000987try:
Alexandre Vassalottif7fa63d2008-05-11 08:55:36 +0000988 _copyreg.pickle(statvfs_result, _pickle_statvfs_result,
Michael W. Hudsonce00b732002-03-15 10:18:58 +0000989 _make_statvfs_result)
Michael W. Hudsone5363b72002-03-15 10:21:59 +0000990except NameError: # statvfs_result may not exist
Michael W. Hudsonce00b732002-03-15 10:18:58 +0000991 pass
Martin v. Löwisdc3883f2004-08-29 15:46:35 +0000992
Guido van Rossumc2f93dc2007-05-24 00:50:02 +0000993# Supply os.popen()
Antoine Pitrou877766d2011-03-19 17:00:37 +0100994def popen(cmd, mode="r", buffering=-1):
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000995 if not isinstance(cmd, str):
Guido van Rossumc2f93dc2007-05-24 00:50:02 +0000996 raise TypeError("invalid cmd type (%s, expected string)" % type(cmd))
997 if mode not in ("r", "w"):
998 raise ValueError("invalid mode %r" % mode)
Benjamin Petersonb29614e2012-10-09 11:16:03 -0400999 if buffering == 0 or buffering is None:
Antoine Pitrou877766d2011-03-19 17:00:37 +01001000 raise ValueError("popen() does not support unbuffered streams")
Guido van Rossumc2f93dc2007-05-24 00:50:02 +00001001 import subprocess, io
1002 if mode == "r":
1003 proc = subprocess.Popen(cmd,
1004 shell=True,
1005 stdout=subprocess.PIPE,
1006 bufsize=buffering)
1007 return _wrap_close(io.TextIOWrapper(proc.stdout), proc)
1008 else:
1009 proc = subprocess.Popen(cmd,
1010 shell=True,
1011 stdin=subprocess.PIPE,
1012 bufsize=buffering)
1013 return _wrap_close(io.TextIOWrapper(proc.stdin), proc)
1014
1015# Helper for popen() -- a proxy for a file whose close waits for the process
1016class _wrap_close:
1017 def __init__(self, stream, proc):
1018 self._stream = stream
1019 self._proc = proc
1020 def close(self):
1021 self._stream.close()
Amaury Forgeot d'Arc97e5f282009-07-11 09:35:13 +00001022 returncode = self._proc.wait()
1023 if returncode == 0:
1024 return None
1025 if name == 'nt':
1026 return returncode
1027 else:
1028 return returncode << 8 # Shift left to match old behavior
Antoine Pitrouac625352009-12-09 00:01:27 +00001029 def __enter__(self):
1030 return self
1031 def __exit__(self, *args):
1032 self.close()
Guido van Rossumc2f93dc2007-05-24 00:50:02 +00001033 def __getattr__(self, name):
1034 return getattr(self._stream, name)
Thomas Heller476157b2007-09-04 11:27:47 +00001035 def __iter__(self):
1036 return iter(self._stream)
Guido van Rossumc2f93dc2007-05-24 00:50:02 +00001037
Amaury Forgeot d'Arcbdbddf82008-08-01 00:06:49 +00001038# Supply os.fdopen()
1039def fdopen(fd, *args, **kwargs):
Guido van Rossumc2f93dc2007-05-24 00:50:02 +00001040 if not isinstance(fd, int):
1041 raise TypeError("invalid fd type (%s, expected integer)" % type(fd))
1042 import io
Amaury Forgeot d'Arcbdbddf82008-08-01 00:06:49 +00001043 return io.open(fd, *args, **kwargs)