blob: 6d4fb04108354c315c1b7535f2786363dedb2807 [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001:mod:`os` --- Miscellaneous operating system interfaces
2=======================================================
3
4.. module:: os
5 :synopsis: Miscellaneous operating system interfaces.
6
7
Christian Heimesa62da1d2008-01-12 19:39:10 +00008This module provides a portable way of using operating system dependent
9functionality. If you just want to read or write a file see :func:`open`, if
10you want to manipulate paths, see the :mod:`os.path` module, and if you want to
11read all the lines in all the files on the command line see the :mod:`fileinput`
12module. For creating temporary files and directories see the :mod:`tempfile`
13module, and for high-level file and directory handling see the :mod:`shutil`
14module.
Georg Brandl116aa622007-08-15 14:28:22 +000015
Benjamin Peterson1baf4652009-12-31 03:11:23 +000016Notes on the availability of these functions:
Georg Brandl116aa622007-08-15 14:28:22 +000017
Benjamin Peterson1baf4652009-12-31 03:11:23 +000018* The design of all built-in operating system dependent modules of Python is
19 such that as long as the same functionality is available, it uses the same
20 interface; for example, the function ``os.stat(path)`` returns stat
21 information about *path* in the same format (which happens to have originated
22 with the POSIX interface).
Georg Brandl116aa622007-08-15 14:28:22 +000023
Benjamin Peterson1baf4652009-12-31 03:11:23 +000024* Extensions peculiar to a particular operating system are also available
25 through the :mod:`os` module, but using them is of course a threat to
26 portability.
Georg Brandl116aa622007-08-15 14:28:22 +000027
Benjamin Peterson1baf4652009-12-31 03:11:23 +000028* All functions accepting path or file names accept both bytes and string
29 objects, and result in an object of the same type, if a path or file name is
30 returned.
Georg Brandl76e55382008-10-08 16:34:57 +000031
Benjamin Peterson1baf4652009-12-31 03:11:23 +000032* An "Availability: Unix" note means that this function is commonly found on
33 Unix systems. It does not make any claims about its existence on a specific
34 operating system.
35
36* If not separately noted, all functions that claim "Availability: Unix" are
37 supported on Mac OS X, which builds on a Unix core.
38
Benjamin Petersonf650e462010-05-06 23:03:05 +000039.. Availability notes get their own line and occur at the end of the function
40.. documentation.
41
Georg Brandlc575c902008-09-13 17:46:05 +000042.. note::
43
Christian Heimesa62da1d2008-01-12 19:39:10 +000044 All functions in this module raise :exc:`OSError` in the case of invalid or
45 inaccessible file names and paths, or other arguments that have the correct
46 type, but are not accepted by the operating system.
Georg Brandl116aa622007-08-15 14:28:22 +000047
Georg Brandl116aa622007-08-15 14:28:22 +000048.. exception:: error
49
Christian Heimesa62da1d2008-01-12 19:39:10 +000050 An alias for the built-in :exc:`OSError` exception.
Georg Brandl116aa622007-08-15 14:28:22 +000051
52
53.. data:: name
54
Benjamin Peterson1baf4652009-12-31 03:11:23 +000055 The name of the operating system dependent module imported. The following
56 names have currently been registered: ``'posix'``, ``'nt'``, ``'mac'``,
57 ``'os2'``, ``'ce'``, ``'java'``.
Georg Brandl116aa622007-08-15 14:28:22 +000058
Antoine Pitroua83cdaa2011-07-09 15:54:23 +020059 .. seealso::
60 :attr:`sys.platform` has a finer granularity. :func:`os.uname` gives
61 system-dependent version information.
62
63 The :mod:`platform` module provides detailed checks for the
64 system's identity.
65
Georg Brandl116aa622007-08-15 14:28:22 +000066
Martin v. Löwis011e8422009-05-05 04:43:17 +000067.. _os-filenames:
68
69File Names, Command Line Arguments, and Environment Variables
70-------------------------------------------------------------
71
Georg Brandl67b21b72010-08-17 15:07:14 +000072In Python, file names, command line arguments, and environment variables are
73represented using the string type. On some systems, decoding these strings to
74and from bytes is necessary before passing them to the operating system. Python
75uses the file system encoding to perform this conversion (see
76:func:`sys.getfilesystemencoding`).
Martin v. Löwis011e8422009-05-05 04:43:17 +000077
78.. versionchanged:: 3.1
Georg Brandl67b21b72010-08-17 15:07:14 +000079 On some systems, conversion using the file system encoding may fail. In this
80 case, Python uses the ``surrogateescape`` encoding error handler, which means
81 that undecodable bytes are replaced by a Unicode character U+DCxx on
82 decoding, and these are again translated to the original byte on encoding.
Martin v. Löwis011e8422009-05-05 04:43:17 +000083
84
Georg Brandl67b21b72010-08-17 15:07:14 +000085The file system encoding must guarantee to successfully decode all bytes
86below 128. If the file system encoding fails to provide this guarantee, API
87functions may raise UnicodeErrors.
Martin v. Löwis011e8422009-05-05 04:43:17 +000088
89
Georg Brandl116aa622007-08-15 14:28:22 +000090.. _os-procinfo:
91
92Process Parameters
93------------------
94
95These functions and data items provide information and operate on the current
96process and user.
97
98
Georg Brandl8ccadaa2012-06-24 12:50:06 +020099.. function:: ctermid()
100
101 Return the filename corresponding to the controlling terminal of the process.
102
103 Availability: Unix.
104
105
Georg Brandl116aa622007-08-15 14:28:22 +0000106.. data:: environ
107
Chris Jerdonek11f3f172012-11-03 12:05:55 -0700108 A :term:`mapping` object representing the string environment. For example,
Georg Brandl116aa622007-08-15 14:28:22 +0000109 ``environ['HOME']`` is the pathname of your home directory (on some platforms),
110 and is equivalent to ``getenv("HOME")`` in C.
111
112 This mapping is captured the first time the :mod:`os` module is imported,
113 typically during Python startup as part of processing :file:`site.py`. Changes
114 to the environment made after this time are not reflected in ``os.environ``,
115 except for changes made by modifying ``os.environ`` directly.
116
117 If the platform supports the :func:`putenv` function, this mapping may be used
118 to modify the environment as well as query the environment. :func:`putenv` will
119 be called automatically when the mapping is modified.
120
Victor Stinner84ae1182010-05-06 22:05:07 +0000121 On Unix, keys and values use :func:`sys.getfilesystemencoding` and
122 ``'surrogateescape'`` error handler. Use :data:`environb` if you would like
123 to use a different encoding.
124
Georg Brandl116aa622007-08-15 14:28:22 +0000125 .. note::
126
127 Calling :func:`putenv` directly does not change ``os.environ``, so it's better
128 to modify ``os.environ``.
129
130 .. note::
131
Georg Brandlc575c902008-09-13 17:46:05 +0000132 On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
133 cause memory leaks. Refer to the system documentation for
Georg Brandl60203b42010-10-06 10:11:56 +0000134 :c:func:`putenv`.
Georg Brandl116aa622007-08-15 14:28:22 +0000135
136 If :func:`putenv` is not provided, a modified copy of this mapping may be
137 passed to the appropriate process-creation functions to cause child processes
138 to use a modified environment.
139
Georg Brandl9afde1c2007-11-01 20:32:30 +0000140 If the platform supports the :func:`unsetenv` function, you can delete items in
Georg Brandl116aa622007-08-15 14:28:22 +0000141 this mapping to unset environment variables. :func:`unsetenv` will be called
Georg Brandl9afde1c2007-11-01 20:32:30 +0000142 automatically when an item is deleted from ``os.environ``, and when
143 one of the :meth:`pop` or :meth:`clear` methods is called.
144
Georg Brandl116aa622007-08-15 14:28:22 +0000145
Victor Stinner84ae1182010-05-06 22:05:07 +0000146.. data:: environb
147
Chris Jerdonek11f3f172012-11-03 12:05:55 -0700148 Bytes version of :data:`environ`: a :term:`mapping` object representing the
Victor Stinner84ae1182010-05-06 22:05:07 +0000149 environment as byte strings. :data:`environ` and :data:`environb` are
150 synchronized (modify :data:`environb` updates :data:`environ`, and vice
151 versa).
152
Victor Stinnerb745a742010-05-18 17:17:23 +0000153 :data:`environb` is only available if :data:`supports_bytes_environ` is
154 True.
Victor Stinner84ae1182010-05-06 22:05:07 +0000155
Benjamin Peterson662c74f2010-05-06 22:09:03 +0000156 .. versionadded:: 3.2
157
Victor Stinner84ae1182010-05-06 22:05:07 +0000158
Georg Brandl116aa622007-08-15 14:28:22 +0000159.. function:: chdir(path)
160 fchdir(fd)
161 getcwd()
162 :noindex:
163
164 These functions are described in :ref:`os-file-dir`.
165
166
Victor Stinnere8d51452010-08-19 01:05:19 +0000167.. function:: fsencode(filename)
Victor Stinner449c4662010-05-08 11:10:09 +0000168
Victor Stinnere8d51452010-08-19 01:05:19 +0000169 Encode *filename* to the filesystem encoding with ``'surrogateescape'``
Victor Stinner62165d62010-10-09 10:34:37 +0000170 error handler, or ``'strict'`` on Windows; return :class:`bytes` unchanged.
Victor Stinnere8d51452010-08-19 01:05:19 +0000171
Antoine Pitroua305ca72010-09-25 22:12:00 +0000172 :func:`fsdecode` is the reverse function.
Victor Stinnere8d51452010-08-19 01:05:19 +0000173
174 .. versionadded:: 3.2
175
176
177.. function:: fsdecode(filename)
178
179 Decode *filename* from the filesystem encoding with ``'surrogateescape'``
Victor Stinner62165d62010-10-09 10:34:37 +0000180 error handler, or ``'strict'`` on Windows; return :class:`str` unchanged.
Victor Stinnere8d51452010-08-19 01:05:19 +0000181
182 :func:`fsencode` is the reverse function.
Victor Stinner449c4662010-05-08 11:10:09 +0000183
184 .. versionadded:: 3.2
185
186
Georg Brandl8ccadaa2012-06-24 12:50:06 +0200187.. function:: getenv(key, default=None)
188
189 Return the value of the environment variable *key* if it exists, or
190 *default* if it doesn't. *key*, *default* and the result are str.
191
192 On Unix, keys and values are decoded with :func:`sys.getfilesystemencoding`
193 and ``'surrogateescape'`` error handler. Use :func:`os.getenvb` if you
194 would like to use a different encoding.
195
196 Availability: most flavors of Unix, Windows.
197
198
199.. function:: getenvb(key, default=None)
200
201 Return the value of the environment variable *key* if it exists, or
202 *default* if it doesn't. *key*, *default* and the result are bytes.
203
204 Availability: most flavors of Unix.
205
206 .. versionadded:: 3.2
207
208
Gregory P. Smithb6e8c7e2010-02-27 07:22:22 +0000209.. function:: get_exec_path(env=None)
210
211 Returns the list of directories that will be searched for a named
212 executable, similar to a shell, when launching a process.
213 *env*, when specified, should be an environment variable dictionary
214 to lookup the PATH in.
215 By default, when *env* is None, :data:`environ` is used.
216
217 .. versionadded:: 3.2
218
219
Georg Brandl116aa622007-08-15 14:28:22 +0000220.. function:: getegid()
221
222 Return the effective group id of the current process. This corresponds to the
Benjamin Petersonf650e462010-05-06 23:03:05 +0000223 "set id" bit on the file being executed in the current process.
224
225 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000226
227
228.. function:: geteuid()
229
230 .. index:: single: user; effective id
231
Benjamin Petersonf650e462010-05-06 23:03:05 +0000232 Return the current process's effective user id.
233
234 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000235
236
237.. function:: getgid()
238
239 .. index:: single: process; group
240
Benjamin Petersonf650e462010-05-06 23:03:05 +0000241 Return the real group id of the current process.
242
243 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000244
245
Ross Lagerwallb0ae53d2011-06-10 07:30:30 +0200246.. function:: getgrouplist(user, group)
247
248 Return list of group ids that *user* belongs to. If *group* is not in the
249 list, it is included; typically, *group* is specified as the group ID
250 field from the password record for *user*.
251
252 Availability: Unix.
253
254 .. versionadded:: 3.3
255
256
Georg Brandl116aa622007-08-15 14:28:22 +0000257.. function:: getgroups()
258
259 Return list of supplemental group ids associated with the current process.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000260
Georg Brandl116aa622007-08-15 14:28:22 +0000261 Availability: Unix.
262
Ned Deily2e209682012-04-30 11:14:02 -0700263 .. note:: On Mac OS X, :func:`getgroups` behavior differs somewhat from
264 other Unix platforms. If the Python interpreter was built with a
265 deployment target of :const:`10.5` or earlier, :func:`getgroups` returns
266 the list of effective group ids associated with the current user process;
267 this list is limited to a system-defined number of entries, typically 16,
268 and may be modified by calls to :func:`setgroups` if suitably privileged.
269 If built with a deployment target greater than :const:`10.5`,
270 :func:`getgroups` returns the current group access list for the user
271 associated with the effective user id of the process; the group access
272 list may change over the lifetime of the process, it is not affected by
273 calls to :func:`setgroups`, and its length is not limited to 16. The
274 deployment target value, :const:`MACOSX_DEPLOYMENT_TARGET`, can be
275 obtained with :func:`sysconfig.get_config_var`.
276
Georg Brandl116aa622007-08-15 14:28:22 +0000277
278.. function:: getlogin()
279
280 Return the name of the user logged in on the controlling terminal of the
Brian Curtine8e4b3b2010-09-23 20:04:14 +0000281 process. For most purposes, it is more useful to use the environment variables
282 :envvar:`LOGNAME` or :envvar:`USERNAME` to find out who the user is, or
Georg Brandl116aa622007-08-15 14:28:22 +0000283 ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the currently
Benjamin Petersonf650e462010-05-06 23:03:05 +0000284 effective user id.
285
Brian Curtine8e4b3b2010-09-23 20:04:14 +0000286 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000287
288
289.. function:: getpgid(pid)
290
291 Return the process group id of the process with process id *pid*. If *pid* is 0,
Benjamin Petersonf650e462010-05-06 23:03:05 +0000292 the process group id of the current process is returned.
Georg Brandl116aa622007-08-15 14:28:22 +0000293
Benjamin Petersonf650e462010-05-06 23:03:05 +0000294 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000295
296.. function:: getpgrp()
297
298 .. index:: single: process; group
299
Benjamin Petersonf650e462010-05-06 23:03:05 +0000300 Return the id of the current process group.
301
302 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000303
304
305.. function:: getpid()
306
307 .. index:: single: process; id
308
Benjamin Petersonf650e462010-05-06 23:03:05 +0000309 Return the current process id.
310
311 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000312
313
314.. function:: getppid()
315
316 .. index:: single: process; id of parent
317
Amaury Forgeot d'Arc4b6fdf32010-09-07 21:31:17 +0000318 Return the parent's process id. When the parent process has exited, on Unix
319 the id returned is the one of the init process (1), on Windows it is still
320 the same id, which may be already reused by another process.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000321
Georg Brandl8a5555f2012-06-24 13:29:09 +0200322 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000323
Amaury Forgeot d'Arc4b6fdf32010-09-07 21:31:17 +0000324 .. versionchanged:: 3.2
325 Added support for Windows.
Georg Brandl1b83a452009-11-28 11:12:26 +0000326
Georg Brandl8a5555f2012-06-24 13:29:09 +0200327
Giampaolo Rodolà18e8bcb2011-02-25 20:57:54 +0000328.. function:: getpriority(which, who)
329
330 .. index:: single: process; scheduling priority
331
Georg Brandl8ccadaa2012-06-24 12:50:06 +0200332 Get program scheduling priority. The value *which* is one of
Giampaolo Rodolà18e8bcb2011-02-25 20:57:54 +0000333 :const:`PRIO_PROCESS`, :const:`PRIO_PGRP`, or :const:`PRIO_USER`, and *who*
334 is interpreted relative to *which* (a process identifier for
335 :const:`PRIO_PROCESS`, process group identifier for :const:`PRIO_PGRP`, and a
Georg Brandl8ccadaa2012-06-24 12:50:06 +0200336 user ID for :const:`PRIO_USER`). A zero value for *who* denotes
Giampaolo Rodolà18e8bcb2011-02-25 20:57:54 +0000337 (respectively) the calling process, the process group of the calling process,
338 or the real user ID of the calling process.
339
Georg Brandl8ccadaa2012-06-24 12:50:06 +0200340 Availability: Unix.
Giampaolo Rodolà18e8bcb2011-02-25 20:57:54 +0000341
342 .. versionadded:: 3.3
343
Georg Brandl8ccadaa2012-06-24 12:50:06 +0200344
345.. data:: PRIO_PROCESS
346 PRIO_PGRP
347 PRIO_USER
348
349 Parameters for the :func:`getpriority` and :func:`setpriority` functions.
350
351 Availability: Unix.
352
353 .. versionadded:: 3.3
354
355
Gregory P. Smithcf02c6a2009-11-27 17:54:17 +0000356.. function:: getresuid()
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000357
358 Return a tuple (ruid, euid, suid) denoting the current process's
Benjamin Petersonf650e462010-05-06 23:03:05 +0000359 real, effective, and saved user ids.
360
361 Availability: Unix.
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000362
Georg Brandl1b83a452009-11-28 11:12:26 +0000363 .. versionadded:: 3.2
364
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000365
Gregory P. Smithcf02c6a2009-11-27 17:54:17 +0000366.. function:: getresgid()
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000367
368 Return a tuple (rgid, egid, sgid) denoting the current process's
Georg Brandla9b51d22010-09-05 17:07:12 +0000369 real, effective, and saved group ids.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000370
371 Availability: Unix.
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000372
Georg Brandl1b83a452009-11-28 11:12:26 +0000373 .. versionadded:: 3.2
374
Georg Brandl116aa622007-08-15 14:28:22 +0000375
376.. function:: getuid()
377
378 .. index:: single: user; id
379
Benjamin Petersonf650e462010-05-06 23:03:05 +0000380 Return the current process's user id.
381
382 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000383
384
Georg Brandl8ccadaa2012-06-24 12:50:06 +0200385.. function:: initgroups(username, gid)
Georg Brandl116aa622007-08-15 14:28:22 +0000386
Georg Brandl8ccadaa2012-06-24 12:50:06 +0200387 Call the system initgroups() to initialize the group access list with all of
388 the groups of which the specified username is a member, plus the specified
389 group id.
Giampaolo Rodolà18e8bcb2011-02-25 20:57:54 +0000390
391 Availability: Unix.
392
Georg Brandl8ccadaa2012-06-24 12:50:06 +0200393 .. versionadded:: 3.2
394
Georg Brandl116aa622007-08-15 14:28:22 +0000395
Georg Brandl18244152009-09-02 20:34:52 +0000396.. function:: putenv(key, value)
Georg Brandl116aa622007-08-15 14:28:22 +0000397
398 .. index:: single: environment variables; setting
399
Georg Brandl18244152009-09-02 20:34:52 +0000400 Set the environment variable named *key* to the string *value*. Such
Georg Brandl116aa622007-08-15 14:28:22 +0000401 changes to the environment affect subprocesses started with :func:`os.system`,
Benjamin Petersonf650e462010-05-06 23:03:05 +0000402 :func:`popen` or :func:`fork` and :func:`execv`.
403
404 Availability: most flavors of Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000405
406 .. note::
407
Georg Brandlc575c902008-09-13 17:46:05 +0000408 On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
409 cause memory leaks. Refer to the system documentation for putenv.
Georg Brandl116aa622007-08-15 14:28:22 +0000410
411 When :func:`putenv` is supported, assignments to items in ``os.environ`` are
412 automatically translated into corresponding calls to :func:`putenv`; however,
413 calls to :func:`putenv` don't update ``os.environ``, so it is actually
414 preferable to assign to items of ``os.environ``.
415
416
417.. function:: setegid(egid)
418
Benjamin Petersonf650e462010-05-06 23:03:05 +0000419 Set the current process's effective group id.
420
421 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000422
423
424.. function:: seteuid(euid)
425
Benjamin Petersonf650e462010-05-06 23:03:05 +0000426 Set the current process's effective user id.
427
428 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000429
430
431.. function:: setgid(gid)
432
Benjamin Petersonf650e462010-05-06 23:03:05 +0000433 Set the current process' group id.
434
435 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000436
437
438.. function:: setgroups(groups)
439
440 Set the list of supplemental group ids associated with the current process to
441 *groups*. *groups* must be a sequence, and each element must be an integer
Christian Heimesfaf2f632008-01-06 16:59:19 +0000442 identifying a group. This operation is typically available only to the superuser.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000443
Georg Brandl116aa622007-08-15 14:28:22 +0000444 Availability: Unix.
445
Ned Deily2e209682012-04-30 11:14:02 -0700446 .. note:: On Mac OS X, the length of *groups* may not exceed the
447 system-defined maximum number of effective group ids, typically 16.
448 See the documentation for :func:`getgroups` for cases where it may not
449 return the same group list set by calling setgroups().
Georg Brandl116aa622007-08-15 14:28:22 +0000450
451.. function:: setpgrp()
452
Andrew Svetlova2fe3342012-08-11 21:14:08 +0300453 Call the system call :c:func:`setpgrp` or ``setpgrp(0, 0)`` depending on
Georg Brandl116aa622007-08-15 14:28:22 +0000454 which version is implemented (if any). See the Unix manual for the semantics.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000455
Georg Brandl116aa622007-08-15 14:28:22 +0000456 Availability: Unix.
457
458
459.. function:: setpgid(pid, pgrp)
460
Georg Brandl60203b42010-10-06 10:11:56 +0000461 Call the system call :c:func:`setpgid` to set the process group id of the
Georg Brandl116aa622007-08-15 14:28:22 +0000462 process with id *pid* to the process group with id *pgrp*. See the Unix manual
Benjamin Petersonf650e462010-05-06 23:03:05 +0000463 for the semantics.
464
465 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000466
467
Giampaolo Rodolà18e8bcb2011-02-25 20:57:54 +0000468.. function:: setpriority(which, who, priority)
469
470 .. index:: single: process; scheduling priority
471
472 Set program scheduling priority. The value *which* is one of
473 :const:`PRIO_PROCESS`, :const:`PRIO_PGRP`, or :const:`PRIO_USER`, and *who*
474 is interpreted relative to *which* (a process identifier for
475 :const:`PRIO_PROCESS`, process group identifier for :const:`PRIO_PGRP`, and a
476 user ID for :const:`PRIO_USER`). A zero value for *who* denotes
477 (respectively) the calling process, the process group of the calling process,
478 or the real user ID of the calling process.
479 *priority* is a value in the range -20 to 19. The default priority is 0;
480 lower priorities cause more favorable scheduling.
481
482 Availability: Unix
483
484 .. versionadded:: 3.3
485
486
Georg Brandl116aa622007-08-15 14:28:22 +0000487.. function:: setregid(rgid, egid)
488
Benjamin Petersonf650e462010-05-06 23:03:05 +0000489 Set the current process's real and effective group ids.
490
491 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000492
Georg Brandl1b83a452009-11-28 11:12:26 +0000493
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000494.. function:: setresgid(rgid, egid, sgid)
495
496 Set the current process's real, effective, and saved group ids.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000497
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000498 Availability: Unix.
499
Georg Brandl1b83a452009-11-28 11:12:26 +0000500 .. versionadded:: 3.2
501
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000502
503.. function:: setresuid(ruid, euid, suid)
504
505 Set the current process's real, effective, and saved user ids.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000506
Georg Brandl6faee4e2010-09-21 14:48:28 +0000507 Availability: Unix.
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000508
Georg Brandl1b83a452009-11-28 11:12:26 +0000509 .. versionadded:: 3.2
510
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000511
512.. function:: setreuid(ruid, euid)
513
Benjamin Petersonf650e462010-05-06 23:03:05 +0000514 Set the current process's real and effective user ids.
515
516 Availability: Unix.
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000517
Georg Brandl116aa622007-08-15 14:28:22 +0000518
519.. function:: getsid(pid)
520
Georg Brandl60203b42010-10-06 10:11:56 +0000521 Call the system call :c:func:`getsid`. See the Unix manual for the semantics.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000522
Georg Brandl116aa622007-08-15 14:28:22 +0000523 Availability: Unix.
524
Georg Brandl116aa622007-08-15 14:28:22 +0000525
526.. function:: setsid()
527
Georg Brandl60203b42010-10-06 10:11:56 +0000528 Call the system call :c:func:`setsid`. See the Unix manual for the semantics.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000529
Georg Brandl116aa622007-08-15 14:28:22 +0000530 Availability: Unix.
531
532
533.. function:: setuid(uid)
534
535 .. index:: single: user; id, setting
536
Benjamin Petersonf650e462010-05-06 23:03:05 +0000537 Set the current process's user id.
538
539 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000540
Georg Brandl116aa622007-08-15 14:28:22 +0000541
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000542.. placed in this section since it relates to errno.... a little weak
Georg Brandl116aa622007-08-15 14:28:22 +0000543.. function:: strerror(code)
544
545 Return the error message corresponding to the error code in *code*.
Georg Brandl60203b42010-10-06 10:11:56 +0000546 On platforms where :c:func:`strerror` returns ``NULL`` when given an unknown
Benjamin Petersonf650e462010-05-06 23:03:05 +0000547 error number, :exc:`ValueError` is raised.
548
549 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000550
551
Victor Stinnerb745a742010-05-18 17:17:23 +0000552.. data:: supports_bytes_environ
553
554 True if the native OS type of the environment is bytes (eg. False on
555 Windows).
556
Victor Stinner8fddc9e2010-05-18 17:24:09 +0000557 .. versionadded:: 3.2
558
Victor Stinnerb745a742010-05-18 17:17:23 +0000559
Georg Brandl116aa622007-08-15 14:28:22 +0000560.. function:: umask(mask)
561
Benjamin Petersonf650e462010-05-06 23:03:05 +0000562 Set the current numeric umask and return the previous umask.
563
564 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000565
566
567.. function:: uname()
568
569 .. index::
570 single: gethostname() (in module socket)
571 single: gethostbyaddr() (in module socket)
572
Larry Hastings605a62d2012-06-24 04:33:36 -0700573 Returns information identifying the current operating system.
574 The return value is an object with five attributes:
575
576 * :attr:`sysname` - operating system name
577 * :attr:`nodename` - name of machine on network (implementation-defined)
578 * :attr:`release` - operating system release
579 * :attr:`version` - operating system version
580 * :attr:`machine` - hardware identifier
581
582 For backwards compatibility, this object is also iterable, behaving
583 like a five-tuple containing :attr:`sysname`, :attr:`nodename`,
584 :attr:`release`, :attr:`version`, and :attr:`machine`
585 in that order.
586
587 Some systems truncate :attr:`nodename` to 8 characters or to the
Georg Brandl116aa622007-08-15 14:28:22 +0000588 leading component; a better way to get the hostname is
589 :func:`socket.gethostname` or even
Benjamin Petersonf650e462010-05-06 23:03:05 +0000590 ``socket.gethostbyaddr(socket.gethostname())``.
591
592 Availability: recent flavors of Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000593
Larry Hastings605a62d2012-06-24 04:33:36 -0700594 .. versionchanged:: 3.3
595 Return type changed from a tuple to a tuple-like object
596 with named attributes.
597
Georg Brandl116aa622007-08-15 14:28:22 +0000598
Georg Brandl18244152009-09-02 20:34:52 +0000599.. function:: unsetenv(key)
Georg Brandl116aa622007-08-15 14:28:22 +0000600
601 .. index:: single: environment variables; deleting
602
Georg Brandl18244152009-09-02 20:34:52 +0000603 Unset (delete) the environment variable named *key*. Such changes to the
Georg Brandl116aa622007-08-15 14:28:22 +0000604 environment affect subprocesses started with :func:`os.system`, :func:`popen` or
Benjamin Petersonf650e462010-05-06 23:03:05 +0000605 :func:`fork` and :func:`execv`.
Georg Brandl116aa622007-08-15 14:28:22 +0000606
607 When :func:`unsetenv` is supported, deletion of items in ``os.environ`` is
608 automatically translated into a corresponding call to :func:`unsetenv`; however,
609 calls to :func:`unsetenv` don't update ``os.environ``, so it is actually
610 preferable to delete items of ``os.environ``.
611
Benjamin Petersonf650e462010-05-06 23:03:05 +0000612 Availability: most flavors of Unix, Windows.
613
Georg Brandl116aa622007-08-15 14:28:22 +0000614
615.. _os-newstreams:
616
617File Object Creation
618--------------------
619
Georg Brandla570e982012-06-24 13:26:22 +0200620This function creates new :term:`file objects <file object>`. (See also
Georg Brandlb2462e22012-06-24 13:24:56 +0200621:func:`~os.open` for opening file descriptors.)
Georg Brandl116aa622007-08-15 14:28:22 +0000622
623
Petri Lehtinen1a01ebc2012-05-24 21:44:07 +0300624.. function:: fdopen(fd, *args, **kwargs)
Georg Brandl116aa622007-08-15 14:28:22 +0000625
Georg Brandlb2462e22012-06-24 13:24:56 +0200626 Return an open file object connected to the file descriptor *fd*. This is an
627 alias of the :func:`open` built-in function and accepts the same arguments.
628 The only difference is that the first argument of :func:`fdopen` must always
629 be an integer.
Georg Brandl116aa622007-08-15 14:28:22 +0000630
Georg Brandl116aa622007-08-15 14:28:22 +0000631
Georg Brandl116aa622007-08-15 14:28:22 +0000632.. _os-fd-ops:
633
634File Descriptor Operations
635--------------------------
636
637These functions operate on I/O streams referenced using file descriptors.
638
639File descriptors are small integers corresponding to a file that has been opened
640by the current process. For example, standard input is usually file descriptor
6410, standard output is 1, and standard error is 2. Further files opened by a
642process will then be assigned 3, 4, 5, and so forth. The name "file descriptor"
643is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
644by file descriptors.
645
Benjamin Peterson08bf91c2010-04-11 16:12:57 +0000646The :meth:`~file.fileno` method can be used to obtain the file descriptor
Antoine Pitrou11cb9612010-09-15 11:11:28 +0000647associated with a :term:`file object` when required. Note that using the file
Benjamin Peterson08bf91c2010-04-11 16:12:57 +0000648descriptor directly will bypass the file object methods, ignoring aspects such
649as internal buffering of data.
Georg Brandl116aa622007-08-15 14:28:22 +0000650
Antoine Pitrouf65132d2011-02-25 23:25:17 +0000651
Georg Brandl116aa622007-08-15 14:28:22 +0000652.. function:: close(fd)
653
Benjamin Petersonf650e462010-05-06 23:03:05 +0000654 Close file descriptor *fd*.
655
656 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000657
658 .. note::
659
660 This function is intended for low-level I/O and must be applied to a file
Benjamin Petersonfa0d7032009-06-01 22:42:33 +0000661 descriptor as returned by :func:`os.open` or :func:`pipe`. To close a "file
Georg Brandl116aa622007-08-15 14:28:22 +0000662 object" returned by the built-in function :func:`open` or by :func:`popen` or
Benjamin Petersonfa0d7032009-06-01 22:42:33 +0000663 :func:`fdopen`, use its :meth:`~file.close` method.
Georg Brandl116aa622007-08-15 14:28:22 +0000664
665
Christian Heimesfdab48e2008-01-20 09:06:41 +0000666.. function:: closerange(fd_low, fd_high)
667
668 Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive),
Georg Brandlb1a1ac02012-06-24 11:54:07 +0200669 ignoring errors. Equivalent to (but much faster than)::
Christian Heimesfdab48e2008-01-20 09:06:41 +0000670
Georg Brandlc9a5a0e2009-09-01 07:34:27 +0000671 for fd in range(fd_low, fd_high):
Christian Heimesfdab48e2008-01-20 09:06:41 +0000672 try:
673 os.close(fd)
674 except OSError:
675 pass
676
Benjamin Petersonf650e462010-05-06 23:03:05 +0000677 Availability: Unix, Windows.
678
Christian Heimesfdab48e2008-01-20 09:06:41 +0000679
Georg Brandl81f11302007-12-21 08:45:42 +0000680.. function:: device_encoding(fd)
681
682 Return a string describing the encoding of the device associated with *fd*
683 if it is connected to a terminal; else return :const:`None`.
684
685
Georg Brandl116aa622007-08-15 14:28:22 +0000686.. function:: dup(fd)
687
Benjamin Petersonf650e462010-05-06 23:03:05 +0000688 Return a duplicate of file descriptor *fd*.
689
690 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000691
692
693.. function:: dup2(fd, fd2)
694
695 Duplicate file descriptor *fd* to *fd2*, closing the latter first if necessary.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000696
Georg Brandlc575c902008-09-13 17:46:05 +0000697 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000698
699
Christian Heimes4e30a842007-11-30 22:12:06 +0000700.. function:: fchmod(fd, mode)
701
Georg Brandlb9df00c2012-06-24 12:38:14 +0200702 Change the mode of the file given by *fd* to the numeric *mode*. See the
Georg Brandl4d399a42012-06-25 07:40:32 +0200703 docs for :func:`chmod` for possible values of *mode*. As of Python 3.3, this
Georg Brandlb9df00c2012-06-24 12:38:14 +0200704 is equivalent to ``os.chmod(fd, mode)``.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000705
706 Availability: Unix.
Christian Heimes4e30a842007-11-30 22:12:06 +0000707
708
709.. function:: fchown(fd, uid, gid)
710
711 Change the owner and group id of the file given by *fd* to the numeric *uid*
Georg Brandlb9df00c2012-06-24 12:38:14 +0200712 and *gid*. To leave one of the ids unchanged, set it to -1. See
Georg Brandl4d399a42012-06-25 07:40:32 +0200713 :func:`chown`. As of Python 3.3, this is equivalent to ``os.chown(fd, uid,
Georg Brandlb9df00c2012-06-24 12:38:14 +0200714 gid)``.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000715
Christian Heimes4e30a842007-11-30 22:12:06 +0000716 Availability: Unix.
717
718
Georg Brandl116aa622007-08-15 14:28:22 +0000719.. function:: fdatasync(fd)
720
721 Force write of file with filedescriptor *fd* to disk. Does not force update of
Benjamin Petersonf650e462010-05-06 23:03:05 +0000722 metadata.
723
724 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000725
Benjamin Petersonfa0d7032009-06-01 22:42:33 +0000726 .. note::
727 This function is not available on MacOS.
728
Georg Brandl116aa622007-08-15 14:28:22 +0000729
730.. function:: fpathconf(fd, name)
731
732 Return system configuration information relevant to an open file. *name*
733 specifies the configuration value to retrieve; it may be a string which is the
734 name of a defined system value; these names are specified in a number of
735 standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define
736 additional names as well. The names known to the host operating system are
737 given in the ``pathconf_names`` dictionary. For configuration variables not
738 included in that mapping, passing an integer for *name* is also accepted.
Georg Brandl116aa622007-08-15 14:28:22 +0000739
740 If *name* is a string and is not known, :exc:`ValueError` is raised. If a
741 specific value for *name* is not supported by the host system, even if it is
742 included in ``pathconf_names``, an :exc:`OSError` is raised with
743 :const:`errno.EINVAL` for the error number.
744
Georg Brandl4d399a42012-06-25 07:40:32 +0200745 As of Python 3.3, this is equivalent to ``os.pathconf(fd, name)``.
Georg Brandl306336b2012-06-24 12:55:33 +0200746
Benjamin Petersonf650e462010-05-06 23:03:05 +0000747 Availability: Unix.
748
Georg Brandl116aa622007-08-15 14:28:22 +0000749
Victor Stinner4195b5c2012-02-08 23:03:19 +0100750.. function:: fstat(fd)
Georg Brandl116aa622007-08-15 14:28:22 +0000751
Georg Brandl4d399a42012-06-25 07:40:32 +0200752 Return status for file descriptor *fd*, like :func:`~os.stat`. As of Python
Georg Brandlb9df00c2012-06-24 12:38:14 +0200753 3.3, this is equivalent to ``os.stat(fd)``.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000754
755 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000756
Georg Brandlb1a1ac02012-06-24 11:54:07 +0200757
Georg Brandl116aa622007-08-15 14:28:22 +0000758.. function:: fstatvfs(fd)
759
Georg Brandlb9df00c2012-06-24 12:38:14 +0200760 Return information about the filesystem containing the file associated with
Georg Brandl4d399a42012-06-25 07:40:32 +0200761 file descriptor *fd*, like :func:`statvfs`. As of Python 3.3, this is
Georg Brandlb9df00c2012-06-24 12:38:14 +0200762 equivalent to ``os.statvfs(fd)``.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000763
764 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000765
766
767.. function:: fsync(fd)
768
769 Force write of file with filedescriptor *fd* to disk. On Unix, this calls the
Georg Brandl60203b42010-10-06 10:11:56 +0000770 native :c:func:`fsync` function; on Windows, the MS :c:func:`_commit` function.
Georg Brandl116aa622007-08-15 14:28:22 +0000771
Antoine Pitrou11cb9612010-09-15 11:11:28 +0000772 If you're starting with a buffered Python :term:`file object` *f*, first do
773 ``f.flush()``, and then do ``os.fsync(f.fileno())``, to ensure that all internal
774 buffers associated with *f* are written to disk.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000775
Georg Brandl8a5555f2012-06-24 13:29:09 +0200776 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000777
778
779.. function:: ftruncate(fd, length)
780
Georg Brandl306336b2012-06-24 12:55:33 +0200781 Truncate the file corresponding to file descriptor *fd*, so that it is at
Georg Brandl4d399a42012-06-25 07:40:32 +0200782 most *length* bytes in size. As of Python 3.3, this is equivalent to
Georg Brandl306336b2012-06-24 12:55:33 +0200783 ``os.truncate(fd, length)``.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000784
785 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000786
787
788.. function:: isatty(fd)
789
790 Return ``True`` if the file descriptor *fd* is open and connected to a
Benjamin Petersonf650e462010-05-06 23:03:05 +0000791 tty(-like) device, else ``False``.
792
793 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000794
795
Ross Lagerwall7807c352011-03-17 20:20:30 +0200796.. function:: lockf(fd, cmd, len)
797
798 Apply, test or remove a POSIX lock on an open file descriptor.
799 *fd* is an open file descriptor.
800 *cmd* specifies the command to use - one of :data:`F_LOCK`, :data:`F_TLOCK`,
801 :data:`F_ULOCK` or :data:`F_TEST`.
802 *len* specifies the section of the file to lock.
803
804 Availability: Unix.
805
806 .. versionadded:: 3.3
807
808
809.. data:: F_LOCK
810 F_TLOCK
811 F_ULOCK
812 F_TEST
813
814 Flags that specify what action :func:`lockf` will take.
815
816 Availability: Unix.
817
818 .. versionadded:: 3.3
819
Georg Brandlf62445a2012-06-24 13:31:20 +0200820
Georg Brandl116aa622007-08-15 14:28:22 +0000821.. function:: lseek(fd, pos, how)
822
Christian Heimesfaf2f632008-01-06 16:59:19 +0000823 Set the current position of file descriptor *fd* to position *pos*, modified
824 by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the
825 beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the
826 current position; :const:`os.SEEK_END` or ``2`` to set it relative to the end of
Victor Stinnere83f8992011-12-17 23:15:09 +0100827 the file. Return the new cursor position in bytes, starting from the beginning.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000828
829 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000830
831
Georg Brandl8569e582010-05-19 20:57:08 +0000832.. data:: SEEK_SET
833 SEEK_CUR
834 SEEK_END
835
836 Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
Georg Brandl8a5555f2012-06-24 13:29:09 +0200837 respectively.
838
839 Availability: Unix, Windows.
Georg Brandl8569e582010-05-19 20:57:08 +0000840
Jesus Cea94363612012-06-22 18:32:07 +0200841 .. versionadded:: 3.3
842 Some operating systems could support additional values, like
843 :data:`os.SEEK_HOLE` or :data:`os.SEEK_DATA`.
844
Georg Brandl8569e582010-05-19 20:57:08 +0000845
Larry Hastings9cf065c2012-06-22 16:30:09 -0700846.. function:: open(file, flags, mode=0o777, *, dir_fd=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000847
Georg Brandlf4a41232008-05-26 17:55:52 +0000848 Open the file *file* and set various flags according to *flags* and possibly
Larry Hastings9cf065c2012-06-22 16:30:09 -0700849 its mode according to *mode*. When computing *mode*, the current umask value
850 is first masked out. Return the file descriptor for the newly opened file.
Georg Brandl116aa622007-08-15 14:28:22 +0000851
852 For a description of the flag and mode values, see the C run-time documentation;
853 flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
Georg Brandl8569e582010-05-19 20:57:08 +0000854 this module too (see :ref:`open-constants`). In particular, on Windows adding
855 :const:`O_BINARY` is needed to open files in binary mode.
Georg Brandl116aa622007-08-15 14:28:22 +0000856
Georg Brandl50c40002012-06-24 11:45:20 +0200857 This function can support :ref:`paths relative to directory descriptors
858 <dir_fd>`.
Larry Hastings9cf065c2012-06-22 16:30:09 -0700859
Benjamin Petersonf650e462010-05-06 23:03:05 +0000860 Availability: Unix, Windows.
861
Georg Brandl116aa622007-08-15 14:28:22 +0000862 .. note::
863
Georg Brandl502d9a52009-07-26 15:02:41 +0000864 This function is intended for low-level I/O. For normal usage, use the
Antoine Pitrou11cb9612010-09-15 11:11:28 +0000865 built-in function :func:`open`, which returns a :term:`file object` with
Jeroen Ruigrok van der Werven9c558bcf2010-07-13 14:47:01 +0000866 :meth:`~file.read` and :meth:`~file.write` methods (and many more). To
Antoine Pitrou11cb9612010-09-15 11:11:28 +0000867 wrap a file descriptor in a file object, use :func:`fdopen`.
Georg Brandl116aa622007-08-15 14:28:22 +0000868
Antoine Pitrouf65132d2011-02-25 23:25:17 +0000869 .. versionadded:: 3.3
Larry Hastings9cf065c2012-06-22 16:30:09 -0700870 The *dir_fd* argument.
Antoine Pitrouf65132d2011-02-25 23:25:17 +0000871
872
Georg Brandl116aa622007-08-15 14:28:22 +0000873.. function:: openpty()
874
875 .. index:: module: pty
876
877 Open a new pseudo-terminal pair. Return a pair of file descriptors ``(master,
878 slave)`` for the pty and the tty, respectively. For a (slightly) more portable
Benjamin Petersonf650e462010-05-06 23:03:05 +0000879 approach, use the :mod:`pty` module.
880
881 Availability: some flavors of Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000882
883
884.. function:: pipe()
885
886 Create a pipe. Return a pair of file descriptors ``(r, w)`` usable for reading
Benjamin Petersonf650e462010-05-06 23:03:05 +0000887 and writing, respectively.
888
889 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000890
891
Charles-François Natali368f34b2011-06-06 19:49:47 +0200892.. function:: pipe2(flags)
Charles-François Natalidaafdd52011-05-29 20:07:40 +0200893
894 Create a pipe with *flags* set atomically.
Charles-François Natali368f34b2011-06-06 19:49:47 +0200895 *flags* can be constructed by ORing together one or more of these values:
896 :data:`O_NONBLOCK`, :data:`O_CLOEXEC`.
Charles-François Natalidaafdd52011-05-29 20:07:40 +0200897 Return a pair of file descriptors ``(r, w)`` usable for reading and writing,
898 respectively.
899
900 Availability: some flavors of Unix.
901
902 .. versionadded:: 3.3
903
904
Ross Lagerwall7807c352011-03-17 20:20:30 +0200905.. function:: posix_fallocate(fd, offset, len)
906
907 Ensures that enough disk space is allocated for the file specified by *fd*
908 starting from *offset* and continuing for *len* bytes.
909
910 Availability: Unix.
911
912 .. versionadded:: 3.3
913
914
915.. function:: posix_fadvise(fd, offset, len, advice)
916
917 Announces an intention to access data in a specific pattern thus allowing
918 the kernel to make optimizations.
919 The advice applies to the region of the file specified by *fd* starting at
920 *offset* and continuing for *len* bytes.
921 *advice* is one of :data:`POSIX_FADV_NORMAL`, :data:`POSIX_FADV_SEQUENTIAL`,
922 :data:`POSIX_FADV_RANDOM`, :data:`POSIX_FADV_NOREUSE`,
923 :data:`POSIX_FADV_WILLNEED` or :data:`POSIX_FADV_DONTNEED`.
924
925 Availability: Unix.
926
927 .. versionadded:: 3.3
928
929
930.. data:: POSIX_FADV_NORMAL
931 POSIX_FADV_SEQUENTIAL
932 POSIX_FADV_RANDOM
933 POSIX_FADV_NOREUSE
934 POSIX_FADV_WILLNEED
935 POSIX_FADV_DONTNEED
936
937 Flags that can be used in *advice* in :func:`posix_fadvise` that specify
938 the access pattern that is likely to be used.
939
940 Availability: Unix.
941
942 .. versionadded:: 3.3
943
944
945.. function:: pread(fd, buffersize, offset)
946
947 Read from a file descriptor, *fd*, at a position of *offset*. It will read up
948 to *buffersize* number of bytes. The file offset remains unchanged.
949
950 Availability: Unix.
951
952 .. versionadded:: 3.3
953
954
955.. function:: pwrite(fd, string, offset)
956
957 Write *string* to a file descriptor, *fd*, from *offset*, leaving the file
958 offset unchanged.
959
960 Availability: Unix.
961
962 .. versionadded:: 3.3
963
964
Georg Brandl116aa622007-08-15 14:28:22 +0000965.. function:: read(fd, n)
966
Georg Brandlb90be692009-07-29 16:14:16 +0000967 Read at most *n* bytes from file descriptor *fd*. Return a bytestring containing the
Georg Brandl116aa622007-08-15 14:28:22 +0000968 bytes read. If the end of the file referred to by *fd* has been reached, an
Benjamin Petersonf650e462010-05-06 23:03:05 +0000969 empty bytes object is returned.
970
971 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000972
973 .. note::
974
975 This function is intended for low-level I/O and must be applied to a file
Georg Brandlb2462e22012-06-24 13:24:56 +0200976 descriptor as returned by :func:`os.open` or :func:`pipe`. To read a
977 "file object" returned by the built-in function :func:`open` or by
978 :func:`popen` or :func:`fdopen`, or :data:`sys.stdin`, use its
979 :meth:`~file.read` or :meth:`~file.readline` methods.
Georg Brandl116aa622007-08-15 14:28:22 +0000980
981
Giampaolo Rodolàc9c2c8b2011-02-25 14:39:16 +0000982.. function:: sendfile(out, in, offset, nbytes)
983 sendfile(out, in, offset, nbytes, headers=None, trailers=None, flags=0)
984
985 Copy *nbytes* bytes from file descriptor *in* to file descriptor *out*
986 starting at *offset*.
987 Return the number of bytes sent. When EOF is reached return 0.
988
989 The first function notation is supported by all platforms that define
990 :func:`sendfile`.
991
992 On Linux, if *offset* is given as ``None``, the bytes are read from the
993 current position of *in* and the position of *in* is updated.
994
995 The second case may be used on Mac OS X and FreeBSD where *headers* and
996 *trailers* are arbitrary sequences of buffers that are written before and
997 after the data from *in* is written. It returns the same as the first case.
998
999 On Mac OS X and FreeBSD, a value of 0 for *nbytes* specifies to send until
1000 the end of *in* is reached.
1001
Charles-Francois Natalia771a1b2013-05-01 15:12:20 +02001002 All platforms support sockets as *out* file descriptor, and some platforms
1003 allow other types (e.g. regular file, pipe) as well.
Giampaolo Rodolàc9c2c8b2011-02-25 14:39:16 +00001004
1005 Availability: Unix.
1006
1007 .. versionadded:: 3.3
1008
1009
1010.. data:: SF_NODISKIO
1011 SF_MNOWAIT
1012 SF_SYNC
1013
1014 Parameters to the :func:`sendfile` function, if the implementation supports
1015 them.
1016
1017 Availability: Unix.
1018
1019 .. versionadded:: 3.3
1020
1021
Ross Lagerwall7807c352011-03-17 20:20:30 +02001022.. function:: readv(fd, buffers)
1023
1024 Read from a file descriptor into a number of writable buffers. *buffers* is
1025 an arbitrary sequence of writable buffers. Returns the total number of bytes
1026 read.
1027
1028 Availability: Unix.
1029
1030 .. versionadded:: 3.3
1031
1032
Georg Brandl116aa622007-08-15 14:28:22 +00001033.. function:: tcgetpgrp(fd)
1034
1035 Return the process group associated with the terminal given by *fd* (an open
Benjamin Petersonf650e462010-05-06 23:03:05 +00001036 file descriptor as returned by :func:`os.open`).
1037
1038 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001039
1040
1041.. function:: tcsetpgrp(fd, pg)
1042
1043 Set the process group associated with the terminal given by *fd* (an open file
Benjamin Petersonf650e462010-05-06 23:03:05 +00001044 descriptor as returned by :func:`os.open`) to *pg*.
1045
1046 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001047
1048
1049.. function:: ttyname(fd)
1050
1051 Return a string which specifies the terminal device associated with
Georg Brandl9afde1c2007-11-01 20:32:30 +00001052 file descriptor *fd*. If *fd* is not associated with a terminal device, an
Benjamin Petersonf650e462010-05-06 23:03:05 +00001053 exception is raised.
1054
1055 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001056
1057
1058.. function:: write(fd, str)
1059
Georg Brandlb90be692009-07-29 16:14:16 +00001060 Write the bytestring in *str* to file descriptor *fd*. Return the number of
Benjamin Petersonf650e462010-05-06 23:03:05 +00001061 bytes actually written.
1062
1063 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001064
1065 .. note::
1066
1067 This function is intended for low-level I/O and must be applied to a file
Benjamin Petersonfa0d7032009-06-01 22:42:33 +00001068 descriptor as returned by :func:`os.open` or :func:`pipe`. To write a "file
Georg Brandl116aa622007-08-15 14:28:22 +00001069 object" returned by the built-in function :func:`open` or by :func:`popen` or
Benjamin Petersonfa0d7032009-06-01 22:42:33 +00001070 :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
1071 :meth:`~file.write` method.
Georg Brandl116aa622007-08-15 14:28:22 +00001072
Georg Brandl8569e582010-05-19 20:57:08 +00001073
Ross Lagerwall7807c352011-03-17 20:20:30 +02001074.. function:: writev(fd, buffers)
1075
Ezio Melottif1064492011-10-19 11:06:26 +03001076 Write the contents of *buffers* to file descriptor *fd*, where *buffers*
Ross Lagerwall7807c352011-03-17 20:20:30 +02001077 is an arbitrary sequence of buffers.
1078 Returns the total number of bytes written.
1079
1080 Availability: Unix.
1081
1082 .. versionadded:: 3.3
1083
1084
Georg Brandl8569e582010-05-19 20:57:08 +00001085.. _open-constants:
1086
1087``open()`` flag constants
1088~~~~~~~~~~~~~~~~~~~~~~~~~
1089
Georg Brandlaf265f42008-12-07 15:06:20 +00001090The following constants are options for the *flags* parameter to the
Benjamin Petersonfa0d7032009-06-01 22:42:33 +00001091:func:`~os.open` function. They can be combined using the bitwise OR operator
Georg Brandlaf265f42008-12-07 15:06:20 +00001092``|``. Some of them are not available on all platforms. For descriptions of
1093their availability and use, consult the :manpage:`open(2)` manual page on Unix
Doug Hellmanneb097fc2009-09-20 20:56:56 +00001094or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001095
1096
1097.. data:: O_RDONLY
1098 O_WRONLY
1099 O_RDWR
1100 O_APPEND
1101 O_CREAT
1102 O_EXCL
1103 O_TRUNC
1104
Georg Brandlaf265f42008-12-07 15:06:20 +00001105 These constants are available on Unix and Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001106
1107
1108.. data:: O_DSYNC
1109 O_RSYNC
1110 O_SYNC
1111 O_NDELAY
1112 O_NONBLOCK
1113 O_NOCTTY
1114 O_SHLOCK
1115 O_EXLOCK
Charles-François Natali1e045b12011-05-22 20:42:32 +02001116 O_CLOEXEC
Georg Brandl116aa622007-08-15 14:28:22 +00001117
Georg Brandlaf265f42008-12-07 15:06:20 +00001118 These constants are only available on Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001119
Victor Stinnere3455c02011-10-20 00:46:21 +02001120 .. versionchanged:: 3.3
1121 Add :data:`O_CLOEXEC` constant.
Georg Brandl116aa622007-08-15 14:28:22 +00001122
1123.. data:: O_BINARY
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +00001124 O_NOINHERIT
Georg Brandl116aa622007-08-15 14:28:22 +00001125 O_SHORT_LIVED
1126 O_TEMPORARY
1127 O_RANDOM
1128 O_SEQUENTIAL
1129 O_TEXT
1130
Georg Brandlaf265f42008-12-07 15:06:20 +00001131 These constants are only available on Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001132
1133
Alexandre Vassalottibee32532008-05-16 18:15:12 +00001134.. data:: O_ASYNC
1135 O_DIRECT
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +00001136 O_DIRECTORY
1137 O_NOFOLLOW
1138 O_NOATIME
1139
Georg Brandlaf265f42008-12-07 15:06:20 +00001140 These constants are GNU extensions and not present if they are not defined by
1141 the C library.
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +00001142
1143
Victor Stinner8b905bd2011-10-25 13:34:04 +02001144.. data:: RTLD_LAZY
1145 RTLD_NOW
1146 RTLD_GLOBAL
1147 RTLD_LOCAL
1148 RTLD_NODELETE
1149 RTLD_NOLOAD
1150 RTLD_DEEPBIND
1151
1152 See the Unix manual page :manpage:`dlopen(3)`.
1153
1154 .. versionadded:: 3.3
1155
1156
Antoine Pitroubcf2b592012-02-08 23:28:36 +01001157.. _terminal-size:
1158
1159Querying the size of a terminal
1160~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1161
1162.. versionadded:: 3.3
1163
1164.. function:: get_terminal_size(fd=STDOUT_FILENO)
1165
1166 Return the size of the terminal window as ``(columns, lines)``,
1167 tuple of type :class:`terminal_size`.
1168
1169 The optional argument ``fd`` (default ``STDOUT_FILENO``, or standard
1170 output) specifies which file descriptor should be queried.
1171
1172 If the file descriptor is not connected to a terminal, an :exc:`OSError`
Andrew Svetlov5b898402012-12-18 21:26:36 +02001173 is raised.
Antoine Pitroubcf2b592012-02-08 23:28:36 +01001174
1175 :func:`shutil.get_terminal_size` is the high-level function which
1176 should normally be used, ``os.get_terminal_size`` is the low-level
1177 implementation.
1178
1179 Availability: Unix, Windows.
1180
Georg Brandl6cff9ff2012-06-24 14:05:40 +02001181.. class:: terminal_size
Antoine Pitroubcf2b592012-02-08 23:28:36 +01001182
Georg Brandl6cff9ff2012-06-24 14:05:40 +02001183 A subclass of tuple, holding ``(columns, lines)`` of the terminal window size.
Antoine Pitroubcf2b592012-02-08 23:28:36 +01001184
1185 .. attribute:: columns
1186
1187 Width of the terminal window in characters.
1188
1189 .. attribute:: lines
1190
1191 Height of the terminal window in characters.
1192
1193
Georg Brandl116aa622007-08-15 14:28:22 +00001194.. _os-file-dir:
1195
1196Files and Directories
1197---------------------
1198
Georg Brandl50c40002012-06-24 11:45:20 +02001199On some Unix platforms, many of these functions support one or more of these
1200features:
1201
1202.. _path_fd:
1203
Larry Hastings77892dc2012-06-25 03:27:33 -07001204* **specifying a file descriptor:**
1205 For some functions, the *path* argument can be not only a string giving a path
Georg Brandl50c40002012-06-24 11:45:20 +02001206 name, but also a file descriptor. The function will then operate on the file
Georg Brandlaceaf902012-06-25 08:33:56 +02001207 referred to by the descriptor. (For POSIX systems, Python will call the
1208 ``f...`` version of the function.)
Georg Brandl50c40002012-06-24 11:45:20 +02001209
1210 You can check whether or not *path* can be specified as a file descriptor on
1211 your platform using :data:`os.supports_fd`. If it is unavailable, using it
1212 will raise a :exc:`NotImplementedError`.
1213
1214 If the function also supports *dir_fd* or *follow_symlinks* arguments, it is
1215 an error to specify one of those when supplying *path* as a file descriptor.
1216
1217.. _dir_fd:
1218
Larry Hastings77892dc2012-06-25 03:27:33 -07001219* **paths relative to directory descriptors:** If *dir_fd* is not ``None``, it
Georg Brandl50c40002012-06-24 11:45:20 +02001220 should be a file descriptor referring to a directory, and the path to operate
1221 on should be relative; path will then be relative to that directory. If the
Georg Brandlaceaf902012-06-25 08:33:56 +02001222 path is absolute, *dir_fd* is ignored. (For POSIX systems, Python will call
Larry Hastings77892dc2012-06-25 03:27:33 -07001223 the ``...at`` or ``f...at`` version of the function.)
Georg Brandl50c40002012-06-24 11:45:20 +02001224
1225 You can check whether or not *dir_fd* is supported on your platform using
1226 :data:`os.supports_dir_fd`. If it is unavailable, using it will raise a
1227 :exc:`NotImplementedError`.
1228
1229.. _follow_symlinks:
1230
Larry Hastings77892dc2012-06-25 03:27:33 -07001231* **not following symlinks:** If *follow_symlinks* is
Georg Brandl50c40002012-06-24 11:45:20 +02001232 ``False``, and the last element of the path to operate on is a symbolic link,
1233 the function will operate on the symbolic link itself instead of the file the
Georg Brandlaceaf902012-06-25 08:33:56 +02001234 link points to. (For POSIX systems, Python will call the ``l...`` version of
Georg Brandl50c40002012-06-24 11:45:20 +02001235 the function.)
1236
1237 You can check whether or not *follow_symlinks* is supported on your platform
1238 using :data:`os.supports_follow_symlinks`. If it is unavailable, using it
1239 will raise a :exc:`NotImplementedError`.
1240
1241
1242
Larry Hastings9cf065c2012-06-22 16:30:09 -07001243.. function:: access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True)
Georg Brandl116aa622007-08-15 14:28:22 +00001244
1245 Use the real uid/gid to test for access to *path*. Note that most operations
1246 will use the effective uid/gid, therefore this routine can be used in a
1247 suid/sgid environment to test if the invoking user has the specified access to
1248 *path*. *mode* should be :const:`F_OK` to test the existence of *path*, or it
1249 can be the inclusive OR of one or more of :const:`R_OK`, :const:`W_OK`, and
1250 :const:`X_OK` to test permissions. Return :const:`True` if access is allowed,
1251 :const:`False` if not. See the Unix man page :manpage:`access(2)` for more
Benjamin Petersonf650e462010-05-06 23:03:05 +00001252 information.
1253
Georg Brandl50c40002012-06-24 11:45:20 +02001254 This function can support specifying :ref:`paths relative to directory
1255 descriptors <dir_fd>` and :ref:`not following symlinks <follow_symlinks>`.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001256
1257 If *effective_ids* is ``True``, :func:`access` will perform its access
1258 checks using the effective uid/gid instead of the real uid/gid.
1259 *effective_ids* may not be supported on your platform; you can check whether
1260 or not it is available using :data:`os.supports_effective_ids`. If it is
1261 unavailable, using it will raise a :exc:`NotImplementedError`.
1262
Benjamin Petersonf650e462010-05-06 23:03:05 +00001263 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001264
1265 .. note::
1266
Georg Brandl502d9a52009-07-26 15:02:41 +00001267 Using :func:`access` to check if a user is authorized to e.g. open a file
1268 before actually doing so using :func:`open` creates a security hole,
1269 because the user might exploit the short time interval between checking
Benjamin Peterson249b5082011-05-20 11:41:13 -05001270 and opening the file to manipulate it. It's preferable to use :term:`EAFP`
1271 techniques. For example::
1272
1273 if os.access("myfile", os.R_OK):
1274 with open("myfile") as fp:
1275 return fp.read()
1276 return "some default data"
1277
1278 is better written as::
1279
1280 try:
1281 fp = open("myfile")
Antoine Pitrou62ab10a02011-10-12 20:10:51 +02001282 except PermissionError:
1283 return "some default data"
Benjamin Peterson249b5082011-05-20 11:41:13 -05001284 else:
1285 with fp:
1286 return fp.read()
Georg Brandl116aa622007-08-15 14:28:22 +00001287
1288 .. note::
1289
1290 I/O operations may fail even when :func:`access` indicates that they would
1291 succeed, particularly for operations on network filesystems which may have
1292 permissions semantics beyond the usual POSIX permission-bit model.
1293
Larry Hastings9cf065c2012-06-22 16:30:09 -07001294 .. versionchanged:: 3.3
1295 Added the *dir_fd*, *effective_ids*, and *follow_symlinks* parameters.
1296
Georg Brandl116aa622007-08-15 14:28:22 +00001297
1298.. data:: F_OK
Georg Brandl8ccadaa2012-06-24 12:50:06 +02001299 R_OK
1300 W_OK
1301 X_OK
Georg Brandl116aa622007-08-15 14:28:22 +00001302
Georg Brandl8ccadaa2012-06-24 12:50:06 +02001303 Values to pass as the *mode* parameter of :func:`access` to test the
1304 existence, readability, writability and executability of *path*,
1305 respectively.
Georg Brandl116aa622007-08-15 14:28:22 +00001306
1307
1308.. function:: chdir(path)
1309
1310 .. index:: single: directory; changing
1311
Benjamin Petersonf650e462010-05-06 23:03:05 +00001312 Change the current working directory to *path*.
1313
Larry Hastings77892dc2012-06-25 03:27:33 -07001314 This function can support :ref:`specifying a file descriptor <path_fd>`. The
Georg Brandl50c40002012-06-24 11:45:20 +02001315 descriptor must refer to an opened directory, not an open file.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001316
Benjamin Petersonf650e462010-05-06 23:03:05 +00001317 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001318
Larry Hastings9cf065c2012-06-22 16:30:09 -07001319 .. versionadded:: 3.3
1320 Added support for specifying *path* as a file descriptor
Georg Brandl50c40002012-06-24 11:45:20 +02001321 on some platforms.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001322
Georg Brandl116aa622007-08-15 14:28:22 +00001323
Larry Hastings9cf065c2012-06-22 16:30:09 -07001324.. function:: chflags(path, flags, *, follow_symlinks=True)
Georg Brandl116aa622007-08-15 14:28:22 +00001325
1326 Set the flags of *path* to the numeric *flags*. *flags* may take a combination
1327 (bitwise OR) of the following values (as defined in the :mod:`stat` module):
1328
R David Murray30178062011-03-10 17:18:33 -05001329 * :data:`stat.UF_NODUMP`
1330 * :data:`stat.UF_IMMUTABLE`
1331 * :data:`stat.UF_APPEND`
1332 * :data:`stat.UF_OPAQUE`
1333 * :data:`stat.UF_NOUNLINK`
Ned Deily3eb67d52011-06-28 00:00:28 -07001334 * :data:`stat.UF_COMPRESSED`
1335 * :data:`stat.UF_HIDDEN`
R David Murray30178062011-03-10 17:18:33 -05001336 * :data:`stat.SF_ARCHIVED`
1337 * :data:`stat.SF_IMMUTABLE`
1338 * :data:`stat.SF_APPEND`
1339 * :data:`stat.SF_NOUNLINK`
1340 * :data:`stat.SF_SNAPSHOT`
Georg Brandl116aa622007-08-15 14:28:22 +00001341
Georg Brandl50c40002012-06-24 11:45:20 +02001342 This function can support :ref:`not following symlinks <follow_symlinks>`.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001343
Georg Brandlc575c902008-09-13 17:46:05 +00001344 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001345
Larry Hastings9cf065c2012-06-22 16:30:09 -07001346 .. versionadded:: 3.3
1347 The *follow_symlinks* argument.
1348
Georg Brandl116aa622007-08-15 14:28:22 +00001349
Larry Hastings9cf065c2012-06-22 16:30:09 -07001350.. function:: chmod(path, mode, *, dir_fd=None, follow_symlinks=True)
Georg Brandl116aa622007-08-15 14:28:22 +00001351
1352 Change the mode of *path* to the numeric *mode*. *mode* may take one of the
Christian Heimesfaf2f632008-01-06 16:59:19 +00001353 following values (as defined in the :mod:`stat` module) or bitwise ORed
Georg Brandl116aa622007-08-15 14:28:22 +00001354 combinations of them:
1355
Alexandre Vassalottic22c6f22009-07-21 00:51:58 +00001356 * :data:`stat.S_ISUID`
1357 * :data:`stat.S_ISGID`
1358 * :data:`stat.S_ENFMT`
1359 * :data:`stat.S_ISVTX`
1360 * :data:`stat.S_IREAD`
1361 * :data:`stat.S_IWRITE`
1362 * :data:`stat.S_IEXEC`
1363 * :data:`stat.S_IRWXU`
1364 * :data:`stat.S_IRUSR`
1365 * :data:`stat.S_IWUSR`
1366 * :data:`stat.S_IXUSR`
1367 * :data:`stat.S_IRWXG`
1368 * :data:`stat.S_IRGRP`
1369 * :data:`stat.S_IWGRP`
1370 * :data:`stat.S_IXGRP`
1371 * :data:`stat.S_IRWXO`
1372 * :data:`stat.S_IROTH`
1373 * :data:`stat.S_IWOTH`
1374 * :data:`stat.S_IXOTH`
Georg Brandl116aa622007-08-15 14:28:22 +00001375
Georg Brandl50c40002012-06-24 11:45:20 +02001376 This function can support :ref:`specifying a file descriptor <path_fd>`,
1377 :ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not
1378 following symlinks <follow_symlinks>`.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001379
Georg Brandlc575c902008-09-13 17:46:05 +00001380 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001381
1382 .. note::
1383
Georg Brandl50c40002012-06-24 11:45:20 +02001384 Although Windows supports :func:`chmod`, you can only set the file's
1385 read-only flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD``
1386 constants or a corresponding integer value). All other bits are ignored.
Georg Brandl116aa622007-08-15 14:28:22 +00001387
Larry Hastings9cf065c2012-06-22 16:30:09 -07001388 .. versionadded:: 3.3
1389 Added support for specifying *path* as an open file descriptor,
1390 and the *dir_fd* and *follow_symlinks* arguments.
Georg Brandl116aa622007-08-15 14:28:22 +00001391
Larry Hastings9cf065c2012-06-22 16:30:09 -07001392
1393.. function:: chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True)
Georg Brandl116aa622007-08-15 14:28:22 +00001394
Georg Brandl50c40002012-06-24 11:45:20 +02001395 Change the owner and group id of *path* to the numeric *uid* and *gid*. To
1396 leave one of the ids unchanged, set it to -1.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001397
Georg Brandl50c40002012-06-24 11:45:20 +02001398 This function can support :ref:`specifying a file descriptor <path_fd>`,
1399 :ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not
1400 following symlinks <follow_symlinks>`.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001401
Sandro Tosid902a142011-08-22 23:28:27 +02001402 See :func:`shutil.chown` for a higher-level function that accepts names in
1403 addition to numeric ids.
1404
Benjamin Petersonf650e462010-05-06 23:03:05 +00001405 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001406
Larry Hastings9cf065c2012-06-22 16:30:09 -07001407 .. versionadded:: 3.3
1408 Added support for specifying an open file descriptor for *path*,
1409 and the *dir_fd* and *follow_symlinks* arguments.
Georg Brandl116aa622007-08-15 14:28:22 +00001410
Benjamin Peterson799bd802011-08-31 22:15:17 -04001411
Georg Brandl8ccadaa2012-06-24 12:50:06 +02001412.. function:: chroot(path)
1413
Georg Brandl8a5555f2012-06-24 13:29:09 +02001414 Change the root directory of the current process to *path*.
1415
1416 Availability: Unix.
Georg Brandl8ccadaa2012-06-24 12:50:06 +02001417
1418
1419.. function:: fchdir(fd)
1420
1421 Change the current working directory to the directory represented by the file
1422 descriptor *fd*. The descriptor must refer to an opened directory, not an
Georg Brandl4d399a42012-06-25 07:40:32 +02001423 open file. As of Python 3.3, this is equivalent to ``os.chdir(fd)``.
Georg Brandl8ccadaa2012-06-24 12:50:06 +02001424
1425 Availability: Unix.
1426
1427
1428.. function:: getcwd()
1429
1430 Return a string representing the current working directory.
1431
1432 Availability: Unix, Windows.
1433
1434
1435.. function:: getcwdb()
1436
1437 Return a bytestring representing the current working directory.
1438
1439 Availability: Unix, Windows.
1440
1441
Georg Brandl116aa622007-08-15 14:28:22 +00001442.. function:: lchflags(path, flags)
1443
Georg Brandl50c40002012-06-24 11:45:20 +02001444 Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do
Georg Brandl4d399a42012-06-25 07:40:32 +02001445 not follow symbolic links. As of Python 3.3, this is equivalent to
Georg Brandlb9df00c2012-06-24 12:38:14 +02001446 ``os.chflags(path, flags, follow_symlinks=False)``.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001447
1448 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001449
Georg Brandl116aa622007-08-15 14:28:22 +00001450
Christian Heimes93852662007-12-01 12:22:32 +00001451.. function:: lchmod(path, mode)
1452
1453 Change the mode of *path* to the numeric *mode*. If path is a symlink, this
Georg Brandl50c40002012-06-24 11:45:20 +02001454 affects the symlink rather than the target. See the docs for :func:`chmod`
Georg Brandl4d399a42012-06-25 07:40:32 +02001455 for possible values of *mode*. As of Python 3.3, this is equivalent to
Georg Brandlb9df00c2012-06-24 12:38:14 +02001456 ``os.chmod(path, mode, follow_symlinks=False)``.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001457
1458 Availability: Unix.
Christian Heimes93852662007-12-01 12:22:32 +00001459
Christian Heimes93852662007-12-01 12:22:32 +00001460
Georg Brandl116aa622007-08-15 14:28:22 +00001461.. function:: lchown(path, uid, gid)
1462
Georg Brandl50c40002012-06-24 11:45:20 +02001463 Change the owner and group id of *path* to the numeric *uid* and *gid*. This
Georg Brandl4d399a42012-06-25 07:40:32 +02001464 function will not follow symbolic links. As of Python 3.3, this is equivalent
Georg Brandlb9df00c2012-06-24 12:38:14 +02001465 to ``os.chown(path, uid, gid, follow_symlinks=False)``.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001466
1467 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001468
Georg Brandl116aa622007-08-15 14:28:22 +00001469
Larry Hastings9cf065c2012-06-22 16:30:09 -07001470.. function:: link(src, dst, *, src_dir_fd=None, dst_dir_fd=None, follow_symlinks=True)
Benjamin Peterson799bd802011-08-31 22:15:17 -04001471
Larry Hastings9cf065c2012-06-22 16:30:09 -07001472 Create a hard link pointing to *src* named *dst*.
Benjamin Peterson799bd802011-08-31 22:15:17 -04001473
Georg Brandlaceaf902012-06-25 08:33:56 +02001474 This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to
1475 supply :ref:`paths relative to directory descriptors <dir_fd>`, and :ref:`not
1476 following symlinks <follow_symlinks>`.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001477
Brian Curtin1b9df392010-11-24 20:24:31 +00001478 Availability: Unix, Windows.
1479
1480 .. versionchanged:: 3.2
1481 Added Windows support.
Georg Brandl116aa622007-08-15 14:28:22 +00001482
Larry Hastings9cf065c2012-06-22 16:30:09 -07001483 .. versionadded:: 3.3
1484 Added the *src_dir_fd*, *dst_dir_fd*, and *follow_symlinks* arguments.
1485
Georg Brandl116aa622007-08-15 14:28:22 +00001486
Martin v. Löwis9c71f902010-07-24 10:09:11 +00001487.. function:: listdir(path='.')
Georg Brandl116aa622007-08-15 14:28:22 +00001488
Benjamin Peterson4469d0c2008-11-30 22:46:23 +00001489 Return a list containing the names of the entries in the directory given by
Larry Hastingsfdaea062012-06-25 04:42:23 -07001490 *path*. The list is in arbitrary order, and does not include the special
1491 entries ``'.'`` and ``'..'`` even if they are present in the directory.
Georg Brandl116aa622007-08-15 14:28:22 +00001492
Larry Hastingsfdaea062012-06-25 04:42:23 -07001493 *path* may be either of type ``str`` or of type ``bytes``. If *path*
1494 is of type ``bytes``, the filenames returned will also be of type ``bytes``;
1495 in all other circumstances, they will be of type ``str``.
Georg Brandl116aa622007-08-15 14:28:22 +00001496
Larry Hastings77892dc2012-06-25 03:27:33 -07001497 This function can also support :ref:`specifying a file descriptor
1498 <path_fd>`; the file descriptor must refer to a directory.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001499
Larry Hastingsfdaea062012-06-25 04:42:23 -07001500 .. note::
1501 To encode ``str`` filenames to ``bytes``, use :func:`~os.fsencode`.
1502
Benjamin Petersonf650e462010-05-06 23:03:05 +00001503 Availability: Unix, Windows.
1504
Martin v. Löwisc9e1c7d2010-07-23 12:16:41 +00001505 .. versionchanged:: 3.2
1506 The *path* parameter became optional.
Georg Brandl116aa622007-08-15 14:28:22 +00001507
Larry Hastings9cf065c2012-06-22 16:30:09 -07001508 .. versionadded:: 3.3
1509 Added support for specifying an open file descriptor for *path*.
Benjamin Peterson799bd802011-08-31 22:15:17 -04001510
Georg Brandl50c40002012-06-24 11:45:20 +02001511
Larry Hastings9cf065c2012-06-22 16:30:09 -07001512.. function:: lstat(path, *, dir_fd=None)
Georg Brandl116aa622007-08-15 14:28:22 +00001513
R. David Murray7b1aae92011-01-24 19:34:58 +00001514 Perform the equivalent of an :c:func:`lstat` system call on the given path.
1515 Similar to :func:`~os.stat`, but does not follow symbolic links. On
1516 platforms that do not support symbolic links, this is an alias for
Georg Brandl4d399a42012-06-25 07:40:32 +02001517 :func:`~os.stat`. As of Python 3.3, this is equivalent to ``os.stat(path,
Georg Brandlb9df00c2012-06-24 12:38:14 +02001518 dir_fd=dir_fd, follow_symlinks=False)``.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001519
Georg Brandl50c40002012-06-24 11:45:20 +02001520 This function can also support :ref:`paths relative to directory descriptors
1521 <dir_fd>`.
Brian Curtinc7395692010-07-09 15:15:09 +00001522
Georg Brandlb3823372010-07-10 08:58:37 +00001523 .. versionchanged:: 3.2
1524 Added support for Windows 6.0 (Vista) symbolic links.
Georg Brandl116aa622007-08-15 14:28:22 +00001525
Larry Hastings9cf065c2012-06-22 16:30:09 -07001526 .. versionchanged:: 3.3
1527 Added the *dir_fd* parameter.
Ross Lagerwall7807c352011-03-17 20:20:30 +02001528
1529
Georg Brandl8ccadaa2012-06-24 12:50:06 +02001530.. function:: mkdir(path, mode=0o777, *, dir_fd=None)
1531
1532 Create a directory named *path* with numeric mode *mode*.
1533
1534 On some systems, *mode* is ignored. Where it is used, the current umask
1535 value is first masked out. If the directory already exists, :exc:`OSError`
1536 is raised.
1537
1538 This function can also support :ref:`paths relative to directory descriptors
1539 <dir_fd>`.
1540
1541 It is also possible to create temporary directories; see the
1542 :mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
1543
1544 Availability: Unix, Windows.
1545
1546 .. versionadded:: 3.3
1547 The *dir_fd* argument.
1548
1549
1550.. function:: makedirs(path, mode=0o777, exist_ok=False)
1551
1552 .. index::
1553 single: directory; creating
1554 single: UNC paths; and os.makedirs()
1555
1556 Recursive directory creation function. Like :func:`mkdir`, but makes all
Hynek Schlawack0230b6a2012-10-07 18:04:38 +02001557 intermediate-level directories needed to contain the leaf directory.
1558
1559 The default *mode* is ``0o777`` (octal). On some systems, *mode* is
1560 ignored. Where it is used, the current umask value is first masked out.
1561
1562 If *exists_ok* is ``False`` (the default), an :exc:`OSError` is raised if
1563 the target directory already exists. If *exists_ok* is ``True`` an
1564 :exc:`OSError` is still raised if the umask-masked *mode* is different from
1565 the existing mode, on systems where the mode is used. :exc:`OSError` will
1566 also be raised if the directory creation fails.
Georg Brandl8ccadaa2012-06-24 12:50:06 +02001567
1568 .. note::
1569
1570 :func:`makedirs` will become confused if the path elements to create
Hynek Schlawack0230b6a2012-10-07 18:04:38 +02001571 include :data:`pardir` (eg. ".." on UNIX systems).
Georg Brandl8ccadaa2012-06-24 12:50:06 +02001572
1573 This function handles UNC paths correctly.
1574
1575 .. versionadded:: 3.2
1576 The *exist_ok* parameter.
1577
1578
Larry Hastings9cf065c2012-06-22 16:30:09 -07001579.. function:: mkfifo(path, mode=0o666, *, dir_fd=None)
Georg Brandl116aa622007-08-15 14:28:22 +00001580
Larry Hastings9cf065c2012-06-22 16:30:09 -07001581 Create a FIFO (a named pipe) named *path* with numeric mode *mode*.
1582 The current umask value is first masked out from the mode.
1583
Georg Brandl50c40002012-06-24 11:45:20 +02001584 This function can also support :ref:`paths relative to directory descriptors
1585 <dir_fd>`.
Georg Brandl116aa622007-08-15 14:28:22 +00001586
1587 FIFOs are pipes that can be accessed like regular files. FIFOs exist until they
1588 are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as
1589 rendezvous between "client" and "server" type processes: the server opens the
1590 FIFO for reading, and the client opens it for writing. Note that :func:`mkfifo`
1591 doesn't open the FIFO --- it just creates the rendezvous point.
1592
Benjamin Petersonf650e462010-05-06 23:03:05 +00001593 Availability: Unix.
1594
Larry Hastings9cf065c2012-06-22 16:30:09 -07001595 .. versionadded:: 3.3
1596 The *dir_fd* argument.
Georg Brandl116aa622007-08-15 14:28:22 +00001597
Larry Hastings9cf065c2012-06-22 16:30:09 -07001598
1599.. function:: mknod(filename, mode=0o600, device=0, *, dir_fd=None)
Georg Brandl116aa622007-08-15 14:28:22 +00001600
1601 Create a filesystem node (file, device special file or named pipe) named
Georg Brandl18244152009-09-02 20:34:52 +00001602 *filename*. *mode* specifies both the permissions to use and the type of node
1603 to be created, being combined (bitwise OR) with one of ``stat.S_IFREG``,
1604 ``stat.S_IFCHR``, ``stat.S_IFBLK``, and ``stat.S_IFIFO`` (those constants are
1605 available in :mod:`stat`). For ``stat.S_IFCHR`` and ``stat.S_IFBLK``,
1606 *device* defines the newly created device special file (probably using
Georg Brandl116aa622007-08-15 14:28:22 +00001607 :func:`os.makedev`), otherwise it is ignored.
1608
Georg Brandl50c40002012-06-24 11:45:20 +02001609 This function can also support :ref:`paths relative to directory descriptors
1610 <dir_fd>`.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001611
1612 .. versionadded:: 3.3
1613 The *dir_fd* argument.
1614
Georg Brandl116aa622007-08-15 14:28:22 +00001615
1616.. function:: major(device)
1617
Christian Heimesfaf2f632008-01-06 16:59:19 +00001618 Extract the device major number from a raw device number (usually the
Georg Brandl60203b42010-10-06 10:11:56 +00001619 :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`).
Georg Brandl116aa622007-08-15 14:28:22 +00001620
Georg Brandl116aa622007-08-15 14:28:22 +00001621
1622.. function:: minor(device)
1623
Christian Heimesfaf2f632008-01-06 16:59:19 +00001624 Extract the device minor number from a raw device number (usually the
Georg Brandl60203b42010-10-06 10:11:56 +00001625 :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`).
Georg Brandl116aa622007-08-15 14:28:22 +00001626
Georg Brandl116aa622007-08-15 14:28:22 +00001627
1628.. function:: makedev(major, minor)
1629
Christian Heimesfaf2f632008-01-06 16:59:19 +00001630 Compose a raw device number from the major and minor device numbers.
Georg Brandl116aa622007-08-15 14:28:22 +00001631
Georg Brandl116aa622007-08-15 14:28:22 +00001632
Georg Brandl116aa622007-08-15 14:28:22 +00001633.. function:: pathconf(path, name)
1634
1635 Return system configuration information relevant to a named file. *name*
1636 specifies the configuration value to retrieve; it may be a string which is the
1637 name of a defined system value; these names are specified in a number of
1638 standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define
1639 additional names as well. The names known to the host operating system are
1640 given in the ``pathconf_names`` dictionary. For configuration variables not
1641 included in that mapping, passing an integer for *name* is also accepted.
Georg Brandl116aa622007-08-15 14:28:22 +00001642
1643 If *name* is a string and is not known, :exc:`ValueError` is raised. If a
1644 specific value for *name* is not supported by the host system, even if it is
1645 included in ``pathconf_names``, an :exc:`OSError` is raised with
1646 :const:`errno.EINVAL` for the error number.
1647
Larry Hastings77892dc2012-06-25 03:27:33 -07001648 This function can support :ref:`specifying a file descriptor
Georg Brandl306336b2012-06-24 12:55:33 +02001649 <path_fd>`.
1650
Benjamin Petersonf650e462010-05-06 23:03:05 +00001651 Availability: Unix.
1652
Georg Brandl116aa622007-08-15 14:28:22 +00001653
1654.. data:: pathconf_names
1655
1656 Dictionary mapping names accepted by :func:`pathconf` and :func:`fpathconf` to
1657 the integer values defined for those names by the host operating system. This
Georg Brandl8a5555f2012-06-24 13:29:09 +02001658 can be used to determine the set of names known to the system.
1659
1660 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001661
1662
Larry Hastings9cf065c2012-06-22 16:30:09 -07001663.. function:: readlink(path, *, dir_fd=None)
Georg Brandl116aa622007-08-15 14:28:22 +00001664
1665 Return a string representing the path to which the symbolic link points. The
Georg Brandl50c40002012-06-24 11:45:20 +02001666 result may be either an absolute or relative pathname; if it is relative, it
1667 may be converted to an absolute pathname using
1668 ``os.path.join(os.path.dirname(path), result)``.
Georg Brandl116aa622007-08-15 14:28:22 +00001669
Georg Brandl76e55382008-10-08 16:34:57 +00001670 If the *path* is a string object, the result will also be a string object,
1671 and the call may raise an UnicodeDecodeError. If the *path* is a bytes
1672 object, the result will be a bytes object.
Georg Brandl116aa622007-08-15 14:28:22 +00001673
Georg Brandl50c40002012-06-24 11:45:20 +02001674 This function can also support :ref:`paths relative to directory descriptors
1675 <dir_fd>`.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001676
Brian Curtinc7395692010-07-09 15:15:09 +00001677 Availability: Unix, Windows
1678
Georg Brandlb3823372010-07-10 08:58:37 +00001679 .. versionchanged:: 3.2
1680 Added support for Windows 6.0 (Vista) symbolic links.
Georg Brandl116aa622007-08-15 14:28:22 +00001681
Larry Hastings9cf065c2012-06-22 16:30:09 -07001682 .. versionadded:: 3.3
1683 The *dir_fd* argument.
Georg Brandl116aa622007-08-15 14:28:22 +00001684
Georg Brandl116aa622007-08-15 14:28:22 +00001685
Larry Hastingsb698d8e2012-06-23 16:55:07 -07001686.. function:: remove(path, *, dir_fd=None)
Larry Hastings9cf065c2012-06-22 16:30:09 -07001687
Georg Brandl50c40002012-06-24 11:45:20 +02001688 Remove (delete) the file *path*. If *path* is a directory, :exc:`OSError` is
1689 raised. Use :func:`rmdir` to remove directories.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001690
Georg Brandl50c40002012-06-24 11:45:20 +02001691 This function can support :ref:`paths relative to directory descriptors
1692 <dir_fd>`.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001693
1694 On Windows, attempting to remove a file that is in use causes an exception to
1695 be raised; on Unix, the directory entry is removed but the storage allocated
1696 to the file is not made available until the original file is no longer in use.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001697
Larry Hastingsb698d8e2012-06-23 16:55:07 -07001698 This function is identical to :func:`unlink`.
1699
Benjamin Petersonf650e462010-05-06 23:03:05 +00001700 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001701
Larry Hastings9cf065c2012-06-22 16:30:09 -07001702 .. versionadded:: 3.3
Larry Hastingsb698d8e2012-06-23 16:55:07 -07001703 The *dir_fd* argument.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001704
Georg Brandl116aa622007-08-15 14:28:22 +00001705
1706.. function:: removedirs(path)
1707
1708 .. index:: single: directory; deleting
1709
Christian Heimesfaf2f632008-01-06 16:59:19 +00001710 Remove directories recursively. Works like :func:`rmdir` except that, if the
Georg Brandl116aa622007-08-15 14:28:22 +00001711 leaf directory is successfully removed, :func:`removedirs` tries to
1712 successively remove every parent directory mentioned in *path* until an error
1713 is raised (which is ignored, because it generally means that a parent directory
1714 is not empty). For example, ``os.removedirs('foo/bar/baz')`` will first remove
1715 the directory ``'foo/bar/baz'``, and then remove ``'foo/bar'`` and ``'foo'`` if
1716 they are empty. Raises :exc:`OSError` if the leaf directory could not be
1717 successfully removed.
1718
Georg Brandl116aa622007-08-15 14:28:22 +00001719
Larry Hastings9cf065c2012-06-22 16:30:09 -07001720.. function:: rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None)
Georg Brandl116aa622007-08-15 14:28:22 +00001721
1722 Rename the file or directory *src* to *dst*. If *dst* is a directory,
1723 :exc:`OSError` will be raised. On Unix, if *dst* exists and is a file, it will
Christian Heimesfaf2f632008-01-06 16:59:19 +00001724 be replaced silently if the user has permission. The operation may fail on some
Georg Brandl116aa622007-08-15 14:28:22 +00001725 Unix flavors if *src* and *dst* are on different filesystems. If successful,
1726 the renaming will be an atomic operation (this is a POSIX requirement). On
1727 Windows, if *dst* already exists, :exc:`OSError` will be raised even if it is a
Antoine Pitrouf3b2d882012-01-30 22:08:52 +01001728 file.
1729
Georg Brandlaceaf902012-06-25 08:33:56 +02001730 This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to
1731 supply :ref:`paths relative to directory descriptors <dir_fd>`.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001732
Antoine Pitrouf3b2d882012-01-30 22:08:52 +01001733 If you want cross-platform overwriting of the destination, use :func:`replace`.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001734
1735 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001736
Larry Hastings9cf065c2012-06-22 16:30:09 -07001737 .. versionadded:: 3.3
1738 The *src_dir_fd* and *dst_dir_fd* arguments.
1739
Georg Brandl116aa622007-08-15 14:28:22 +00001740
1741.. function:: renames(old, new)
1742
1743 Recursive directory or file renaming function. Works like :func:`rename`, except
1744 creation of any intermediate directories needed to make the new pathname good is
1745 attempted first. After the rename, directories corresponding to rightmost path
1746 segments of the old name will be pruned away using :func:`removedirs`.
1747
Georg Brandl116aa622007-08-15 14:28:22 +00001748 .. note::
1749
1750 This function can fail with the new directory structure made if you lack
1751 permissions needed to remove the leaf directory or file.
1752
1753
Larry Hastings9cf065c2012-06-22 16:30:09 -07001754.. function:: replace(src, dst, *, src_dir_fd=None, dst_dir_fd=None)
Antoine Pitrouf3b2d882012-01-30 22:08:52 +01001755
1756 Rename the file or directory *src* to *dst*. If *dst* is a directory,
1757 :exc:`OSError` will be raised. If *dst* exists and is a file, it will
1758 be replaced silently if the user has permission. The operation may fail
1759 if *src* and *dst* are on different filesystems. If successful,
1760 the renaming will be an atomic operation (this is a POSIX requirement).
1761
Georg Brandlaceaf902012-06-25 08:33:56 +02001762 This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to
1763 supply :ref:`paths relative to directory descriptors <dir_fd>`.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001764
Georg Brandl8a5555f2012-06-24 13:29:09 +02001765 Availability: Unix, Windows.
Antoine Pitrouf3b2d882012-01-30 22:08:52 +01001766
1767 .. versionadded:: 3.3
1768
1769
Larry Hastingsb698d8e2012-06-23 16:55:07 -07001770.. function:: rmdir(path, *, dir_fd=None)
Georg Brandl116aa622007-08-15 14:28:22 +00001771
Georg Brandla6053b42009-09-01 08:11:14 +00001772 Remove (delete) the directory *path*. Only works when the directory is
1773 empty, otherwise, :exc:`OSError` is raised. In order to remove whole
Benjamin Petersonf650e462010-05-06 23:03:05 +00001774 directory trees, :func:`shutil.rmtree` can be used.
1775
Georg Brandl50c40002012-06-24 11:45:20 +02001776 This function can support :ref:`paths relative to directory descriptors
1777 <dir_fd>`.
Larry Hastingsb698d8e2012-06-23 16:55:07 -07001778
Benjamin Petersonf650e462010-05-06 23:03:05 +00001779 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001780
Larry Hastingsb698d8e2012-06-23 16:55:07 -07001781 .. versionadded:: 3.3
1782 The *dir_fd* parameter.
1783
Georg Brandl116aa622007-08-15 14:28:22 +00001784
Larry Hastings9cf065c2012-06-22 16:30:09 -07001785.. function:: stat(path, *, dir_fd=None, follow_symlinks=True)
Georg Brandl116aa622007-08-15 14:28:22 +00001786
R. David Murray7b1aae92011-01-24 19:34:58 +00001787 Perform the equivalent of a :c:func:`stat` system call on the given path.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001788 *path* may be specified as either a string or as an open file descriptor.
1789 (This function normally follows symlinks; to stat a symlink add the argument
1790 ``follow_symlinks=False``, or use :func:`lstat`.)
Georg Brandl116aa622007-08-15 14:28:22 +00001791
Larry Hastings6fe20b32012-04-19 15:07:49 -07001792 The return value is an object whose attributes correspond roughly
1793 to the members of the :c:type:`stat` structure, namely:
R. David Murray7b1aae92011-01-24 19:34:58 +00001794
1795 * :attr:`st_mode` - protection bits,
1796 * :attr:`st_ino` - inode number,
1797 * :attr:`st_dev` - device,
1798 * :attr:`st_nlink` - number of hard links,
1799 * :attr:`st_uid` - user id of owner,
1800 * :attr:`st_gid` - group id of owner,
1801 * :attr:`st_size` - size of file, in bytes,
Larry Hastings6fe20b32012-04-19 15:07:49 -07001802 * :attr:`st_atime` - time of most recent access expressed in seconds,
1803 * :attr:`st_mtime` - time of most recent content modification
1804 expressed in seconds,
1805 * :attr:`st_ctime` - platform dependent; time of most recent metadata
1806 change on Unix, or the time of creation on Windows, expressed in seconds
1807 * :attr:`st_atime_ns` - time of most recent access
1808 expressed in nanoseconds as an integer,
1809 * :attr:`st_mtime_ns` - time of most recent content modification
1810 expressed in nanoseconds as an integer,
1811 * :attr:`st_ctime_ns` - platform dependent; time of most recent metadata
1812 change on Unix, or the time of creation on Windows,
1813 expressed in nanoseconds as an integer
Georg Brandl116aa622007-08-15 14:28:22 +00001814
1815 On some Unix systems (such as Linux), the following attributes may also be
R. David Murray7b1aae92011-01-24 19:34:58 +00001816 available:
1817
1818 * :attr:`st_blocks` - number of blocks allocated for file
1819 * :attr:`st_blksize` - filesystem blocksize
1820 * :attr:`st_rdev` - type of device if an inode device
1821 * :attr:`st_flags` - user defined flags for file
Georg Brandl116aa622007-08-15 14:28:22 +00001822
1823 On other Unix systems (such as FreeBSD), the following attributes may be
R. David Murray7b1aae92011-01-24 19:34:58 +00001824 available (but may be only filled out if root tries to use them):
1825
1826 * :attr:`st_gen` - file generation number
1827 * :attr:`st_birthtime` - time of file creation
Georg Brandl116aa622007-08-15 14:28:22 +00001828
1829 On Mac OS systems, the following attributes may also be available:
Georg Brandl116aa622007-08-15 14:28:22 +00001830
R. David Murray7b1aae92011-01-24 19:34:58 +00001831 * :attr:`st_rsize`
1832 * :attr:`st_creator`
1833 * :attr:`st_type`
Georg Brandl116aa622007-08-15 14:28:22 +00001834
1835 .. note::
1836
Senthil Kumaran3aac1792011-07-04 11:43:51 -07001837 The exact meaning and resolution of the :attr:`st_atime`,
Senthil Kumarana6bac952011-07-04 11:28:30 -07001838 :attr:`st_mtime`, and :attr:`st_ctime` attributes depend on the operating
1839 system and the file system. For example, on Windows systems using the FAT
1840 or FAT32 file systems, :attr:`st_mtime` has 2-second resolution, and
1841 :attr:`st_atime` has only 1-day resolution. See your operating system
1842 documentation for details.
Larry Hastings6fe20b32012-04-19 15:07:49 -07001843 Similarly, although :attr:`st_atime_ns`, :attr:`st_mtime_ns`,
1844 and :attr:`st_ctime_ns` are always expressed in nanoseconds, many
1845 systems do not provide nanosecond precision. On systems that do
1846 provide nanosecond precision, the floating-point object used to
1847 store :attr:`st_atime`, :attr:`st_mtime`, and :attr:`st_ctime`
1848 cannot preserve all of it, and as such will be slightly inexact.
1849 If you need the exact timestamps you should always use
1850 :attr:`st_atime_ns`, :attr:`st_mtime_ns`, and :attr:`st_ctime_ns`.
Georg Brandl116aa622007-08-15 14:28:22 +00001851
Georg Brandl50c40002012-06-24 11:45:20 +02001852 For backward compatibility, the return value of :func:`~os.stat` is also
1853 accessible as a tuple of at least 10 integers giving the most important (and
1854 portable) members of the :c:type:`stat` structure, in the order
1855 :attr:`st_mode`, :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`,
1856 :attr:`st_uid`, :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`,
1857 :attr:`st_mtime`, :attr:`st_ctime`. More items may be added at the end by
1858 some implementations.
R. David Murray7b1aae92011-01-24 19:34:58 +00001859
R David Murrayce478b92012-09-10 21:08:50 -04001860 This function can support :ref:`specifying a file descriptor <path_fd>` and
1861 :ref:`not following symlinks <follow_symlinks>`.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001862
R. David Murray7b1aae92011-01-24 19:34:58 +00001863 .. index:: module: stat
1864
1865 The standard module :mod:`stat` defines functions and constants that are useful
1866 for extracting information from a :c:type:`stat` structure. (On Windows, some
1867 items are filled with dummy values.)
1868
1869 Example::
1870
1871 >>> import os
1872 >>> statinfo = os.stat('somefile.txt')
1873 >>> statinfo
Raymond Hettinger8f0ae9a2011-02-18 00:53:55 +00001874 posix.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,
1875 st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,
1876 st_mtime=1297230027, st_ctime=1297230027)
R. David Murray7b1aae92011-01-24 19:34:58 +00001877 >>> statinfo.st_size
Raymond Hettinger8f0ae9a2011-02-18 00:53:55 +00001878 264
R. David Murray7b1aae92011-01-24 19:34:58 +00001879
Georg Brandlc575c902008-09-13 17:46:05 +00001880 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001881
Larry Hastings6fe20b32012-04-19 15:07:49 -07001882 .. versionadded:: 3.3
Larry Hastings9cf065c2012-06-22 16:30:09 -07001883 Added the *dir_fd* and *follow_symlinks* arguments,
1884 specifying a file descriptor instead of a path,
1885 and the :attr:`st_atime_ns`, :attr:`st_mtime_ns`,
Larry Hastings6fe20b32012-04-19 15:07:49 -07001886 and :attr:`st_ctime_ns` members.
1887
Georg Brandl116aa622007-08-15 14:28:22 +00001888
1889.. function:: stat_float_times([newvalue])
1890
1891 Determine whether :class:`stat_result` represents time stamps as float objects.
R. David Murray7b1aae92011-01-24 19:34:58 +00001892 If *newvalue* is ``True``, future calls to :func:`~os.stat` return floats, if it is
Georg Brandl116aa622007-08-15 14:28:22 +00001893 ``False``, future calls return ints. If *newvalue* is omitted, return the
1894 current setting.
1895
1896 For compatibility with older Python versions, accessing :class:`stat_result` as
1897 a tuple always returns integers.
1898
Georg Brandl55ac8f02007-09-01 13:51:09 +00001899 Python now returns float values by default. Applications which do not work
1900 correctly with floating point time stamps can use this function to restore the
1901 old behaviour.
Georg Brandl116aa622007-08-15 14:28:22 +00001902
1903 The resolution of the timestamps (that is the smallest possible fraction)
1904 depends on the system. Some systems only support second resolution; on these
1905 systems, the fraction will always be zero.
1906
1907 It is recommended that this setting is only changed at program startup time in
1908 the *__main__* module; libraries should never change this setting. If an
1909 application uses a library that works incorrectly if floating point time stamps
1910 are processed, this application should turn the feature off until the library
1911 has been corrected.
1912
Victor Stinner034d0aa2012-06-05 01:22:15 +02001913 .. deprecated:: 3.3
1914
Georg Brandl116aa622007-08-15 14:28:22 +00001915
1916.. function:: statvfs(path)
1917
Georg Brandl60203b42010-10-06 10:11:56 +00001918 Perform a :c:func:`statvfs` system call on the given path. The return value is
Georg Brandl116aa622007-08-15 14:28:22 +00001919 an object whose attributes describe the filesystem on the given path, and
Georg Brandl60203b42010-10-06 10:11:56 +00001920 correspond to the members of the :c:type:`statvfs` structure, namely:
Georg Brandl116aa622007-08-15 14:28:22 +00001921 :attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`,
1922 :attr:`f_bavail`, :attr:`f_files`, :attr:`f_ffree`, :attr:`f_favail`,
Benjamin Petersonf650e462010-05-06 23:03:05 +00001923 :attr:`f_flag`, :attr:`f_namemax`.
1924
Andrew M. Kuchling4ea04a32010-08-18 22:30:34 +00001925 Two module-level constants are defined for the :attr:`f_flag` attribute's
1926 bit-flags: if :const:`ST_RDONLY` is set, the filesystem is mounted
1927 read-only, and if :const:`ST_NOSUID` is set, the semantics of
1928 setuid/setgid bits are disabled or not supported.
1929
Georg Brandl50c40002012-06-24 11:45:20 +02001930 This function can support :ref:`specifying a file descriptor <path_fd>`.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001931
Andrew M. Kuchling4ea04a32010-08-18 22:30:34 +00001932 .. versionchanged:: 3.2
1933 The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added.
1934
Benjamin Petersonf650e462010-05-06 23:03:05 +00001935 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001936
Larry Hastings9cf065c2012-06-22 16:30:09 -07001937 .. versionadded:: 3.3
1938 Added support for specifying an open file descriptor for *path*.
Georg Brandl116aa622007-08-15 14:28:22 +00001939
Larry Hastings9cf065c2012-06-22 16:30:09 -07001940
1941.. data:: supports_dir_fd
1942
Georg Brandlaceaf902012-06-25 08:33:56 +02001943 A :class:`~collections.Set` object indicating which functions in the
1944 :mod:`os` module permit use of their *dir_fd* parameter. Different platforms
Larry Hastings9cf065c2012-06-22 16:30:09 -07001945 provide different functionality, and an option that might work on one might
1946 be unsupported on another. For consistency's sakes, functions that support
Andrew Svetlov5b898402012-12-18 21:26:36 +02001947 *dir_fd* always allow specifying the parameter, but will raise an exception
Larry Hastings9cf065c2012-06-22 16:30:09 -07001948 if the functionality is not actually available.
1949
1950 To check whether a particular function permits use of its *dir_fd*
1951 parameter, use the ``in`` operator on ``supports_dir_fd``. As an example,
1952 this expression determines whether the *dir_fd* parameter of :func:`os.stat`
1953 is locally available::
1954
1955 os.stat in os.supports_dir_fd
1956
Georg Brandlf62445a2012-06-24 13:31:20 +02001957 Currently *dir_fd* parameters only work on Unix platforms; none of them work
1958 on Windows.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001959
1960 .. versionadded:: 3.3
1961
Georg Brandl8ccadaa2012-06-24 12:50:06 +02001962
Larry Hastings9cf065c2012-06-22 16:30:09 -07001963.. data:: supports_effective_ids
1964
Georg Brandlaceaf902012-06-25 08:33:56 +02001965 A :class:`~collections.Set` object indicating which functions in the
1966 :mod:`os` module permit use of the *effective_ids* parameter for
1967 :func:`os.access`. If the local platform supports it, the collection will
1968 contain :func:`os.access`, otherwise it will be empty.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001969
Georg Brandl50c40002012-06-24 11:45:20 +02001970 To check whether you can use the *effective_ids* parameter for
Larry Hastings9cf065c2012-06-22 16:30:09 -07001971 :func:`os.access`, use the ``in`` operator on ``supports_dir_fd``, like so::
1972
1973 os.access in os.supports_effective_ids
1974
Georg Brandl50c40002012-06-24 11:45:20 +02001975 Currently *effective_ids* only works on Unix platforms; it does not work on
1976 Windows.
Larry Hastings9cf065c2012-06-22 16:30:09 -07001977
1978 .. versionadded:: 3.3
1979
Georg Brandl8ccadaa2012-06-24 12:50:06 +02001980
Larry Hastings9cf065c2012-06-22 16:30:09 -07001981.. data:: supports_fd
1982
Georg Brandlaceaf902012-06-25 08:33:56 +02001983 A :class:`~collections.Set` object indicating which functions in the
1984 :mod:`os` module permit specifying their *path* parameter as an open file
Larry Hastings9cf065c2012-06-22 16:30:09 -07001985 descriptor. Different platforms provide different functionality, and an
1986 option that might work on one might be unsupported on another. For
1987 consistency's sakes, functions that support *fd* always allow specifying
Andrew Svetlov5b898402012-12-18 21:26:36 +02001988 the parameter, but will raise an exception if the functionality is not
Larry Hastings9cf065c2012-06-22 16:30:09 -07001989 actually available.
1990
1991 To check whether a particular function permits specifying an open file
1992 descriptor for its *path* parameter, use the ``in`` operator on
1993 ``supports_fd``. As an example, this expression determines whether
1994 :func:`os.chdir` accepts open file descriptors when called on your local
1995 platform::
1996
1997 os.chdir in os.supports_fd
1998
1999 .. versionadded:: 3.3
2000
Georg Brandl8ccadaa2012-06-24 12:50:06 +02002001
Larry Hastings9cf065c2012-06-22 16:30:09 -07002002.. data:: supports_follow_symlinks
2003
Georg Brandlaceaf902012-06-25 08:33:56 +02002004 A :class:`~collections.Set` object indicating which functions in the
2005 :mod:`os` module permit use of their *follow_symlinks* parameter. Different
Larry Hastings9cf065c2012-06-22 16:30:09 -07002006 platforms provide different functionality, and an option that might work on
2007 one might be unsupported on another. For consistency's sakes, functions that
2008 support *follow_symlinks* always allow specifying the parameter, but will
Andrew Svetlov5b898402012-12-18 21:26:36 +02002009 raise an exception if the functionality is not actually available.
Larry Hastings9cf065c2012-06-22 16:30:09 -07002010
2011 To check whether a particular function permits use of its *follow_symlinks*
2012 parameter, use the ``in`` operator on ``supports_follow_symlinks``. As an
2013 example, this expression determines whether the *follow_symlinks* parameter
2014 of :func:`os.stat` is locally available::
2015
2016 os.stat in os.supports_follow_symlinks
2017
2018 .. versionadded:: 3.3
2019
Georg Brandl8ccadaa2012-06-24 12:50:06 +02002020
Larry Hastings9cf065c2012-06-22 16:30:09 -07002021.. function:: symlink(source, link_name, target_is_directory=False, *, dir_fd=None)
Georg Brandl116aa622007-08-15 14:28:22 +00002022
Brian Curtinc7395692010-07-09 15:15:09 +00002023 Create a symbolic link pointing to *source* named *link_name*.
2024
Larry Hastings9cf065c2012-06-22 16:30:09 -07002025 On Windows, a symlink represents either a file or a directory, and does not
2026 morph to the target dynamically. If *target_is_directory* is set to ``True``,
2027 the symlink will be created as a directory symlink, otherwise as a file symlink
2028 (the default). On non-Window platforms, *target_is_directory* is ignored.
Brian Curtind40e6f72010-07-08 21:39:08 +00002029
Georg Brandl64a41ed2010-10-06 08:52:48 +00002030 Symbolic link support was introduced in Windows 6.0 (Vista). :func:`symlink`
2031 will raise a :exc:`NotImplementedError` on Windows versions earlier than 6.0.
Brian Curtin52173d42010-12-02 18:29:18 +00002032
Georg Brandl50c40002012-06-24 11:45:20 +02002033 This function can support :ref:`paths relative to directory descriptors
2034 <dir_fd>`.
Larry Hastings9cf065c2012-06-22 16:30:09 -07002035
Brian Curtin52173d42010-12-02 18:29:18 +00002036 .. note::
2037
Larry Hastings9cf065c2012-06-22 16:30:09 -07002038 On Windows, the *SeCreateSymbolicLinkPrivilege* is required in order to
2039 successfully create symlinks. This privilege is not typically granted to
2040 regular users but is available to accounts which can escalate privileges
2041 to the administrator level. Either obtaining the privilege or running your
Brian Curtin96245592010-12-28 17:08:22 +00002042 application as an administrator are ways to successfully create symlinks.
2043
Brian Curtin96245592010-12-28 17:08:22 +00002044 :exc:`OSError` is raised when the function is called by an unprivileged
2045 user.
Brian Curtind40e6f72010-07-08 21:39:08 +00002046
Georg Brandl64a41ed2010-10-06 08:52:48 +00002047 Availability: Unix, Windows.
Brian Curtinc7395692010-07-09 15:15:09 +00002048
Georg Brandlb3823372010-07-10 08:58:37 +00002049 .. versionchanged:: 3.2
2050 Added support for Windows 6.0 (Vista) symbolic links.
Georg Brandl116aa622007-08-15 14:28:22 +00002051
Larry Hastings9cf065c2012-06-22 16:30:09 -07002052 .. versionadded:: 3.3
2053 Added the *dir_fd* argument, and now allow *target_is_directory*
2054 on non-Windows platforms.
2055
Georg Brandl116aa622007-08-15 14:28:22 +00002056
Ross Lagerwall7807c352011-03-17 20:20:30 +02002057.. function:: sync()
2058
2059 Force write of everything to disk.
2060
2061 Availability: Unix.
2062
2063 .. versionadded:: 3.3
2064
2065
2066.. function:: truncate(path, length)
2067
2068 Truncate the file corresponding to *path*, so that it is at most
2069 *length* bytes in size.
2070
Georg Brandl306336b2012-06-24 12:55:33 +02002071 This function can support :ref:`specifying a file descriptor <path_fd>`.
2072
Ross Lagerwall7807c352011-03-17 20:20:30 +02002073 Availability: Unix.
2074
2075 .. versionadded:: 3.3
2076
2077
Larry Hastingsb698d8e2012-06-23 16:55:07 -07002078.. function:: unlink(path, *, dir_fd=None)
Georg Brandl116aa622007-08-15 14:28:22 +00002079
Larry Hastingsb698d8e2012-06-23 16:55:07 -07002080 Remove (delete) the file *path*. This function is identical to
Georg Brandl50c40002012-06-24 11:45:20 +02002081 :func:`remove`; the ``unlink`` name is its traditional Unix
Larry Hastings9cf065c2012-06-22 16:30:09 -07002082 name. Please see the documentation for :func:`remove` for
2083 further information.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002084
2085 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00002086
Larry Hastings9cf065c2012-06-22 16:30:09 -07002087 .. versionadded:: 3.3
Larry Hastingsb698d8e2012-06-23 16:55:07 -07002088 The *dir_fd* parameter.
Georg Brandl116aa622007-08-15 14:28:22 +00002089
Larry Hastings9cf065c2012-06-22 16:30:09 -07002090
2091.. function:: utime(path, times=None, *, ns=None, dir_fd=None, follow_symlinks=True)
Georg Brandl116aa622007-08-15 14:28:22 +00002092
Larry Hastings76ad59b2012-05-03 00:30:07 -07002093 Set the access and modified times of the file specified by *path*.
2094
2095 :func:`utime` takes two optional parameters, *times* and *ns*.
2096 These specify the times set on *path* and are used as follows:
2097
Larry Hastings9cf065c2012-06-22 16:30:09 -07002098 - If *ns* is not ``None``,
Larry Hastings76ad59b2012-05-03 00:30:07 -07002099 it must be a 2-tuple of the form ``(atime_ns, mtime_ns)``
2100 where each member is an int expressing nanoseconds.
Larry Hastings9cf065c2012-06-22 16:30:09 -07002101 - If *times* is not ``None``,
Larry Hastings76ad59b2012-05-03 00:30:07 -07002102 it must be a 2-tuple of the form ``(atime, mtime)``
2103 where each member is an int or float expressing seconds.
Larry Hastings9cf065c2012-06-22 16:30:09 -07002104 - If *times* and *ns* are both ``None``,
2105 this is equivalent to specifying ``ns=(atime_ns, mtime_ns)``
Larry Hastings76ad59b2012-05-03 00:30:07 -07002106 where both times are the current time.
2107 (The effect is similar to running the Unix program
2108 :program:`touch` on *path*.)
Larry Hastings76ad59b2012-05-03 00:30:07 -07002109
Larry Hastings9cf065c2012-06-22 16:30:09 -07002110 It is an error to specify tuples for both *times* and *ns*.
Larry Hastings76ad59b2012-05-03 00:30:07 -07002111
2112 Whether a directory can be given for *path*
Brian Curtin52fbea12011-11-06 13:41:17 -06002113 depends on whether the operating system implements directories as files
2114 (for example, Windows does not). Note that the exact times you set here may
2115 not be returned by a subsequent :func:`~os.stat` call, depending on the
2116 resolution with which your operating system records access and modification
Larry Hastings76ad59b2012-05-03 00:30:07 -07002117 times; see :func:`~os.stat`. The best way to preserve exact times is to
2118 use the *st_atime_ns* and *st_mtime_ns* fields from the :func:`os.stat`
2119 result object with the *ns* parameter to `utime`.
Georg Brandl116aa622007-08-15 14:28:22 +00002120
Georg Brandl50c40002012-06-24 11:45:20 +02002121 This function can support :ref:`specifying a file descriptor <path_fd>`,
2122 :ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not
2123 following symlinks <follow_symlinks>`.
Larry Hastings9cf065c2012-06-22 16:30:09 -07002124
Georg Brandlc575c902008-09-13 17:46:05 +00002125 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00002126
Larry Hastings76ad59b2012-05-03 00:30:07 -07002127 .. versionadded:: 3.3
Larry Hastings9cf065c2012-06-22 16:30:09 -07002128 Added support for specifying an open file descriptor for *path*,
2129 and the *dir_fd*, *follow_symlinks*, and *ns* parameters.
Larry Hastings76ad59b2012-05-03 00:30:07 -07002130
Georg Brandl116aa622007-08-15 14:28:22 +00002131
Georg Brandl18244152009-09-02 20:34:52 +00002132.. function:: walk(top, topdown=True, onerror=None, followlinks=False)
Georg Brandl116aa622007-08-15 14:28:22 +00002133
2134 .. index::
2135 single: directory; walking
2136 single: directory; traversal
2137
Christian Heimesfaf2f632008-01-06 16:59:19 +00002138 Generate the file names in a directory tree by walking the tree
2139 either top-down or bottom-up. For each directory in the tree rooted at directory
Georg Brandl116aa622007-08-15 14:28:22 +00002140 *top* (including *top* itself), it yields a 3-tuple ``(dirpath, dirnames,
2141 filenames)``.
2142
2143 *dirpath* is a string, the path to the directory. *dirnames* is a list of the
2144 names of the subdirectories in *dirpath* (excluding ``'.'`` and ``'..'``).
2145 *filenames* is a list of the names of the non-directory files in *dirpath*.
2146 Note that the names in the lists contain no path components. To get a full path
2147 (which begins with *top*) to a file or directory in *dirpath*, do
2148 ``os.path.join(dirpath, name)``.
2149
Christian Heimesfaf2f632008-01-06 16:59:19 +00002150 If optional argument *topdown* is ``True`` or not specified, the triple for a
Georg Brandl116aa622007-08-15 14:28:22 +00002151 directory is generated before the triples for any of its subdirectories
Christian Heimesfaf2f632008-01-06 16:59:19 +00002152 (directories are generated top-down). If *topdown* is ``False``, the triple for a
Georg Brandl116aa622007-08-15 14:28:22 +00002153 directory is generated after the triples for all of its subdirectories
Christian Heimesfaf2f632008-01-06 16:59:19 +00002154 (directories are generated bottom-up).
Georg Brandl116aa622007-08-15 14:28:22 +00002155
Christian Heimesfaf2f632008-01-06 16:59:19 +00002156 When *topdown* is ``True``, the caller can modify the *dirnames* list in-place
Georg Brandl116aa622007-08-15 14:28:22 +00002157 (perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only
2158 recurse into the subdirectories whose names remain in *dirnames*; this can be
2159 used to prune the search, impose a specific order of visiting, or even to inform
2160 :func:`walk` about directories the caller creates or renames before it resumes
Christian Heimesfaf2f632008-01-06 16:59:19 +00002161 :func:`walk` again. Modifying *dirnames* when *topdown* is ``False`` is
Georg Brandl116aa622007-08-15 14:28:22 +00002162 ineffective, because in bottom-up mode the directories in *dirnames* are
2163 generated before *dirpath* itself is generated.
2164
Ezio Melotti67494f22011-10-18 12:59:39 +03002165 By default, errors from the :func:`listdir` call are ignored. If optional
Georg Brandl116aa622007-08-15 14:28:22 +00002166 argument *onerror* is specified, it should be a function; it will be called with
2167 one argument, an :exc:`OSError` instance. It can report the error to continue
2168 with the walk, or raise the exception to abort the walk. Note that the filename
2169 is available as the ``filename`` attribute of the exception object.
2170
2171 By default, :func:`walk` will not walk down into symbolic links that resolve to
Christian Heimesfaf2f632008-01-06 16:59:19 +00002172 directories. Set *followlinks* to ``True`` to visit directories pointed to by
Georg Brandl116aa622007-08-15 14:28:22 +00002173 symlinks, on systems that support them.
2174
Georg Brandl116aa622007-08-15 14:28:22 +00002175 .. note::
2176
Georg Brandl50c40002012-06-24 11:45:20 +02002177 Be aware that setting *followlinks* to ``True`` can lead to infinite
2178 recursion if a link points to a parent directory of itself. :func:`walk`
2179 does not keep track of the directories it visited already.
Georg Brandl116aa622007-08-15 14:28:22 +00002180
2181 .. note::
2182
2183 If you pass a relative pathname, don't change the current working directory
2184 between resumptions of :func:`walk`. :func:`walk` never changes the current
2185 directory, and assumes that its caller doesn't either.
2186
2187 This example displays the number of bytes taken by non-directory files in each
2188 directory under the starting directory, except that it doesn't look under any
2189 CVS subdirectory::
2190
2191 import os
2192 from os.path import join, getsize
2193 for root, dirs, files in os.walk('python/Lib/email'):
Georg Brandl6911e3c2007-09-04 07:15:32 +00002194 print(root, "consumes", end=" ")
2195 print(sum(getsize(join(root, name)) for name in files), end=" ")
2196 print("bytes in", len(files), "non-directory files")
Georg Brandl116aa622007-08-15 14:28:22 +00002197 if 'CVS' in dirs:
2198 dirs.remove('CVS') # don't visit CVS directories
2199
Christian Heimesfaf2f632008-01-06 16:59:19 +00002200 In the next example, walking the tree bottom-up is essential: :func:`rmdir`
Georg Brandl116aa622007-08-15 14:28:22 +00002201 doesn't allow deleting a directory before the directory is empty::
2202
Christian Heimesfaf2f632008-01-06 16:59:19 +00002203 # Delete everything reachable from the directory named in "top",
Georg Brandl116aa622007-08-15 14:28:22 +00002204 # assuming there are no symbolic links.
2205 # CAUTION: This is dangerous! For example, if top == '/', it
2206 # could delete all your disk files.
2207 import os
2208 for root, dirs, files in os.walk(top, topdown=False):
2209 for name in files:
2210 os.remove(os.path.join(root, name))
2211 for name in dirs:
2212 os.rmdir(os.path.join(root, name))
2213
Georg Brandl116aa622007-08-15 14:28:22 +00002214
Larry Hastingsb4038062012-07-15 10:57:38 -07002215.. function:: fwalk(top='.', topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None)
Charles-François Natali7372b062012-02-05 15:15:38 +01002216
2217 .. index::
2218 single: directory; walking
2219 single: directory; traversal
2220
Eli Benderskyd049d5c2012-02-11 09:52:29 +02002221 This behaves exactly like :func:`walk`, except that it yields a 4-tuple
Larry Hastingsc48fe982012-06-25 04:49:05 -07002222 ``(dirpath, dirnames, filenames, dirfd)``, and it supports ``dir_fd``.
Charles-François Natali7372b062012-02-05 15:15:38 +01002223
2224 *dirpath*, *dirnames* and *filenames* are identical to :func:`walk` output,
2225 and *dirfd* is a file descriptor referring to the directory *dirpath*.
2226
Larry Hastingsc48fe982012-06-25 04:49:05 -07002227 This function always supports :ref:`paths relative to directory descriptors
Larry Hastingsb4038062012-07-15 10:57:38 -07002228 <dir_fd>` and :ref:`not following symlinks <follow_symlinks>`. Note however
Larry Hastings950b76a2012-07-15 17:32:36 -07002229 that, unlike other functions, the :func:`fwalk` default value for
Larry Hastingsb4038062012-07-15 10:57:38 -07002230 *follow_symlinks* is ``False``.
Larry Hastingsc48fe982012-06-25 04:49:05 -07002231
Charles-François Natali7372b062012-02-05 15:15:38 +01002232 .. note::
2233
2234 Since :func:`fwalk` yields file descriptors, those are only valid until
2235 the next iteration step, so you should duplicate them (e.g. with
2236 :func:`dup`) if you want to keep them longer.
2237
2238 This example displays the number of bytes taken by non-directory files in each
2239 directory under the starting directory, except that it doesn't look under any
2240 CVS subdirectory::
2241
2242 import os
2243 for root, dirs, files, rootfd in os.fwalk('python/Lib/email'):
2244 print(root, "consumes", end="")
Hynek Schlawack1729b8f2012-06-24 16:11:08 +02002245 print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]),
Charles-François Natali7372b062012-02-05 15:15:38 +01002246 end="")
2247 print("bytes in", len(files), "non-directory files")
2248 if 'CVS' in dirs:
2249 dirs.remove('CVS') # don't visit CVS directories
2250
2251 In the next example, walking the tree bottom-up is essential:
Victor Stinner69a6ca52012-08-05 15:18:02 +02002252 :func:`rmdir` doesn't allow deleting a directory before the directory is
Charles-François Natali7372b062012-02-05 15:15:38 +01002253 empty::
2254
2255 # Delete everything reachable from the directory named in "top",
2256 # assuming there are no symbolic links.
2257 # CAUTION: This is dangerous! For example, if top == '/', it
2258 # could delete all your disk files.
2259 import os
2260 for root, dirs, files, rootfd in os.fwalk(top, topdown=False):
2261 for name in files:
Victor Stinner69a6ca52012-08-05 15:18:02 +02002262 os.unlink(name, dir_fd=rootfd)
Charles-François Natali7372b062012-02-05 15:15:38 +01002263 for name in dirs:
Victor Stinner69a6ca52012-08-05 15:18:02 +02002264 os.rmdir(name, dir_fd=rootfd)
Charles-François Natali7372b062012-02-05 15:15:38 +01002265
2266 Availability: Unix.
2267
2268 .. versionadded:: 3.3
2269
2270
Georg Brandlb9831ab2012-06-24 11:57:07 +02002271Linux extended attributes
2272~~~~~~~~~~~~~~~~~~~~~~~~~
2273
2274.. versionadded:: 3.3
2275
2276These functions are all available on Linux only.
2277
2278.. function:: getxattr(path, attribute, *, follow_symlinks=True)
2279
2280 Return the value of the extended filesystem attribute *attribute* for
2281 *path*. *attribute* can be bytes or str. If it is str, it is encoded
2282 with the filesystem encoding.
2283
2284 This function can support :ref:`specifying a file descriptor <path_fd>` and
2285 :ref:`not following symlinks <follow_symlinks>`.
2286
2287
2288.. function:: listxattr(path=None, *, follow_symlinks=True)
2289
2290 Return a list of the extended filesystem attributes on *path*. The
2291 attributes in the list are represented as strings decoded with the filesystem
2292 encoding. If *path* is ``None``, :func:`listxattr` will examine the current
2293 directory.
2294
2295 This function can support :ref:`specifying a file descriptor <path_fd>` and
2296 :ref:`not following symlinks <follow_symlinks>`.
2297
2298
2299.. function:: removexattr(path, attribute, *, follow_symlinks=True)
2300
2301 Removes the extended filesystem attribute *attribute* from *path*.
2302 *attribute* should be bytes or str. If it is a string, it is encoded
2303 with the filesystem encoding.
2304
2305 This function can support :ref:`specifying a file descriptor <path_fd>` and
2306 :ref:`not following symlinks <follow_symlinks>`.
2307
2308
2309.. function:: setxattr(path, attribute, value, flags=0, *, follow_symlinks=True)
2310
2311 Set the extended filesystem attribute *attribute* on *path* to *value*.
2312 *attribute* must be a bytes or str with no embedded NULs. If it is a str,
2313 it is encoded with the filesystem encoding. *flags* may be
2314 :data:`XATTR_REPLACE` or :data:`XATTR_CREATE`. If :data:`XATTR_REPLACE` is
2315 given and the attribute does not exist, ``EEXISTS`` will be raised.
2316 If :data:`XATTR_CREATE` is given and the attribute already exists, the
2317 attribute will not be created and ``ENODATA`` will be raised.
2318
2319 This function can support :ref:`specifying a file descriptor <path_fd>` and
2320 :ref:`not following symlinks <follow_symlinks>`.
2321
2322 .. note::
2323
2324 A bug in Linux kernel versions less than 2.6.39 caused the flags argument
2325 to be ignored on some filesystems.
2326
2327
2328.. data:: XATTR_SIZE_MAX
2329
2330 The maximum size the value of an extended attribute can be. Currently, this
Serhiy Storchakaf8def282013-02-16 17:29:56 +02002331 is 64 KiB on Linux.
Georg Brandlb9831ab2012-06-24 11:57:07 +02002332
2333
2334.. data:: XATTR_CREATE
2335
2336 This is a possible value for the flags argument in :func:`setxattr`. It
2337 indicates the operation must create an attribute.
2338
2339
2340.. data:: XATTR_REPLACE
2341
2342 This is a possible value for the flags argument in :func:`setxattr`. It
2343 indicates the operation must replace an existing attribute.
2344
2345
Georg Brandl116aa622007-08-15 14:28:22 +00002346.. _os-process:
2347
2348Process Management
2349------------------
2350
2351These functions may be used to create and manage processes.
2352
2353The various :func:`exec\*` functions take a list of arguments for the new
2354program loaded into the process. In each case, the first of these arguments is
2355passed to the new program as its own name rather than as an argument a user may
2356have typed on a command line. For the C programmer, this is the ``argv[0]``
Georg Brandl60203b42010-10-06 10:11:56 +00002357passed to a program's :c:func:`main`. For example, ``os.execv('/bin/echo',
Georg Brandl116aa622007-08-15 14:28:22 +00002358['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem
2359to be ignored.
2360
2361
2362.. function:: abort()
2363
2364 Generate a :const:`SIGABRT` signal to the current process. On Unix, the default
2365 behavior is to produce a core dump; on Windows, the process immediately returns
Victor Stinner6e2e3b92011-07-08 02:26:39 +02002366 an exit code of ``3``. Be aware that calling this function will not call the
2367 Python signal handler registered for :const:`SIGABRT` with
2368 :func:`signal.signal`.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002369
Georg Brandlc575c902008-09-13 17:46:05 +00002370 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00002371
2372
2373.. function:: execl(path, arg0, arg1, ...)
2374 execle(path, arg0, arg1, ..., env)
2375 execlp(file, arg0, arg1, ...)
2376 execlpe(file, arg0, arg1, ..., env)
2377 execv(path, args)
2378 execve(path, args, env)
2379 execvp(file, args)
2380 execvpe(file, args, env)
2381
2382 These functions all execute a new program, replacing the current process; they
2383 do not return. On Unix, the new executable is loaded into the current process,
Christian Heimesfaf2f632008-01-06 16:59:19 +00002384 and will have the same process id as the caller. Errors will be reported as
Georg Brandl48310cd2009-01-03 21:18:54 +00002385 :exc:`OSError` exceptions.
Benjamin Petersone9bbc8b2008-09-28 02:06:32 +00002386
2387 The current process is replaced immediately. Open file objects and
2388 descriptors are not flushed, so if there may be data buffered
2389 on these open files, you should flush them using
2390 :func:`sys.stdout.flush` or :func:`os.fsync` before calling an
2391 :func:`exec\*` function.
Georg Brandl116aa622007-08-15 14:28:22 +00002392
Christian Heimesfaf2f632008-01-06 16:59:19 +00002393 The "l" and "v" variants of the :func:`exec\*` functions differ in how
2394 command-line arguments are passed. The "l" variants are perhaps the easiest
Georg Brandl116aa622007-08-15 14:28:22 +00002395 to work with if the number of parameters is fixed when the code is written; the
2396 individual parameters simply become additional parameters to the :func:`execl\*`
Christian Heimesfaf2f632008-01-06 16:59:19 +00002397 functions. The "v" variants are good when the number of parameters is
Georg Brandl116aa622007-08-15 14:28:22 +00002398 variable, with the arguments being passed in a list or tuple as the *args*
2399 parameter. In either case, the arguments to the child process should start with
2400 the name of the command being run, but this is not enforced.
2401
Christian Heimesfaf2f632008-01-06 16:59:19 +00002402 The variants which include a "p" near the end (:func:`execlp`,
Georg Brandl116aa622007-08-15 14:28:22 +00002403 :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the
2404 :envvar:`PATH` environment variable to locate the program *file*. When the
2405 environment is being replaced (using one of the :func:`exec\*e` variants,
2406 discussed in the next paragraph), the new environment is used as the source of
2407 the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle`,
2408 :func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable to
2409 locate the executable; *path* must contain an appropriate absolute or relative
2410 path.
2411
2412 For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (note
Christian Heimesfaf2f632008-01-06 16:59:19 +00002413 that these all end in "e"), the *env* parameter must be a mapping which is
Christian Heimesa342c012008-04-20 21:01:16 +00002414 used to define the environment variables for the new process (these are used
2415 instead of the current process' environment); the functions :func:`execl`,
Georg Brandl116aa622007-08-15 14:28:22 +00002416 :func:`execlp`, :func:`execv`, and :func:`execvp` all cause the new process to
Georg Brandl48310cd2009-01-03 21:18:54 +00002417 inherit the environment of the current process.
Benjamin Petersone9bbc8b2008-09-28 02:06:32 +00002418
Larry Hastings9cf065c2012-06-22 16:30:09 -07002419 For :func:`execve` on some platforms, *path* may also be specified as an open
2420 file descriptor. This functionality may not be supported on your platform;
2421 you can check whether or not it is available using :data:`os.supports_fd`.
2422 If it is unavailable, using it will raise a :exc:`NotImplementedError`.
2423
Benjamin Petersone9bbc8b2008-09-28 02:06:32 +00002424 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00002425
Larry Hastings9cf065c2012-06-22 16:30:09 -07002426 .. versionadded:: 3.3
2427 Added support for specifying an open file descriptor for *path*
2428 for :func:`execve`.
Georg Brandl116aa622007-08-15 14:28:22 +00002429
2430.. function:: _exit(n)
2431
Georg Brandl6f4e68d2010-10-17 10:51:45 +00002432 Exit the process with status *n*, without calling cleanup handlers, flushing
Benjamin Petersonf650e462010-05-06 23:03:05 +00002433 stdio buffers, etc.
2434
2435 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00002436
2437 .. note::
2438
Georg Brandl6f4e68d2010-10-17 10:51:45 +00002439 The standard way to exit is ``sys.exit(n)``. :func:`_exit` should
2440 normally only be used in the child process after a :func:`fork`.
Georg Brandl116aa622007-08-15 14:28:22 +00002441
Christian Heimesfaf2f632008-01-06 16:59:19 +00002442The following exit codes are defined and can be used with :func:`_exit`,
Georg Brandl116aa622007-08-15 14:28:22 +00002443although they are not required. These are typically used for system programs
2444written in Python, such as a mail server's external command delivery program.
2445
2446.. note::
2447
2448 Some of these may not be available on all Unix platforms, since there is some
2449 variation. These constants are defined where they are defined by the underlying
2450 platform.
2451
2452
2453.. data:: EX_OK
2454
Benjamin Petersonf650e462010-05-06 23:03:05 +00002455 Exit code that means no error occurred.
2456
2457 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002458
Georg Brandl116aa622007-08-15 14:28:22 +00002459
2460.. data:: EX_USAGE
2461
2462 Exit code that means the command was used incorrectly, such as when the wrong
Benjamin Petersonf650e462010-05-06 23:03:05 +00002463 number of arguments are given.
2464
2465 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002466
Georg Brandl116aa622007-08-15 14:28:22 +00002467
2468.. data:: EX_DATAERR
2469
Benjamin Petersonf650e462010-05-06 23:03:05 +00002470 Exit code that means the input data was incorrect.
2471
2472 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002473
Georg Brandl116aa622007-08-15 14:28:22 +00002474
2475.. data:: EX_NOINPUT
2476
2477 Exit code that means an input file did not exist or was not readable.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002478
Georg Brandlc575c902008-09-13 17:46:05 +00002479 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002480
Georg Brandl116aa622007-08-15 14:28:22 +00002481
2482.. data:: EX_NOUSER
2483
Benjamin Petersonf650e462010-05-06 23:03:05 +00002484 Exit code that means a specified user did not exist.
2485
2486 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002487
Georg Brandl116aa622007-08-15 14:28:22 +00002488
2489.. data:: EX_NOHOST
2490
Benjamin Petersonf650e462010-05-06 23:03:05 +00002491 Exit code that means a specified host did not exist.
2492
2493 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002494
Georg Brandl116aa622007-08-15 14:28:22 +00002495
2496.. data:: EX_UNAVAILABLE
2497
Benjamin Petersonf650e462010-05-06 23:03:05 +00002498 Exit code that means that a required service is unavailable.
2499
2500 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002501
Georg Brandl116aa622007-08-15 14:28:22 +00002502
2503.. data:: EX_SOFTWARE
2504
Benjamin Petersonf650e462010-05-06 23:03:05 +00002505 Exit code that means an internal software error was detected.
2506
2507 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002508
Georg Brandl116aa622007-08-15 14:28:22 +00002509
2510.. data:: EX_OSERR
2511
2512 Exit code that means an operating system error was detected, such as the
Benjamin Petersonf650e462010-05-06 23:03:05 +00002513 inability to fork or create a pipe.
2514
2515 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002516
Georg Brandl116aa622007-08-15 14:28:22 +00002517
2518.. data:: EX_OSFILE
2519
2520 Exit code that means some system file did not exist, could not be opened, or had
Benjamin Petersonf650e462010-05-06 23:03:05 +00002521 some other kind of error.
2522
2523 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002524
Georg Brandl116aa622007-08-15 14:28:22 +00002525
2526.. data:: EX_CANTCREAT
2527
2528 Exit code that means a user specified output file could not be created.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002529
Georg Brandlc575c902008-09-13 17:46:05 +00002530 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002531
Georg Brandl116aa622007-08-15 14:28:22 +00002532
2533.. data:: EX_IOERR
2534
2535 Exit code that means that an error occurred while doing I/O on some file.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002536
Georg Brandlc575c902008-09-13 17:46:05 +00002537 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002538
Georg Brandl116aa622007-08-15 14:28:22 +00002539
2540.. data:: EX_TEMPFAIL
2541
2542 Exit code that means a temporary failure occurred. This indicates something
2543 that may not really be an error, such as a network connection that couldn't be
Benjamin Petersonf650e462010-05-06 23:03:05 +00002544 made during a retryable operation.
2545
2546 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002547
Georg Brandl116aa622007-08-15 14:28:22 +00002548
2549.. data:: EX_PROTOCOL
2550
2551 Exit code that means that a protocol exchange was illegal, invalid, or not
Benjamin Petersonf650e462010-05-06 23:03:05 +00002552 understood.
2553
2554 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002555
Georg Brandl116aa622007-08-15 14:28:22 +00002556
2557.. data:: EX_NOPERM
2558
2559 Exit code that means that there were insufficient permissions to perform the
Benjamin Petersonf650e462010-05-06 23:03:05 +00002560 operation (but not intended for file system problems).
2561
2562 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002563
Georg Brandl116aa622007-08-15 14:28:22 +00002564
2565.. data:: EX_CONFIG
2566
2567 Exit code that means that some kind of configuration error occurred.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002568
Georg Brandlc575c902008-09-13 17:46:05 +00002569 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002570
Georg Brandl116aa622007-08-15 14:28:22 +00002571
2572.. data:: EX_NOTFOUND
2573
Benjamin Petersonf650e462010-05-06 23:03:05 +00002574 Exit code that means something like "an entry was not found".
2575
2576 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002577
Georg Brandl116aa622007-08-15 14:28:22 +00002578
2579.. function:: fork()
2580
Christian Heimesfaf2f632008-01-06 16:59:19 +00002581 Fork a child process. Return ``0`` in the child and the child's process id in the
Christian Heimesdd15f6c2008-03-16 00:07:10 +00002582 parent. If an error occurs :exc:`OSError` is raised.
Benjamin Petersonbcd8ac32008-10-10 22:20:52 +00002583
2584 Note that some platforms including FreeBSD <= 6.3, Cygwin and OS/2 EMX have
2585 known issues when using fork() from a thread.
2586
Georg Brandlc575c902008-09-13 17:46:05 +00002587 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002588
2589
2590.. function:: forkpty()
2591
2592 Fork a child process, using a new pseudo-terminal as the child's controlling
2593 terminal. Return a pair of ``(pid, fd)``, where *pid* is ``0`` in the child, the
2594 new child's process id in the parent, and *fd* is the file descriptor of the
2595 master end of the pseudo-terminal. For a more portable approach, use the
Christian Heimesdd15f6c2008-03-16 00:07:10 +00002596 :mod:`pty` module. If an error occurs :exc:`OSError` is raised.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002597
Georg Brandlc575c902008-09-13 17:46:05 +00002598 Availability: some flavors of Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002599
2600
2601.. function:: kill(pid, sig)
2602
2603 .. index::
2604 single: process; killing
2605 single: process; signalling
2606
2607 Send signal *sig* to the process *pid*. Constants for the specific signals
2608 available on the host platform are defined in the :mod:`signal` module.
Brian Curtineb24d742010-04-12 17:16:38 +00002609
2610 Windows: The :data:`signal.CTRL_C_EVENT` and
2611 :data:`signal.CTRL_BREAK_EVENT` signals are special signals which can
2612 only be sent to console processes which share a common console window,
2613 e.g., some subprocesses. Any other value for *sig* will cause the process
2614 to be unconditionally killed by the TerminateProcess API, and the exit code
2615 will be set to *sig*. The Windows version of :func:`kill` additionally takes
2616 process handles to be killed.
Georg Brandl116aa622007-08-15 14:28:22 +00002617
Victor Stinnerb3e72192011-05-08 01:46:11 +02002618 See also :func:`signal.pthread_kill`.
2619
Georg Brandl67b21b72010-08-17 15:07:14 +00002620 .. versionadded:: 3.2
2621 Windows support.
Brian Curtin904bd392010-04-20 15:28:06 +00002622
Georg Brandl116aa622007-08-15 14:28:22 +00002623
2624.. function:: killpg(pgid, sig)
2625
2626 .. index::
2627 single: process; killing
2628 single: process; signalling
2629
Benjamin Petersonf650e462010-05-06 23:03:05 +00002630 Send the signal *sig* to the process group *pgid*.
2631
2632 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002633
Georg Brandl116aa622007-08-15 14:28:22 +00002634
2635.. function:: nice(increment)
2636
2637 Add *increment* to the process's "niceness". Return the new niceness.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002638
Georg Brandlc575c902008-09-13 17:46:05 +00002639 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002640
2641
2642.. function:: plock(op)
2643
2644 Lock program segments into memory. The value of *op* (defined in
Benjamin Petersonf650e462010-05-06 23:03:05 +00002645 ``<sys/lock.h>``) determines which segments are locked.
2646
2647 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002648
2649
2650.. function:: popen(...)
2651 :noindex:
2652
2653 Run child processes, returning opened pipes for communications. These functions
2654 are described in section :ref:`os-newstreams`.
2655
2656
2657.. function:: spawnl(mode, path, ...)
2658 spawnle(mode, path, ..., env)
2659 spawnlp(mode, file, ...)
2660 spawnlpe(mode, file, ..., env)
2661 spawnv(mode, path, args)
2662 spawnve(mode, path, args, env)
2663 spawnvp(mode, file, args)
2664 spawnvpe(mode, file, args, env)
2665
2666 Execute the program *path* in a new process.
2667
2668 (Note that the :mod:`subprocess` module provides more powerful facilities for
2669 spawning new processes and retrieving their results; using that module is
Benjamin Peterson87c8d872009-06-11 22:54:11 +00002670 preferable to using these functions. Check especially the
2671 :ref:`subprocess-replacements` section.)
Georg Brandl116aa622007-08-15 14:28:22 +00002672
Christian Heimesfaf2f632008-01-06 16:59:19 +00002673 If *mode* is :const:`P_NOWAIT`, this function returns the process id of the new
Georg Brandl116aa622007-08-15 14:28:22 +00002674 process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it
2675 exits normally, or ``-signal``, where *signal* is the signal that killed the
Christian Heimesfaf2f632008-01-06 16:59:19 +00002676 process. On Windows, the process id will actually be the process handle, so can
Georg Brandl116aa622007-08-15 14:28:22 +00002677 be used with the :func:`waitpid` function.
2678
Christian Heimesfaf2f632008-01-06 16:59:19 +00002679 The "l" and "v" variants of the :func:`spawn\*` functions differ in how
2680 command-line arguments are passed. The "l" variants are perhaps the easiest
Georg Brandl116aa622007-08-15 14:28:22 +00002681 to work with if the number of parameters is fixed when the code is written; the
2682 individual parameters simply become additional parameters to the
Christian Heimesfaf2f632008-01-06 16:59:19 +00002683 :func:`spawnl\*` functions. The "v" variants are good when the number of
Georg Brandl116aa622007-08-15 14:28:22 +00002684 parameters is variable, with the arguments being passed in a list or tuple as
2685 the *args* parameter. In either case, the arguments to the child process must
2686 start with the name of the command being run.
2687
Christian Heimesfaf2f632008-01-06 16:59:19 +00002688 The variants which include a second "p" near the end (:func:`spawnlp`,
Georg Brandl116aa622007-08-15 14:28:22 +00002689 :func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the
2690 :envvar:`PATH` environment variable to locate the program *file*. When the
2691 environment is being replaced (using one of the :func:`spawn\*e` variants,
2692 discussed in the next paragraph), the new environment is used as the source of
2693 the :envvar:`PATH` variable. The other variants, :func:`spawnl`,
2694 :func:`spawnle`, :func:`spawnv`, and :func:`spawnve`, will not use the
2695 :envvar:`PATH` variable to locate the executable; *path* must contain an
2696 appropriate absolute or relative path.
2697
2698 For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe`
Christian Heimesfaf2f632008-01-06 16:59:19 +00002699 (note that these all end in "e"), the *env* parameter must be a mapping
Christian Heimesa342c012008-04-20 21:01:16 +00002700 which is used to define the environment variables for the new process (they are
2701 used instead of the current process' environment); the functions
Georg Brandl116aa622007-08-15 14:28:22 +00002702 :func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause
Benjamin Petersond23f8222009-04-05 19:13:16 +00002703 the new process to inherit the environment of the current process. Note that
2704 keys and values in the *env* dictionary must be strings; invalid keys or
2705 values will cause the function to fail, with a return value of ``127``.
Georg Brandl116aa622007-08-15 14:28:22 +00002706
2707 As an example, the following calls to :func:`spawnlp` and :func:`spawnvpe` are
2708 equivalent::
2709
2710 import os
2711 os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')
2712
2713 L = ['cp', 'index.html', '/dev/null']
2714 os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)
2715
2716 Availability: Unix, Windows. :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp`
Antoine Pitrou0e752dd2011-07-19 01:26:58 +02002717 and :func:`spawnvpe` are not available on Windows. :func:`spawnle` and
2718 :func:`spawnve` are not thread-safe on Windows; we advise you to use the
2719 :mod:`subprocess` module instead.
Georg Brandl116aa622007-08-15 14:28:22 +00002720
Georg Brandl116aa622007-08-15 14:28:22 +00002721
2722.. data:: P_NOWAIT
2723 P_NOWAITO
2724
2725 Possible values for the *mode* parameter to the :func:`spawn\*` family of
2726 functions. If either of these values is given, the :func:`spawn\*` functions
Christian Heimesfaf2f632008-01-06 16:59:19 +00002727 will return as soon as the new process has been created, with the process id as
Benjamin Petersonf650e462010-05-06 23:03:05 +00002728 the return value.
2729
2730 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00002731
Georg Brandl116aa622007-08-15 14:28:22 +00002732
2733.. data:: P_WAIT
2734
2735 Possible value for the *mode* parameter to the :func:`spawn\*` family of
2736 functions. If this is given as *mode*, the :func:`spawn\*` functions will not
2737 return until the new process has run to completion and will return the exit code
2738 of the process the run is successful, or ``-signal`` if a signal kills the
Benjamin Petersonf650e462010-05-06 23:03:05 +00002739 process.
2740
2741 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00002742
Georg Brandl116aa622007-08-15 14:28:22 +00002743
2744.. data:: P_DETACH
2745 P_OVERLAY
2746
2747 Possible values for the *mode* parameter to the :func:`spawn\*` family of
2748 functions. These are less portable than those listed above. :const:`P_DETACH`
2749 is similar to :const:`P_NOWAIT`, but the new process is detached from the
2750 console of the calling process. If :const:`P_OVERLAY` is used, the current
2751 process will be replaced; the :func:`spawn\*` function will not return.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002752
Georg Brandl116aa622007-08-15 14:28:22 +00002753 Availability: Windows.
2754
Georg Brandl116aa622007-08-15 14:28:22 +00002755
2756.. function:: startfile(path[, operation])
2757
2758 Start a file with its associated application.
2759
2760 When *operation* is not specified or ``'open'``, this acts like double-clicking
2761 the file in Windows Explorer, or giving the file name as an argument to the
2762 :program:`start` command from the interactive command shell: the file is opened
2763 with whatever application (if any) its extension is associated.
2764
2765 When another *operation* is given, it must be a "command verb" that specifies
2766 what should be done with the file. Common verbs documented by Microsoft are
2767 ``'print'`` and ``'edit'`` (to be used on files) as well as ``'explore'`` and
2768 ``'find'`` (to be used on directories).
2769
2770 :func:`startfile` returns as soon as the associated application is launched.
2771 There is no option to wait for the application to close, and no way to retrieve
2772 the application's exit status. The *path* parameter is relative to the current
2773 directory. If you want to use an absolute path, make sure the first character
Georg Brandl60203b42010-10-06 10:11:56 +00002774 is not a slash (``'/'``); the underlying Win32 :c:func:`ShellExecute` function
Georg Brandl116aa622007-08-15 14:28:22 +00002775 doesn't work if it is. Use the :func:`os.path.normpath` function to ensure that
Benjamin Petersonf650e462010-05-06 23:03:05 +00002776 the path is properly encoded for Win32.
2777
2778 Availability: Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00002779
Georg Brandl116aa622007-08-15 14:28:22 +00002780
2781.. function:: system(command)
2782
2783 Execute the command (a string) in a subshell. This is implemented by calling
Georg Brandl60203b42010-10-06 10:11:56 +00002784 the Standard C function :c:func:`system`, and has the same limitations.
Georg Brandl8f7b4272010-10-14 06:35:53 +00002785 Changes to :data:`sys.stdin`, etc. are not reflected in the environment of
2786 the executed command. If *command* generates any output, it will be sent to
2787 the interpreter standard output stream.
Georg Brandl116aa622007-08-15 14:28:22 +00002788
2789 On Unix, the return value is the exit status of the process encoded in the
Georg Brandl8f7b4272010-10-14 06:35:53 +00002790 format specified for :func:`wait`. Note that POSIX does not specify the
2791 meaning of the return value of the C :c:func:`system` function, so the return
2792 value of the Python function is system-dependent.
Georg Brandl116aa622007-08-15 14:28:22 +00002793
Georg Brandl8f7b4272010-10-14 06:35:53 +00002794 On Windows, the return value is that returned by the system shell after
2795 running *command*. The shell is given by the Windows environment variable
2796 :envvar:`COMSPEC`: it is usually :program:`cmd.exe`, which returns the exit
2797 status of the command run; on systems using a non-native shell, consult your
2798 shell documentation.
Georg Brandl116aa622007-08-15 14:28:22 +00002799
Georg Brandl8f7b4272010-10-14 06:35:53 +00002800 The :mod:`subprocess` module provides more powerful facilities for spawning
2801 new processes and retrieving their results; using that module is preferable
2802 to using this function. See the :ref:`subprocess-replacements` section in
2803 the :mod:`subprocess` documentation for some helpful recipes.
Georg Brandl116aa622007-08-15 14:28:22 +00002804
Benjamin Petersonf650e462010-05-06 23:03:05 +00002805 Availability: Unix, Windows.
2806
Georg Brandl116aa622007-08-15 14:28:22 +00002807
2808.. function:: times()
2809
Larry Hastings605a62d2012-06-24 04:33:36 -07002810 Returns the current global process times.
2811 The return value is an object with five attributes:
2812
2813 * :attr:`user` - user time
2814 * :attr:`system` - system time
2815 * :attr:`children_user` - user time of all child processes
2816 * :attr:`children_system` - system time of all child processes
2817 * :attr:`elapsed` - elapsed real time since a fixed point in the past
2818
2819 For backwards compatibility, this object also behaves like a five-tuple
2820 containing :attr:`user`, :attr:`system`, :attr:`children_user`,
2821 :attr:`children_system`, and :attr:`elapsed` in that order.
2822
2823 See the Unix manual page
Benjamin Petersonf650e462010-05-06 23:03:05 +00002824 :manpage:`times(2)` or the corresponding Windows Platform API documentation.
Larry Hastings605a62d2012-06-24 04:33:36 -07002825 On Windows, only :attr:`user` and :attr:`system` are known; the other
2826 attributes are zero.
2827 On OS/2, only :attr:`elapsed` is known; the other attributes are zero.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002828
Georg Brandl8a5555f2012-06-24 13:29:09 +02002829 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00002830
Larry Hastings605a62d2012-06-24 04:33:36 -07002831 .. versionchanged:: 3.3
2832 Return type changed from a tuple to a tuple-like object
2833 with named attributes.
2834
Georg Brandl116aa622007-08-15 14:28:22 +00002835
2836.. function:: wait()
2837
2838 Wait for completion of a child process, and return a tuple containing its pid
2839 and exit status indication: a 16-bit number, whose low byte is the signal number
2840 that killed the process, and whose high byte is the exit status (if the signal
2841 number is zero); the high bit of the low byte is set if a core file was
Benjamin Petersonf650e462010-05-06 23:03:05 +00002842 produced.
2843
2844 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002845
Ross Lagerwall7807c352011-03-17 20:20:30 +02002846.. function:: waitid(idtype, id, options)
2847
2848 Wait for the completion of one or more child processes.
2849 *idtype* can be :data:`P_PID`, :data:`P_PGID` or :data:`P_ALL`.
2850 *id* specifies the pid to wait on.
2851 *options* is constructed from the ORing of one or more of :data:`WEXITED`,
2852 :data:`WSTOPPED` or :data:`WCONTINUED` and additionally may be ORed with
2853 :data:`WNOHANG` or :data:`WNOWAIT`. The return value is an object
2854 representing the data contained in the :c:type:`siginfo_t` structure, namely:
2855 :attr:`si_pid`, :attr:`si_uid`, :attr:`si_signo`, :attr:`si_status`,
2856 :attr:`si_code` or ``None`` if :data:`WNOHANG` is specified and there are no
2857 children in a waitable state.
2858
2859 Availability: Unix.
2860
2861 .. versionadded:: 3.3
2862
2863.. data:: P_PID
2864 P_PGID
2865 P_ALL
2866
2867 These are the possible values for *idtype* in :func:`waitid`. They affect
2868 how *id* is interpreted.
2869
2870 Availability: Unix.
2871
2872 .. versionadded:: 3.3
2873
2874.. data:: WEXITED
2875 WSTOPPED
2876 WNOWAIT
2877
2878 Flags that can be used in *options* in :func:`waitid` that specify what
2879 child signal to wait for.
2880
2881 Availability: Unix.
2882
2883 .. versionadded:: 3.3
2884
2885
2886.. data:: CLD_EXITED
2887 CLD_DUMPED
2888 CLD_TRAPPED
2889 CLD_CONTINUED
2890
2891 These are the possible values for :attr:`si_code` in the result returned by
2892 :func:`waitid`.
2893
2894 Availability: Unix.
2895
2896 .. versionadded:: 3.3
2897
Georg Brandl116aa622007-08-15 14:28:22 +00002898
2899.. function:: waitpid(pid, options)
2900
2901 The details of this function differ on Unix and Windows.
2902
2903 On Unix: Wait for completion of a child process given by process id *pid*, and
2904 return a tuple containing its process id and exit status indication (encoded as
2905 for :func:`wait`). The semantics of the call are affected by the value of the
2906 integer *options*, which should be ``0`` for normal operation.
2907
2908 If *pid* is greater than ``0``, :func:`waitpid` requests status information for
2909 that specific process. If *pid* is ``0``, the request is for the status of any
2910 child in the process group of the current process. If *pid* is ``-1``, the
2911 request pertains to any child of the current process. If *pid* is less than
2912 ``-1``, status is requested for any process in the process group ``-pid`` (the
2913 absolute value of *pid*).
2914
Benjamin Peterson4cd6a952008-08-17 20:23:46 +00002915 An :exc:`OSError` is raised with the value of errno when the syscall
2916 returns -1.
2917
Georg Brandl116aa622007-08-15 14:28:22 +00002918 On Windows: Wait for completion of a process given by process handle *pid*, and
2919 return a tuple containing *pid*, and its exit status shifted left by 8 bits
2920 (shifting makes cross-platform use of the function easier). A *pid* less than or
2921 equal to ``0`` has no special meaning on Windows, and raises an exception. The
2922 value of integer *options* has no effect. *pid* can refer to any process whose
2923 id is known, not necessarily a child process. The :func:`spawn` functions called
2924 with :const:`P_NOWAIT` return suitable process handles.
2925
2926
Ezio Melottiba4d8ed2012-11-23 19:45:52 +02002927.. function:: wait3(options)
Georg Brandl116aa622007-08-15 14:28:22 +00002928
2929 Similar to :func:`waitpid`, except no process id argument is given and a
2930 3-element tuple containing the child's process id, exit status indication, and
2931 resource usage information is returned. Refer to :mod:`resource`.\
2932 :func:`getrusage` for details on resource usage information. The option
2933 argument is the same as that provided to :func:`waitpid` and :func:`wait4`.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002934
Georg Brandl116aa622007-08-15 14:28:22 +00002935 Availability: Unix.
2936
Georg Brandl116aa622007-08-15 14:28:22 +00002937
Victor Stinner4195b5c2012-02-08 23:03:19 +01002938.. function:: wait4(pid, options)
Georg Brandl116aa622007-08-15 14:28:22 +00002939
2940 Similar to :func:`waitpid`, except a 3-element tuple, containing the child's
2941 process id, exit status indication, and resource usage information is returned.
2942 Refer to :mod:`resource`.\ :func:`getrusage` for details on resource usage
2943 information. The arguments to :func:`wait4` are the same as those provided to
Benjamin Petersonf650e462010-05-06 23:03:05 +00002944 :func:`waitpid`.
2945
2946 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002947
Georg Brandl116aa622007-08-15 14:28:22 +00002948
2949.. data:: WNOHANG
2950
2951 The option for :func:`waitpid` to return immediately if no child process status
2952 is available immediately. The function returns ``(0, 0)`` in this case.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002953
Georg Brandlc575c902008-09-13 17:46:05 +00002954 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002955
2956
2957.. data:: WCONTINUED
2958
2959 This option causes child processes to be reported if they have been continued
Benjamin Petersonf650e462010-05-06 23:03:05 +00002960 from a job control stop since their status was last reported.
2961
Georg Brandl8a5555f2012-06-24 13:29:09 +02002962 Availability: some Unix systems.
Georg Brandl116aa622007-08-15 14:28:22 +00002963
Georg Brandl116aa622007-08-15 14:28:22 +00002964
2965.. data:: WUNTRACED
2966
2967 This option causes child processes to be reported if they have been stopped but
Benjamin Petersonf650e462010-05-06 23:03:05 +00002968 their current state has not been reported since they were stopped.
2969
2970 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002971
Georg Brandl116aa622007-08-15 14:28:22 +00002972
2973The following functions take a process status code as returned by
2974:func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be
2975used to determine the disposition of a process.
2976
Georg Brandl116aa622007-08-15 14:28:22 +00002977.. function:: WCOREDUMP(status)
2978
Christian Heimesfaf2f632008-01-06 16:59:19 +00002979 Return ``True`` if a core dump was generated for the process, otherwise
Benjamin Petersonf650e462010-05-06 23:03:05 +00002980 return ``False``.
2981
2982 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002983
Georg Brandl116aa622007-08-15 14:28:22 +00002984
2985.. function:: WIFCONTINUED(status)
2986
Christian Heimesfaf2f632008-01-06 16:59:19 +00002987 Return ``True`` if the process has been continued from a job control stop,
Benjamin Petersonf650e462010-05-06 23:03:05 +00002988 otherwise return ``False``.
2989
2990 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002991
Georg Brandl116aa622007-08-15 14:28:22 +00002992
2993.. function:: WIFSTOPPED(status)
2994
Christian Heimesfaf2f632008-01-06 16:59:19 +00002995 Return ``True`` if the process has been stopped, otherwise return
Benjamin Petersonf650e462010-05-06 23:03:05 +00002996 ``False``.
2997
2998 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002999
3000
3001.. function:: WIFSIGNALED(status)
3002
Christian Heimesfaf2f632008-01-06 16:59:19 +00003003 Return ``True`` if the process exited due to a signal, otherwise return
Benjamin Petersonf650e462010-05-06 23:03:05 +00003004 ``False``.
3005
3006 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00003007
3008
3009.. function:: WIFEXITED(status)
3010
Christian Heimesfaf2f632008-01-06 16:59:19 +00003011 Return ``True`` if the process exited using the :manpage:`exit(2)` system call,
Benjamin Petersonf650e462010-05-06 23:03:05 +00003012 otherwise return ``False``.
3013
3014 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00003015
3016
3017.. function:: WEXITSTATUS(status)
3018
3019 If ``WIFEXITED(status)`` is true, return the integer parameter to the
3020 :manpage:`exit(2)` system call. Otherwise, the return value is meaningless.
Benjamin Petersonf650e462010-05-06 23:03:05 +00003021
Georg Brandlc575c902008-09-13 17:46:05 +00003022 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00003023
3024
3025.. function:: WSTOPSIG(status)
3026
Benjamin Petersonf650e462010-05-06 23:03:05 +00003027 Return the signal which caused the process to stop.
3028
3029 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00003030
3031
3032.. function:: WTERMSIG(status)
3033
Benjamin Petersonf650e462010-05-06 23:03:05 +00003034 Return the signal which caused the process to exit.
3035
3036 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00003037
3038
Benjamin Peterson94b580d2011-08-02 17:30:04 -05003039Interface to the scheduler
3040--------------------------
3041
3042These functions control how a process is allocated CPU time by the operating
3043system. They are only available on some Unix platforms. For more detailed
3044information, consult your Unix manpages.
3045
3046.. versionadded:: 3.3
3047
3048The following scheduling policies are exposed if they are a supported by the
3049operating system.
3050
3051.. data:: SCHED_OTHER
3052
3053 The default scheduling policy.
3054
3055.. data:: SCHED_BATCH
3056
3057 Scheduling policy for CPU-intensive processes that tries to preserve
3058 interactivity on the rest of the computer.
3059
3060.. data:: SCHED_IDLE
3061
3062 Scheduling policy for extremely low priority background tasks.
3063
3064.. data:: SCHED_SPORADIC
3065
3066 Scheduling policy for sporadic server programs.
3067
3068.. data:: SCHED_FIFO
3069
3070 A First In First Out scheduling policy.
3071
3072.. data:: SCHED_RR
3073
3074 A round-robin scheduling policy.
3075
3076.. data:: SCHED_RESET_ON_FORK
3077
3078 This flag can OR'ed with any other scheduling policy. When a process with
3079 this flag set forks, its child's scheduling policy and priority are reset to
3080 the default.
3081
3082
3083.. class:: sched_param(sched_priority)
3084
3085 This class represents tunable scheduling parameters used in
3086 :func:`sched_setparam`, :func:`sched_setscheduler`, and
3087 :func:`sched_getparam`. It is immutable.
3088
3089 At the moment, there is only one possible parameter:
3090
3091 .. attribute:: sched_priority
3092
3093 The scheduling priority for a scheduling policy.
3094
3095
3096.. function:: sched_get_priority_min(policy)
3097
3098 Get the minimum priority value for *policy*. *policy* is one of the
3099 scheduling policy constants above.
3100
3101
3102.. function:: sched_get_priority_max(policy)
3103
3104 Get the maximum priority value for *policy*. *policy* is one of the
3105 scheduling policy constants above.
3106
3107
3108.. function:: sched_setscheduler(pid, policy, param)
3109
3110 Set the scheduling policy for the process with PID *pid*. A *pid* of 0 means
3111 the calling process. *policy* is one of the scheduling policy constants
3112 above. *param* is a :class:`sched_param` instance.
3113
3114
3115.. function:: sched_getscheduler(pid)
3116
3117 Return the scheduling policy for the process with PID *pid*. A *pid* of 0
3118 means the calling process. The result is one of the scheduling policy
3119 constants above.
3120
3121
3122.. function:: sched_setparam(pid, param)
3123
3124 Set a scheduling parameters for the process with PID *pid*. A *pid* of 0 means
3125 the calling process. *param* is a :class:`sched_param` instance.
3126
3127
3128.. function:: sched_getparam(pid)
3129
3130 Return the scheduling parameters as a :class:`sched_param` instance for the
3131 process with PID *pid*. A *pid* of 0 means the calling process.
3132
3133
3134.. function:: sched_rr_get_interval(pid)
3135
3136 Return the round-robin quantum in seconds for the process with PID *pid*. A
3137 *pid* of 0 means the calling process.
3138
3139
3140.. function:: sched_yield()
3141
3142 Voluntarily relinquish the CPU.
3143
3144
Benjamin Peterson94b580d2011-08-02 17:30:04 -05003145.. function:: sched_setaffinity(pid, mask)
3146
Antoine Pitrou84869872012-08-04 16:16:35 +02003147 Restrict the process with PID *pid* (or the current process if zero) to a
3148 set of CPUs. *mask* is an iterable of integers representing the set of
3149 CPUs to which the process should be restricted.
Benjamin Peterson94b580d2011-08-02 17:30:04 -05003150
3151
Antoine Pitrou84869872012-08-04 16:16:35 +02003152.. function:: sched_getaffinity(pid)
Benjamin Peterson94b580d2011-08-02 17:30:04 -05003153
Antoine Pitrou84869872012-08-04 16:16:35 +02003154 Return the set of CPUs the process with PID *pid* (or the current process
3155 if zero) is restricted to.
Benjamin Peterson94b580d2011-08-02 17:30:04 -05003156
Victor Stinner15f3d1e2012-08-04 20:57:48 +02003157 .. seealso::
3158 :func:`multiprocessing.cpu_count` returns the number of CPUs in the
3159 system.
3160
Benjamin Peterson94b580d2011-08-02 17:30:04 -05003161
Georg Brandl116aa622007-08-15 14:28:22 +00003162.. _os-path:
3163
3164Miscellaneous System Information
3165--------------------------------
3166
3167
3168.. function:: confstr(name)
3169
3170 Return string-valued system configuration values. *name* specifies the
3171 configuration value to retrieve; it may be a string which is the name of a
3172 defined system value; these names are specified in a number of standards (POSIX,
3173 Unix 95, Unix 98, and others). Some platforms define additional names as well.
3174 The names known to the host operating system are given as the keys of the
3175 ``confstr_names`` dictionary. For configuration variables not included in that
Benjamin Petersonf650e462010-05-06 23:03:05 +00003176 mapping, passing an integer for *name* is also accepted.
Georg Brandl116aa622007-08-15 14:28:22 +00003177
3178 If the configuration value specified by *name* isn't defined, ``None`` is
3179 returned.
3180
3181 If *name* is a string and is not known, :exc:`ValueError` is raised. If a
3182 specific value for *name* is not supported by the host system, even if it is
3183 included in ``confstr_names``, an :exc:`OSError` is raised with
3184 :const:`errno.EINVAL` for the error number.
3185
Georg Brandl8a5555f2012-06-24 13:29:09 +02003186 Availability: Unix.
Benjamin Petersonf650e462010-05-06 23:03:05 +00003187
Georg Brandl116aa622007-08-15 14:28:22 +00003188
3189.. data:: confstr_names
3190
3191 Dictionary mapping names accepted by :func:`confstr` to the integer values
3192 defined for those names by the host operating system. This can be used to
Benjamin Petersonf650e462010-05-06 23:03:05 +00003193 determine the set of names known to the system.
3194
3195 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00003196
3197
3198.. function:: getloadavg()
3199
Christian Heimesa62da1d2008-01-12 19:39:10 +00003200 Return the number of processes in the system run queue averaged over the last
3201 1, 5, and 15 minutes or raises :exc:`OSError` if the load average was
Benjamin Petersonf650e462010-05-06 23:03:05 +00003202 unobtainable.
3203
3204 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00003205
Georg Brandl116aa622007-08-15 14:28:22 +00003206
3207.. function:: sysconf(name)
3208
3209 Return integer-valued system configuration values. If the configuration value
3210 specified by *name* isn't defined, ``-1`` is returned. The comments regarding
3211 the *name* parameter for :func:`confstr` apply here as well; the dictionary that
3212 provides information on the known names is given by ``sysconf_names``.
Benjamin Petersonf650e462010-05-06 23:03:05 +00003213
Georg Brandlc575c902008-09-13 17:46:05 +00003214 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00003215
3216
3217.. data:: sysconf_names
3218
3219 Dictionary mapping names accepted by :func:`sysconf` to the integer values
3220 defined for those names by the host operating system. This can be used to
Benjamin Petersonf650e462010-05-06 23:03:05 +00003221 determine the set of names known to the system.
3222
3223 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00003224
Christian Heimesfaf2f632008-01-06 16:59:19 +00003225The following data values are used to support path manipulation operations. These
Georg Brandl116aa622007-08-15 14:28:22 +00003226are defined for all platforms.
3227
3228Higher-level operations on pathnames are defined in the :mod:`os.path` module.
3229
3230
3231.. data:: curdir
3232
3233 The constant string used by the operating system to refer to the current
Georg Brandlc575c902008-09-13 17:46:05 +00003234 directory. This is ``'.'`` for Windows and POSIX. Also available via
3235 :mod:`os.path`.
Georg Brandl116aa622007-08-15 14:28:22 +00003236
3237
3238.. data:: pardir
3239
3240 The constant string used by the operating system to refer to the parent
Georg Brandlc575c902008-09-13 17:46:05 +00003241 directory. This is ``'..'`` for Windows and POSIX. Also available via
3242 :mod:`os.path`.
Georg Brandl116aa622007-08-15 14:28:22 +00003243
3244
3245.. data:: sep
3246
Georg Brandlc575c902008-09-13 17:46:05 +00003247 The character used by the operating system to separate pathname components.
3248 This is ``'/'`` for POSIX and ``'\\'`` for Windows. Note that knowing this
3249 is not sufficient to be able to parse or concatenate pathnames --- use
Georg Brandl116aa622007-08-15 14:28:22 +00003250 :func:`os.path.split` and :func:`os.path.join` --- but it is occasionally
3251 useful. Also available via :mod:`os.path`.
3252
3253
3254.. data:: altsep
3255
3256 An alternative character used by the operating system to separate pathname
3257 components, or ``None`` if only one separator character exists. This is set to
3258 ``'/'`` on Windows systems where ``sep`` is a backslash. Also available via
3259 :mod:`os.path`.
3260
3261
3262.. data:: extsep
3263
3264 The character which separates the base filename from the extension; for example,
3265 the ``'.'`` in :file:`os.py`. Also available via :mod:`os.path`.
3266
Georg Brandl116aa622007-08-15 14:28:22 +00003267
3268.. data:: pathsep
3269
3270 The character conventionally used by the operating system to separate search
3271 path components (as in :envvar:`PATH`), such as ``':'`` for POSIX or ``';'`` for
3272 Windows. Also available via :mod:`os.path`.
3273
3274
3275.. data:: defpath
3276
3277 The default search path used by :func:`exec\*p\*` and :func:`spawn\*p\*` if the
3278 environment doesn't have a ``'PATH'`` key. Also available via :mod:`os.path`.
3279
3280
3281.. data:: linesep
3282
3283 The string used to separate (or, rather, terminate) lines on the current
Georg Brandlc575c902008-09-13 17:46:05 +00003284 platform. This may be a single character, such as ``'\n'`` for POSIX, or
3285 multiple characters, for example, ``'\r\n'`` for Windows. Do not use
3286 *os.linesep* as a line terminator when writing files opened in text mode (the
3287 default); use a single ``'\n'`` instead, on all platforms.
Georg Brandl116aa622007-08-15 14:28:22 +00003288
3289
3290.. data:: devnull
3291
Georg Brandl850a9902010-05-21 22:04:32 +00003292 The file path of the null device. For example: ``'/dev/null'`` for
3293 POSIX, ``'nul'`` for Windows. Also available via :mod:`os.path`.
Georg Brandl116aa622007-08-15 14:28:22 +00003294
Georg Brandl116aa622007-08-15 14:28:22 +00003295
3296.. _os-miscfunc:
3297
3298Miscellaneous Functions
3299-----------------------
3300
3301
3302.. function:: urandom(n)
3303
3304 Return a string of *n* random bytes suitable for cryptographic use.
3305
3306 This function returns random bytes from an OS-specific randomness source. The
3307 returned data should be unpredictable enough for cryptographic applications,
Georg Brandlf62445a2012-06-24 13:31:20 +02003308 though its exact quality depends on the OS implementation. On a Unix-like
Georg Brandl116aa622007-08-15 14:28:22 +00003309 system this will query /dev/urandom, and on Windows it will use CryptGenRandom.
3310 If a randomness source is not found, :exc:`NotImplementedError` will be raised.
Andrew Svetlov03cb99c2012-10-16 13:15:06 +03003311
Andrew Svetlov2bfe3862012-10-16 13:52:25 +03003312 For an easy-to-use interface to the random number generator
3313 provided by your platform, please see :class:`random.SystemRandom`.