blob: a1aaf1e84daf8cb49fabb9bddf0ec46878875646 [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
32.. note::
33
Georg Brandlc575c902008-09-13 17:46:05 +000034 If not separately noted, all functions that claim "Availability: Unix" are
35 supported on Mac OS X, which builds on a Unix core.
36
Benjamin Peterson1baf4652009-12-31 03:11:23 +000037* An "Availability: Unix" note means that this function is commonly found on
38 Unix systems. It does not make any claims about its existence on a specific
39 operating system.
40
41* If not separately noted, all functions that claim "Availability: Unix" are
42 supported on Mac OS X, which builds on a Unix core.
43
Benjamin Petersonf650e462010-05-06 23:03:05 +000044.. Availability notes get their own line and occur at the end of the function
45.. documentation.
46
Georg Brandlc575c902008-09-13 17:46:05 +000047.. note::
48
Christian Heimesa62da1d2008-01-12 19:39:10 +000049 All functions in this module raise :exc:`OSError` in the case of invalid or
50 inaccessible file names and paths, or other arguments that have the correct
51 type, but are not accepted by the operating system.
Georg Brandl116aa622007-08-15 14:28:22 +000052
Georg Brandl116aa622007-08-15 14:28:22 +000053.. exception:: error
54
Christian Heimesa62da1d2008-01-12 19:39:10 +000055 An alias for the built-in :exc:`OSError` exception.
Georg Brandl116aa622007-08-15 14:28:22 +000056
57
58.. data:: name
59
Benjamin Peterson1baf4652009-12-31 03:11:23 +000060 The name of the operating system dependent module imported. The following
61 names have currently been registered: ``'posix'``, ``'nt'``, ``'mac'``,
62 ``'os2'``, ``'ce'``, ``'java'``.
Georg Brandl116aa622007-08-15 14:28:22 +000063
64
Martin v. Löwis011e8422009-05-05 04:43:17 +000065.. _os-filenames:
66
67File Names, Command Line Arguments, and Environment Variables
68-------------------------------------------------------------
69
Georg Brandl67b21b72010-08-17 15:07:14 +000070In Python, file names, command line arguments, and environment variables are
71represented using the string type. On some systems, decoding these strings to
72and from bytes is necessary before passing them to the operating system. Python
73uses the file system encoding to perform this conversion (see
74:func:`sys.getfilesystemencoding`).
Martin v. Löwis011e8422009-05-05 04:43:17 +000075
76.. versionchanged:: 3.1
Georg Brandl67b21b72010-08-17 15:07:14 +000077 On some systems, conversion using the file system encoding may fail. In this
78 case, Python uses the ``surrogateescape`` encoding error handler, which means
79 that undecodable bytes are replaced by a Unicode character U+DCxx on
80 decoding, and these are again translated to the original byte on encoding.
Martin v. Löwis011e8422009-05-05 04:43:17 +000081
82
Georg Brandl67b21b72010-08-17 15:07:14 +000083The file system encoding must guarantee to successfully decode all bytes
84below 128. If the file system encoding fails to provide this guarantee, API
85functions may raise UnicodeErrors.
Martin v. Löwis011e8422009-05-05 04:43:17 +000086
87
Georg Brandl116aa622007-08-15 14:28:22 +000088.. _os-procinfo:
89
90Process Parameters
91------------------
92
93These functions and data items provide information and operate on the current
94process and user.
95
96
97.. data:: environ
98
99 A mapping object representing the string environment. For example,
100 ``environ['HOME']`` is the pathname of your home directory (on some platforms),
101 and is equivalent to ``getenv("HOME")`` in C.
102
103 This mapping is captured the first time the :mod:`os` module is imported,
104 typically during Python startup as part of processing :file:`site.py`. Changes
105 to the environment made after this time are not reflected in ``os.environ``,
106 except for changes made by modifying ``os.environ`` directly.
107
108 If the platform supports the :func:`putenv` function, this mapping may be used
109 to modify the environment as well as query the environment. :func:`putenv` will
110 be called automatically when the mapping is modified.
111
Victor Stinner84ae1182010-05-06 22:05:07 +0000112 On Unix, keys and values use :func:`sys.getfilesystemencoding` and
113 ``'surrogateescape'`` error handler. Use :data:`environb` if you would like
114 to use a different encoding.
115
Georg Brandl116aa622007-08-15 14:28:22 +0000116 .. note::
117
118 Calling :func:`putenv` directly does not change ``os.environ``, so it's better
119 to modify ``os.environ``.
120
121 .. note::
122
Georg Brandlc575c902008-09-13 17:46:05 +0000123 On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
124 cause memory leaks. Refer to the system documentation for
Georg Brandl60203b42010-10-06 10:11:56 +0000125 :c:func:`putenv`.
Georg Brandl116aa622007-08-15 14:28:22 +0000126
127 If :func:`putenv` is not provided, a modified copy of this mapping may be
128 passed to the appropriate process-creation functions to cause child processes
129 to use a modified environment.
130
Georg Brandl9afde1c2007-11-01 20:32:30 +0000131 If the platform supports the :func:`unsetenv` function, you can delete items in
Georg Brandl116aa622007-08-15 14:28:22 +0000132 this mapping to unset environment variables. :func:`unsetenv` will be called
Georg Brandl9afde1c2007-11-01 20:32:30 +0000133 automatically when an item is deleted from ``os.environ``, and when
134 one of the :meth:`pop` or :meth:`clear` methods is called.
135
Georg Brandl116aa622007-08-15 14:28:22 +0000136
Victor Stinner84ae1182010-05-06 22:05:07 +0000137.. data:: environb
138
139 Bytes version of :data:`environ`: a mapping object representing the
140 environment as byte strings. :data:`environ` and :data:`environb` are
141 synchronized (modify :data:`environb` updates :data:`environ`, and vice
142 versa).
143
Victor Stinnerb745a742010-05-18 17:17:23 +0000144 :data:`environb` is only available if :data:`supports_bytes_environ` is
145 True.
Victor Stinner84ae1182010-05-06 22:05:07 +0000146
Benjamin Peterson662c74f2010-05-06 22:09:03 +0000147 .. versionadded:: 3.2
148
Victor Stinner84ae1182010-05-06 22:05:07 +0000149
Georg Brandl116aa622007-08-15 14:28:22 +0000150.. function:: chdir(path)
151 fchdir(fd)
152 getcwd()
153 :noindex:
154
155 These functions are described in :ref:`os-file-dir`.
156
157
Victor Stinnere8d51452010-08-19 01:05:19 +0000158.. function:: fsencode(filename)
Victor Stinner449c4662010-05-08 11:10:09 +0000159
Victor Stinnere8d51452010-08-19 01:05:19 +0000160 Encode *filename* to the filesystem encoding with ``'surrogateescape'``
Victor Stinner62165d62010-10-09 10:34:37 +0000161 error handler, or ``'strict'`` on Windows; return :class:`bytes` unchanged.
Victor Stinnere8d51452010-08-19 01:05:19 +0000162
Antoine Pitroua305ca72010-09-25 22:12:00 +0000163 :func:`fsdecode` is the reverse function.
Victor Stinnere8d51452010-08-19 01:05:19 +0000164
165 .. versionadded:: 3.2
166
167
168.. function:: fsdecode(filename)
169
170 Decode *filename* from the filesystem encoding with ``'surrogateescape'``
Victor Stinner62165d62010-10-09 10:34:37 +0000171 error handler, or ``'strict'`` on Windows; return :class:`str` unchanged.
Victor Stinnere8d51452010-08-19 01:05:19 +0000172
173 :func:`fsencode` is the reverse function.
Victor Stinner449c4662010-05-08 11:10:09 +0000174
175 .. versionadded:: 3.2
176
177
Gregory P. Smithb6e8c7e2010-02-27 07:22:22 +0000178.. function:: get_exec_path(env=None)
179
180 Returns the list of directories that will be searched for a named
181 executable, similar to a shell, when launching a process.
182 *env*, when specified, should be an environment variable dictionary
183 to lookup the PATH in.
184 By default, when *env* is None, :data:`environ` is used.
185
186 .. versionadded:: 3.2
187
188
Georg Brandl116aa622007-08-15 14:28:22 +0000189.. function:: ctermid()
190
191 Return the filename corresponding to the controlling terminal of the process.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000192
Georg Brandl116aa622007-08-15 14:28:22 +0000193 Availability: Unix.
194
195
196.. function:: getegid()
197
198 Return the effective group id of the current process. This corresponds to the
Benjamin Petersonf650e462010-05-06 23:03:05 +0000199 "set id" bit on the file being executed in the current process.
200
201 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000202
203
204.. function:: geteuid()
205
206 .. index:: single: user; effective id
207
Benjamin Petersonf650e462010-05-06 23:03:05 +0000208 Return the current process's effective user id.
209
210 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000211
212
213.. function:: getgid()
214
215 .. index:: single: process; group
216
Benjamin Petersonf650e462010-05-06 23:03:05 +0000217 Return the real group id of the current process.
218
219 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000220
221
222.. function:: getgroups()
223
224 Return list of supplemental group ids associated with the current process.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000225
Georg Brandl116aa622007-08-15 14:28:22 +0000226 Availability: Unix.
227
228
Antoine Pitroub7572f02009-12-02 20:46:48 +0000229.. function:: initgroups(username, gid)
230
231 Call the system initgroups() to initialize the group access list with all of
232 the groups of which the specified username is a member, plus the specified
Benjamin Petersonf650e462010-05-06 23:03:05 +0000233 group id.
234
235 Availability: Unix.
Antoine Pitroub7572f02009-12-02 20:46:48 +0000236
237 .. versionadded:: 3.2
238
239
Georg Brandl116aa622007-08-15 14:28:22 +0000240.. function:: getlogin()
241
242 Return the name of the user logged in on the controlling terminal of the
Brian Curtine8e4b3b2010-09-23 20:04:14 +0000243 process. For most purposes, it is more useful to use the environment variables
244 :envvar:`LOGNAME` or :envvar:`USERNAME` to find out who the user is, or
Georg Brandl116aa622007-08-15 14:28:22 +0000245 ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the currently
Benjamin Petersonf650e462010-05-06 23:03:05 +0000246 effective user id.
247
Brian Curtine8e4b3b2010-09-23 20:04:14 +0000248 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000249
250
251.. function:: getpgid(pid)
252
253 Return the process group id of the process with process id *pid*. If *pid* is 0,
Benjamin Petersonf650e462010-05-06 23:03:05 +0000254 the process group id of the current process is returned.
Georg Brandl116aa622007-08-15 14:28:22 +0000255
Benjamin Petersonf650e462010-05-06 23:03:05 +0000256 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000257
258.. function:: getpgrp()
259
260 .. index:: single: process; group
261
Benjamin Petersonf650e462010-05-06 23:03:05 +0000262 Return the id of the current process group.
263
264 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000265
266
267.. function:: getpid()
268
269 .. index:: single: process; id
270
Benjamin Petersonf650e462010-05-06 23:03:05 +0000271 Return the current process id.
272
273 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000274
275
276.. function:: getppid()
277
278 .. index:: single: process; id of parent
279
Amaury Forgeot d'Arc4b6fdf32010-09-07 21:31:17 +0000280 Return the parent's process id. When the parent process has exited, on Unix
281 the id returned is the one of the init process (1), on Windows it is still
282 the same id, which may be already reused by another process.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000283
Amaury Forgeot d'Arc4b6fdf32010-09-07 21:31:17 +0000284 Availability: Unix, Windows
Georg Brandl116aa622007-08-15 14:28:22 +0000285
Amaury Forgeot d'Arc4b6fdf32010-09-07 21:31:17 +0000286 .. versionchanged:: 3.2
287 Added support for Windows.
Georg Brandl1b83a452009-11-28 11:12:26 +0000288
Gregory P. Smithcf02c6a2009-11-27 17:54:17 +0000289.. function:: getresuid()
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000290
291 Return a tuple (ruid, euid, suid) denoting the current process's
Benjamin Petersonf650e462010-05-06 23:03:05 +0000292 real, effective, and saved user ids.
293
294 Availability: Unix.
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000295
Georg Brandl1b83a452009-11-28 11:12:26 +0000296 .. versionadded:: 3.2
297
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000298
Gregory P. Smithcf02c6a2009-11-27 17:54:17 +0000299.. function:: getresgid()
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000300
301 Return a tuple (rgid, egid, sgid) denoting the current process's
Georg Brandla9b51d22010-09-05 17:07:12 +0000302 real, effective, and saved group ids.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000303
304 Availability: Unix.
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000305
Georg Brandl1b83a452009-11-28 11:12:26 +0000306 .. versionadded:: 3.2
307
Georg Brandl116aa622007-08-15 14:28:22 +0000308
309.. function:: getuid()
310
311 .. index:: single: user; id
312
Benjamin Petersonf650e462010-05-06 23:03:05 +0000313 Return the current process's user id.
314
315 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000316
317
Georg Brandl18244152009-09-02 20:34:52 +0000318.. function:: getenv(key, default=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000319
Georg Brandl18244152009-09-02 20:34:52 +0000320 Return the value of the environment variable *key* if it exists, or
Victor Stinner84ae1182010-05-06 22:05:07 +0000321 *default* if it doesn't. *key*, *default* and the result are str.
Victor Stinner84ae1182010-05-06 22:05:07 +0000322
323 On Unix, keys and values are decoded with :func:`sys.getfilesystemencoding`
324 and ``'surrogateescape'`` error handler. Use :func:`os.getenvb` if you
325 would like to use a different encoding.
326
Benjamin Petersonf650e462010-05-06 23:03:05 +0000327 Availability: most flavors of Unix, Windows.
328
Victor Stinner84ae1182010-05-06 22:05:07 +0000329
330.. function:: getenvb(key, default=None)
331
332 Return the value of the environment variable *key* if it exists, or
333 *default* if it doesn't. *key*, *default* and the result are bytes.
Benjamin Peterson0d6fe512010-05-06 22:13:11 +0000334
Victor Stinner84ae1182010-05-06 22:05:07 +0000335 Availability: most flavors of Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000336
Benjamin Peterson0d6fe512010-05-06 22:13:11 +0000337 .. versionadded:: 3.2
338
Georg Brandl116aa622007-08-15 14:28:22 +0000339
Georg Brandl18244152009-09-02 20:34:52 +0000340.. function:: putenv(key, value)
Georg Brandl116aa622007-08-15 14:28:22 +0000341
342 .. index:: single: environment variables; setting
343
Georg Brandl18244152009-09-02 20:34:52 +0000344 Set the environment variable named *key* to the string *value*. Such
Georg Brandl116aa622007-08-15 14:28:22 +0000345 changes to the environment affect subprocesses started with :func:`os.system`,
Benjamin Petersonf650e462010-05-06 23:03:05 +0000346 :func:`popen` or :func:`fork` and :func:`execv`.
347
348 Availability: most flavors of Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000349
350 .. note::
351
Georg Brandlc575c902008-09-13 17:46:05 +0000352 On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
353 cause memory leaks. Refer to the system documentation for putenv.
Georg Brandl116aa622007-08-15 14:28:22 +0000354
355 When :func:`putenv` is supported, assignments to items in ``os.environ`` are
356 automatically translated into corresponding calls to :func:`putenv`; however,
357 calls to :func:`putenv` don't update ``os.environ``, so it is actually
358 preferable to assign to items of ``os.environ``.
359
360
361.. function:: setegid(egid)
362
Benjamin Petersonf650e462010-05-06 23:03:05 +0000363 Set the current process's effective group id.
364
365 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000366
367
368.. function:: seteuid(euid)
369
Benjamin Petersonf650e462010-05-06 23:03:05 +0000370 Set the current process's effective user id.
371
372 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000373
374
375.. function:: setgid(gid)
376
Benjamin Petersonf650e462010-05-06 23:03:05 +0000377 Set the current process' group id.
378
379 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000380
381
382.. function:: setgroups(groups)
383
384 Set the list of supplemental group ids associated with the current process to
385 *groups*. *groups* must be a sequence, and each element must be an integer
Christian Heimesfaf2f632008-01-06 16:59:19 +0000386 identifying a group. This operation is typically available only to the superuser.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000387
Georg Brandl116aa622007-08-15 14:28:22 +0000388 Availability: Unix.
389
Georg Brandl116aa622007-08-15 14:28:22 +0000390
391.. function:: setpgrp()
392
Georg Brandl60203b42010-10-06 10:11:56 +0000393 Call the system call :c:func:`setpgrp` or :c:func:`setpgrp(0, 0)` depending on
Georg Brandl116aa622007-08-15 14:28:22 +0000394 which version is implemented (if any). See the Unix manual for the semantics.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000395
Georg Brandl116aa622007-08-15 14:28:22 +0000396 Availability: Unix.
397
398
399.. function:: setpgid(pid, pgrp)
400
Georg Brandl60203b42010-10-06 10:11:56 +0000401 Call the system call :c:func:`setpgid` to set the process group id of the
Georg Brandl116aa622007-08-15 14:28:22 +0000402 process with id *pid* to the process group with id *pgrp*. See the Unix manual
Benjamin Petersonf650e462010-05-06 23:03:05 +0000403 for the semantics.
404
405 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000406
407
Georg Brandl116aa622007-08-15 14:28:22 +0000408.. function:: setregid(rgid, egid)
409
Benjamin Petersonf650e462010-05-06 23:03:05 +0000410 Set the current process's real and effective group ids.
411
412 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000413
Georg Brandl1b83a452009-11-28 11:12:26 +0000414
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000415.. function:: setresgid(rgid, egid, sgid)
416
417 Set the current process's real, effective, and saved group ids.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000418
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000419 Availability: Unix.
420
Georg Brandl1b83a452009-11-28 11:12:26 +0000421 .. versionadded:: 3.2
422
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000423
424.. function:: setresuid(ruid, euid, suid)
425
426 Set the current process's real, effective, and saved user ids.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000427
Georg Brandl6faee4e2010-09-21 14:48:28 +0000428 Availability: Unix.
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000429
Georg Brandl1b83a452009-11-28 11:12:26 +0000430 .. versionadded:: 3.2
431
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000432
433.. function:: setreuid(ruid, euid)
434
Benjamin Petersonf650e462010-05-06 23:03:05 +0000435 Set the current process's real and effective user ids.
436
437 Availability: Unix.
Martin v. Löwis7aed61a2009-11-27 14:09:49 +0000438
Georg Brandl116aa622007-08-15 14:28:22 +0000439
440.. function:: getsid(pid)
441
Georg Brandl60203b42010-10-06 10:11:56 +0000442 Call the system call :c:func:`getsid`. See the Unix manual for the semantics.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000443
Georg Brandl116aa622007-08-15 14:28:22 +0000444 Availability: Unix.
445
Georg Brandl116aa622007-08-15 14:28:22 +0000446
447.. function:: setsid()
448
Georg Brandl60203b42010-10-06 10:11:56 +0000449 Call the system call :c:func:`setsid`. See the Unix manual for the semantics.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000450
Georg Brandl116aa622007-08-15 14:28:22 +0000451 Availability: Unix.
452
453
454.. function:: setuid(uid)
455
456 .. index:: single: user; id, setting
457
Benjamin Petersonf650e462010-05-06 23:03:05 +0000458 Set the current process's user id.
459
460 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000461
Georg Brandl116aa622007-08-15 14:28:22 +0000462
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000463.. placed in this section since it relates to errno.... a little weak
Georg Brandl116aa622007-08-15 14:28:22 +0000464.. function:: strerror(code)
465
466 Return the error message corresponding to the error code in *code*.
Georg Brandl60203b42010-10-06 10:11:56 +0000467 On platforms where :c:func:`strerror` returns ``NULL`` when given an unknown
Benjamin Petersonf650e462010-05-06 23:03:05 +0000468 error number, :exc:`ValueError` is raised.
469
470 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000471
472
Victor Stinnerb745a742010-05-18 17:17:23 +0000473.. data:: supports_bytes_environ
474
475 True if the native OS type of the environment is bytes (eg. False on
476 Windows).
477
Victor Stinner8fddc9e2010-05-18 17:24:09 +0000478 .. versionadded:: 3.2
479
Victor Stinnerb745a742010-05-18 17:17:23 +0000480
Georg Brandl116aa622007-08-15 14:28:22 +0000481.. function:: umask(mask)
482
Benjamin Petersonf650e462010-05-06 23:03:05 +0000483 Set the current numeric umask and return the previous umask.
484
485 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000486
487
488.. function:: uname()
489
490 .. index::
491 single: gethostname() (in module socket)
492 single: gethostbyaddr() (in module socket)
493
494 Return a 5-tuple containing information identifying the current operating
495 system. The tuple contains 5 strings: ``(sysname, nodename, release, version,
496 machine)``. Some systems truncate the nodename to 8 characters or to the
497 leading component; a better way to get the hostname is
498 :func:`socket.gethostname` or even
Benjamin Petersonf650e462010-05-06 23:03:05 +0000499 ``socket.gethostbyaddr(socket.gethostname())``.
500
501 Availability: recent flavors of Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000502
503
Georg Brandl18244152009-09-02 20:34:52 +0000504.. function:: unsetenv(key)
Georg Brandl116aa622007-08-15 14:28:22 +0000505
506 .. index:: single: environment variables; deleting
507
Georg Brandl18244152009-09-02 20:34:52 +0000508 Unset (delete) the environment variable named *key*. Such changes to the
Georg Brandl116aa622007-08-15 14:28:22 +0000509 environment affect subprocesses started with :func:`os.system`, :func:`popen` or
Benjamin Petersonf650e462010-05-06 23:03:05 +0000510 :func:`fork` and :func:`execv`.
Georg Brandl116aa622007-08-15 14:28:22 +0000511
512 When :func:`unsetenv` is supported, deletion of items in ``os.environ`` is
513 automatically translated into a corresponding call to :func:`unsetenv`; however,
514 calls to :func:`unsetenv` don't update ``os.environ``, so it is actually
515 preferable to delete items of ``os.environ``.
516
Benjamin Petersonf650e462010-05-06 23:03:05 +0000517 Availability: most flavors of Unix, Windows.
518
Georg Brandl116aa622007-08-15 14:28:22 +0000519
520.. _os-newstreams:
521
522File Object Creation
523--------------------
524
Antoine Pitrou11cb9612010-09-15 11:11:28 +0000525These functions create new :term:`file objects <file object>`. (See also :func:`open`.)
Georg Brandl116aa622007-08-15 14:28:22 +0000526
527
528.. function:: fdopen(fd[, mode[, bufsize]])
529
530 .. index:: single: I/O control; buffering
531
532 Return an open file object connected to the file descriptor *fd*. The *mode*
533 and *bufsize* arguments have the same meaning as the corresponding arguments to
Benjamin Petersonf650e462010-05-06 23:03:05 +0000534 the built-in :func:`open` function.
Georg Brandl116aa622007-08-15 14:28:22 +0000535
Georg Brandl55ac8f02007-09-01 13:51:09 +0000536 When specified, the *mode* argument must start with one of the letters
537 ``'r'``, ``'w'``, or ``'a'``, otherwise a :exc:`ValueError` is raised.
Georg Brandl116aa622007-08-15 14:28:22 +0000538
Georg Brandl55ac8f02007-09-01 13:51:09 +0000539 On Unix, when the *mode* argument starts with ``'a'``, the *O_APPEND* flag is
Georg Brandl60203b42010-10-06 10:11:56 +0000540 set on the file descriptor (which the :c:func:`fdopen` implementation already
Georg Brandl55ac8f02007-09-01 13:51:09 +0000541 does on most platforms).
Georg Brandl116aa622007-08-15 14:28:22 +0000542
Benjamin Petersonf650e462010-05-06 23:03:05 +0000543 Availability: Unix, Windows.
544
Georg Brandl116aa622007-08-15 14:28:22 +0000545
Georg Brandl116aa622007-08-15 14:28:22 +0000546.. _os-fd-ops:
547
548File Descriptor Operations
549--------------------------
550
551These functions operate on I/O streams referenced using file descriptors.
552
553File descriptors are small integers corresponding to a file that has been opened
554by the current process. For example, standard input is usually file descriptor
5550, standard output is 1, and standard error is 2. Further files opened by a
556process will then be assigned 3, 4, 5, and so forth. The name "file descriptor"
557is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
558by file descriptors.
559
Benjamin Peterson08bf91c2010-04-11 16:12:57 +0000560The :meth:`~file.fileno` method can be used to obtain the file descriptor
Antoine Pitrou11cb9612010-09-15 11:11:28 +0000561associated with a :term:`file object` when required. Note that using the file
Benjamin Peterson08bf91c2010-04-11 16:12:57 +0000562descriptor directly will bypass the file object methods, ignoring aspects such
563as internal buffering of data.
Georg Brandl116aa622007-08-15 14:28:22 +0000564
565.. function:: close(fd)
566
Benjamin Petersonf650e462010-05-06 23:03:05 +0000567 Close file descriptor *fd*.
568
569 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000570
571 .. note::
572
573 This function is intended for low-level I/O and must be applied to a file
Benjamin Petersonfa0d7032009-06-01 22:42:33 +0000574 descriptor as returned by :func:`os.open` or :func:`pipe`. To close a "file
Georg Brandl116aa622007-08-15 14:28:22 +0000575 object" returned by the built-in function :func:`open` or by :func:`popen` or
Benjamin Petersonfa0d7032009-06-01 22:42:33 +0000576 :func:`fdopen`, use its :meth:`~file.close` method.
Georg Brandl116aa622007-08-15 14:28:22 +0000577
578
Christian Heimesfdab48e2008-01-20 09:06:41 +0000579.. function:: closerange(fd_low, fd_high)
580
581 Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive),
Benjamin Petersonf650e462010-05-06 23:03:05 +0000582 ignoring errors. Equivalent to::
Christian Heimesfdab48e2008-01-20 09:06:41 +0000583
Georg Brandlc9a5a0e2009-09-01 07:34:27 +0000584 for fd in range(fd_low, fd_high):
Christian Heimesfdab48e2008-01-20 09:06:41 +0000585 try:
586 os.close(fd)
587 except OSError:
588 pass
589
Benjamin Petersonf650e462010-05-06 23:03:05 +0000590 Availability: Unix, Windows.
591
Christian Heimesfdab48e2008-01-20 09:06:41 +0000592
Georg Brandl81f11302007-12-21 08:45:42 +0000593.. function:: device_encoding(fd)
594
595 Return a string describing the encoding of the device associated with *fd*
596 if it is connected to a terminal; else return :const:`None`.
597
598
Georg Brandl116aa622007-08-15 14:28:22 +0000599.. function:: dup(fd)
600
Benjamin Petersonf650e462010-05-06 23:03:05 +0000601 Return a duplicate of file descriptor *fd*.
602
603 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000604
605
606.. function:: dup2(fd, fd2)
607
608 Duplicate file descriptor *fd* to *fd2*, closing the latter first if necessary.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000609
Georg Brandlc575c902008-09-13 17:46:05 +0000610 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000611
612
Christian Heimes4e30a842007-11-30 22:12:06 +0000613.. function:: fchmod(fd, mode)
614
615 Change the mode of the file given by *fd* to the numeric *mode*. See the docs
Benjamin Petersonf650e462010-05-06 23:03:05 +0000616 for :func:`chmod` for possible values of *mode*.
617
618 Availability: Unix.
Christian Heimes4e30a842007-11-30 22:12:06 +0000619
620
621.. function:: fchown(fd, uid, gid)
622
623 Change the owner and group id of the file given by *fd* to the numeric *uid*
624 and *gid*. To leave one of the ids unchanged, set it to -1.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000625
Christian Heimes4e30a842007-11-30 22:12:06 +0000626 Availability: Unix.
627
628
Georg Brandl116aa622007-08-15 14:28:22 +0000629.. function:: fdatasync(fd)
630
631 Force write of file with filedescriptor *fd* to disk. Does not force update of
Benjamin Petersonf650e462010-05-06 23:03:05 +0000632 metadata.
633
634 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000635
Benjamin Petersonfa0d7032009-06-01 22:42:33 +0000636 .. note::
637 This function is not available on MacOS.
638
Georg Brandl116aa622007-08-15 14:28:22 +0000639
640.. function:: fpathconf(fd, name)
641
642 Return system configuration information relevant to an open file. *name*
643 specifies the configuration value to retrieve; it may be a string which is the
644 name of a defined system value; these names are specified in a number of
645 standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define
646 additional names as well. The names known to the host operating system are
647 given in the ``pathconf_names`` dictionary. For configuration variables not
648 included in that mapping, passing an integer for *name* is also accepted.
Georg Brandl116aa622007-08-15 14:28:22 +0000649
650 If *name* is a string and is not known, :exc:`ValueError` is raised. If a
651 specific value for *name* is not supported by the host system, even if it is
652 included in ``pathconf_names``, an :exc:`OSError` is raised with
653 :const:`errno.EINVAL` for the error number.
654
Benjamin Petersonf650e462010-05-06 23:03:05 +0000655 Availability: Unix.
656
Georg Brandl116aa622007-08-15 14:28:22 +0000657
658.. function:: fstat(fd)
659
R. David Murray7b1aae92011-01-24 19:34:58 +0000660 Return status for file descriptor *fd*, like :func:`~os.stat`.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000661
662 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000663
664
665.. function:: fstatvfs(fd)
666
667 Return information about the filesystem containing the file associated with file
Benjamin Petersonf650e462010-05-06 23:03:05 +0000668 descriptor *fd*, like :func:`statvfs`.
669
670 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000671
672
673.. function:: fsync(fd)
674
675 Force write of file with filedescriptor *fd* to disk. On Unix, this calls the
Georg Brandl60203b42010-10-06 10:11:56 +0000676 native :c:func:`fsync` function; on Windows, the MS :c:func:`_commit` function.
Georg Brandl116aa622007-08-15 14:28:22 +0000677
Antoine Pitrou11cb9612010-09-15 11:11:28 +0000678 If you're starting with a buffered Python :term:`file object` *f*, first do
679 ``f.flush()``, and then do ``os.fsync(f.fileno())``, to ensure that all internal
680 buffers associated with *f* are written to disk.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000681
682 Availability: Unix, and Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000683
684
685.. function:: ftruncate(fd, length)
686
687 Truncate the file corresponding to file descriptor *fd*, so that it is at most
Benjamin Petersonf650e462010-05-06 23:03:05 +0000688 *length* bytes in size.
689
690 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000691
692
693.. function:: isatty(fd)
694
695 Return ``True`` if the file descriptor *fd* is open and connected to a
Benjamin Petersonf650e462010-05-06 23:03:05 +0000696 tty(-like) device, else ``False``.
697
698 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000699
700
701.. function:: lseek(fd, pos, how)
702
Christian Heimesfaf2f632008-01-06 16:59:19 +0000703 Set the current position of file descriptor *fd* to position *pos*, modified
704 by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the
705 beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the
706 current position; :const:`os.SEEK_END` or ``2`` to set it relative to the end of
Benjamin Petersonf650e462010-05-06 23:03:05 +0000707 the file.
708
709 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000710
711
Georg Brandl8569e582010-05-19 20:57:08 +0000712.. data:: SEEK_SET
713 SEEK_CUR
714 SEEK_END
715
716 Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
717 respectively. Availability: Windows, Unix.
718
719
Georg Brandl116aa622007-08-15 14:28:22 +0000720.. function:: open(file, flags[, mode])
721
Georg Brandlf4a41232008-05-26 17:55:52 +0000722 Open the file *file* and set various flags according to *flags* and possibly
723 its mode according to *mode*. The default *mode* is ``0o777`` (octal), and
724 the current umask value is first masked out. Return the file descriptor for
Benjamin Petersonf650e462010-05-06 23:03:05 +0000725 the newly opened file.
Georg Brandl116aa622007-08-15 14:28:22 +0000726
727 For a description of the flag and mode values, see the C run-time documentation;
728 flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
Georg Brandl8569e582010-05-19 20:57:08 +0000729 this module too (see :ref:`open-constants`). In particular, on Windows adding
730 :const:`O_BINARY` is needed to open files in binary mode.
Georg Brandl116aa622007-08-15 14:28:22 +0000731
Benjamin Petersonf650e462010-05-06 23:03:05 +0000732 Availability: Unix, Windows.
733
Georg Brandl116aa622007-08-15 14:28:22 +0000734 .. note::
735
Georg Brandl502d9a52009-07-26 15:02:41 +0000736 This function is intended for low-level I/O. For normal usage, use the
Antoine Pitrou11cb9612010-09-15 11:11:28 +0000737 built-in function :func:`open`, which returns a :term:`file object` with
Jeroen Ruigrok van der Werven9c558bc2010-07-13 14:47:01 +0000738 :meth:`~file.read` and :meth:`~file.write` methods (and many more). To
Antoine Pitrou11cb9612010-09-15 11:11:28 +0000739 wrap a file descriptor in a file object, use :func:`fdopen`.
Georg Brandl116aa622007-08-15 14:28:22 +0000740
741
742.. function:: openpty()
743
744 .. index:: module: pty
745
746 Open a new pseudo-terminal pair. Return a pair of file descriptors ``(master,
747 slave)`` for the pty and the tty, respectively. For a (slightly) more portable
Benjamin Petersonf650e462010-05-06 23:03:05 +0000748 approach, use the :mod:`pty` module.
749
750 Availability: some flavors of Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000751
752
753.. function:: pipe()
754
755 Create a pipe. Return a pair of file descriptors ``(r, w)`` usable for reading
Benjamin Petersonf650e462010-05-06 23:03:05 +0000756 and writing, respectively.
757
758 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000759
760
761.. function:: read(fd, n)
762
Georg Brandlb90be692009-07-29 16:14:16 +0000763 Read at most *n* bytes from file descriptor *fd*. Return a bytestring containing the
Georg Brandl116aa622007-08-15 14:28:22 +0000764 bytes read. If the end of the file referred to by *fd* has been reached, an
Benjamin Petersonf650e462010-05-06 23:03:05 +0000765 empty bytes object is returned.
766
767 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000768
769 .. note::
770
771 This function is intended for low-level I/O and must be applied to a file
Benjamin Petersonfa0d7032009-06-01 22:42:33 +0000772 descriptor as returned by :func:`os.open` or :func:`pipe`. To read a "file object"
Georg Brandl116aa622007-08-15 14:28:22 +0000773 returned by the built-in function :func:`open` or by :func:`popen` or
Benjamin Petersonfa0d7032009-06-01 22:42:33 +0000774 :func:`fdopen`, or :data:`sys.stdin`, use its :meth:`~file.read` or
775 :meth:`~file.readline` methods.
Georg Brandl116aa622007-08-15 14:28:22 +0000776
777
Giampaolo Rodolàc9c2c8b2011-02-25 14:39:16 +0000778.. function:: sendfile(out, in, offset, nbytes)
779 sendfile(out, in, offset, nbytes, headers=None, trailers=None, flags=0)
780
781 Copy *nbytes* bytes from file descriptor *in* to file descriptor *out*
782 starting at *offset*.
783 Return the number of bytes sent. When EOF is reached return 0.
784
785 The first function notation is supported by all platforms that define
786 :func:`sendfile`.
787
788 On Linux, if *offset* is given as ``None``, the bytes are read from the
789 current position of *in* and the position of *in* is updated.
790
791 The second case may be used on Mac OS X and FreeBSD where *headers* and
792 *trailers* are arbitrary sequences of buffers that are written before and
793 after the data from *in* is written. It returns the same as the first case.
794
795 On Mac OS X and FreeBSD, a value of 0 for *nbytes* specifies to send until
796 the end of *in* is reached.
797
798 On Solaris, *out* may be the file descriptor of a regular file or the file
799 descriptor of a socket. On all other platforms, *out* must be the file
800 descriptor of an open socket.
801
802 Availability: Unix.
803
804 .. versionadded:: 3.3
805
806
807.. data:: SF_NODISKIO
808 SF_MNOWAIT
809 SF_SYNC
810
811 Parameters to the :func:`sendfile` function, if the implementation supports
812 them.
813
814 Availability: Unix.
815
816 .. versionadded:: 3.3
817
818
Georg Brandl116aa622007-08-15 14:28:22 +0000819.. function:: tcgetpgrp(fd)
820
821 Return the process group associated with the terminal given by *fd* (an open
Benjamin Petersonf650e462010-05-06 23:03:05 +0000822 file descriptor as returned by :func:`os.open`).
823
824 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000825
826
827.. function:: tcsetpgrp(fd, pg)
828
829 Set the process group associated with the terminal given by *fd* (an open file
Benjamin Petersonf650e462010-05-06 23:03:05 +0000830 descriptor as returned by :func:`os.open`) to *pg*.
831
832 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000833
834
835.. function:: ttyname(fd)
836
837 Return a string which specifies the terminal device associated with
Georg Brandl9afde1c2007-11-01 20:32:30 +0000838 file descriptor *fd*. If *fd* is not associated with a terminal device, an
Benjamin Petersonf650e462010-05-06 23:03:05 +0000839 exception is raised.
840
841 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000842
843
844.. function:: write(fd, str)
845
Georg Brandlb90be692009-07-29 16:14:16 +0000846 Write the bytestring in *str* to file descriptor *fd*. Return the number of
Benjamin Petersonf650e462010-05-06 23:03:05 +0000847 bytes actually written.
848
849 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000850
851 .. note::
852
853 This function is intended for low-level I/O and must be applied to a file
Benjamin Petersonfa0d7032009-06-01 22:42:33 +0000854 descriptor as returned by :func:`os.open` or :func:`pipe`. To write a "file
Georg Brandl116aa622007-08-15 14:28:22 +0000855 object" returned by the built-in function :func:`open` or by :func:`popen` or
Benjamin Petersonfa0d7032009-06-01 22:42:33 +0000856 :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
857 :meth:`~file.write` method.
Georg Brandl116aa622007-08-15 14:28:22 +0000858
Georg Brandl8569e582010-05-19 20:57:08 +0000859
860.. _open-constants:
861
862``open()`` flag constants
863~~~~~~~~~~~~~~~~~~~~~~~~~
864
Georg Brandlaf265f42008-12-07 15:06:20 +0000865The following constants are options for the *flags* parameter to the
Benjamin Petersonfa0d7032009-06-01 22:42:33 +0000866:func:`~os.open` function. They can be combined using the bitwise OR operator
Georg Brandlaf265f42008-12-07 15:06:20 +0000867``|``. Some of them are not available on all platforms. For descriptions of
868their availability and use, consult the :manpage:`open(2)` manual page on Unix
Doug Hellmanneb097fc2009-09-20 20:56:56 +0000869or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000870
871
872.. data:: O_RDONLY
873 O_WRONLY
874 O_RDWR
875 O_APPEND
876 O_CREAT
877 O_EXCL
878 O_TRUNC
879
Georg Brandlaf265f42008-12-07 15:06:20 +0000880 These constants are available on Unix and Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000881
882
883.. data:: O_DSYNC
884 O_RSYNC
885 O_SYNC
886 O_NDELAY
887 O_NONBLOCK
888 O_NOCTTY
889 O_SHLOCK
890 O_EXLOCK
891
Georg Brandlaf265f42008-12-07 15:06:20 +0000892 These constants are only available on Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000893
894
895.. data:: O_BINARY
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000896 O_NOINHERIT
Georg Brandl116aa622007-08-15 14:28:22 +0000897 O_SHORT_LIVED
898 O_TEMPORARY
899 O_RANDOM
900 O_SEQUENTIAL
901 O_TEXT
902
Georg Brandlaf265f42008-12-07 15:06:20 +0000903 These constants are only available on Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000904
905
Alexandre Vassalottibee32532008-05-16 18:15:12 +0000906.. data:: O_ASYNC
907 O_DIRECT
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000908 O_DIRECTORY
909 O_NOFOLLOW
910 O_NOATIME
911
Georg Brandlaf265f42008-12-07 15:06:20 +0000912 These constants are GNU extensions and not present if they are not defined by
913 the C library.
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000914
915
Georg Brandl116aa622007-08-15 14:28:22 +0000916.. _os-file-dir:
917
918Files and Directories
919---------------------
920
Georg Brandl116aa622007-08-15 14:28:22 +0000921.. function:: access(path, mode)
922
923 Use the real uid/gid to test for access to *path*. Note that most operations
924 will use the effective uid/gid, therefore this routine can be used in a
925 suid/sgid environment to test if the invoking user has the specified access to
926 *path*. *mode* should be :const:`F_OK` to test the existence of *path*, or it
927 can be the inclusive OR of one or more of :const:`R_OK`, :const:`W_OK`, and
928 :const:`X_OK` to test permissions. Return :const:`True` if access is allowed,
929 :const:`False` if not. See the Unix man page :manpage:`access(2)` for more
Benjamin Petersonf650e462010-05-06 23:03:05 +0000930 information.
931
932 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000933
934 .. note::
935
Georg Brandl502d9a52009-07-26 15:02:41 +0000936 Using :func:`access` to check if a user is authorized to e.g. open a file
937 before actually doing so using :func:`open` creates a security hole,
938 because the user might exploit the short time interval between checking
939 and opening the file to manipulate it.
Georg Brandl116aa622007-08-15 14:28:22 +0000940
941 .. note::
942
943 I/O operations may fail even when :func:`access` indicates that they would
944 succeed, particularly for operations on network filesystems which may have
945 permissions semantics beyond the usual POSIX permission-bit model.
946
947
948.. data:: F_OK
949
950 Value to pass as the *mode* parameter of :func:`access` to test the existence of
951 *path*.
952
953
954.. data:: R_OK
955
956 Value to include in the *mode* parameter of :func:`access` to test the
957 readability of *path*.
958
959
960.. data:: W_OK
961
962 Value to include in the *mode* parameter of :func:`access` to test the
963 writability of *path*.
964
965
966.. data:: X_OK
967
968 Value to include in the *mode* parameter of :func:`access` to determine if
969 *path* can be executed.
970
971
972.. function:: chdir(path)
973
974 .. index:: single: directory; changing
975
Benjamin Petersonf650e462010-05-06 23:03:05 +0000976 Change the current working directory to *path*.
977
978 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000979
980
981.. function:: fchdir(fd)
982
983 Change the current working directory to the directory represented by the file
984 descriptor *fd*. The descriptor must refer to an opened directory, not an open
Benjamin Petersonf650e462010-05-06 23:03:05 +0000985 file.
986
987 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000988
Georg Brandl116aa622007-08-15 14:28:22 +0000989
990.. function:: getcwd()
991
Martin v. Löwis011e8422009-05-05 04:43:17 +0000992 Return a string representing the current working directory.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000993
Martin v. Löwis011e8422009-05-05 04:43:17 +0000994 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000995
Benjamin Petersonf650e462010-05-06 23:03:05 +0000996
Martin v. Löwisa731b992008-10-07 06:36:31 +0000997.. function:: getcwdb()
Georg Brandl116aa622007-08-15 14:28:22 +0000998
Georg Brandl76e55382008-10-08 16:34:57 +0000999 Return a bytestring representing the current working directory.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001000
Georg Brandlc575c902008-09-13 17:46:05 +00001001 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001002
Georg Brandl116aa622007-08-15 14:28:22 +00001003
1004.. function:: chflags(path, flags)
1005
1006 Set the flags of *path* to the numeric *flags*. *flags* may take a combination
1007 (bitwise OR) of the following values (as defined in the :mod:`stat` module):
1008
1009 * ``UF_NODUMP``
1010 * ``UF_IMMUTABLE``
1011 * ``UF_APPEND``
1012 * ``UF_OPAQUE``
1013 * ``UF_NOUNLINK``
1014 * ``SF_ARCHIVED``
1015 * ``SF_IMMUTABLE``
1016 * ``SF_APPEND``
1017 * ``SF_NOUNLINK``
1018 * ``SF_SNAPSHOT``
1019
Georg Brandlc575c902008-09-13 17:46:05 +00001020 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001021
Georg Brandl116aa622007-08-15 14:28:22 +00001022
1023.. function:: chroot(path)
1024
1025 Change the root directory of the current process to *path*. Availability:
Georg Brandlc575c902008-09-13 17:46:05 +00001026 Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001027
Georg Brandl116aa622007-08-15 14:28:22 +00001028
1029.. function:: chmod(path, mode)
1030
1031 Change the mode of *path* to the numeric *mode*. *mode* may take one of the
Christian Heimesfaf2f632008-01-06 16:59:19 +00001032 following values (as defined in the :mod:`stat` module) or bitwise ORed
Georg Brandl116aa622007-08-15 14:28:22 +00001033 combinations of them:
1034
Alexandre Vassalottic22c6f22009-07-21 00:51:58 +00001035 * :data:`stat.S_ISUID`
1036 * :data:`stat.S_ISGID`
1037 * :data:`stat.S_ENFMT`
1038 * :data:`stat.S_ISVTX`
1039 * :data:`stat.S_IREAD`
1040 * :data:`stat.S_IWRITE`
1041 * :data:`stat.S_IEXEC`
1042 * :data:`stat.S_IRWXU`
1043 * :data:`stat.S_IRUSR`
1044 * :data:`stat.S_IWUSR`
1045 * :data:`stat.S_IXUSR`
1046 * :data:`stat.S_IRWXG`
1047 * :data:`stat.S_IRGRP`
1048 * :data:`stat.S_IWGRP`
1049 * :data:`stat.S_IXGRP`
1050 * :data:`stat.S_IRWXO`
1051 * :data:`stat.S_IROTH`
1052 * :data:`stat.S_IWOTH`
1053 * :data:`stat.S_IXOTH`
Georg Brandl116aa622007-08-15 14:28:22 +00001054
Georg Brandlc575c902008-09-13 17:46:05 +00001055 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001056
1057 .. note::
1058
1059 Although Windows supports :func:`chmod`, you can only set the file's read-only
1060 flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD``
1061 constants or a corresponding integer value). All other bits are
1062 ignored.
1063
1064
1065.. function:: chown(path, uid, gid)
1066
1067 Change the owner and group id of *path* to the numeric *uid* and *gid*. To leave
Benjamin Petersonf650e462010-05-06 23:03:05 +00001068 one of the ids unchanged, set it to -1.
1069
1070 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001071
1072
1073.. function:: lchflags(path, flags)
1074
1075 Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do not
Benjamin Petersonf650e462010-05-06 23:03:05 +00001076 follow symbolic links.
1077
1078 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001079
Georg Brandl116aa622007-08-15 14:28:22 +00001080
Christian Heimes93852662007-12-01 12:22:32 +00001081.. function:: lchmod(path, mode)
1082
1083 Change the mode of *path* to the numeric *mode*. If path is a symlink, this
1084 affects the symlink rather than the target. See the docs for :func:`chmod`
Benjamin Petersonf650e462010-05-06 23:03:05 +00001085 for possible values of *mode*.
1086
1087 Availability: Unix.
Christian Heimes93852662007-12-01 12:22:32 +00001088
Christian Heimes93852662007-12-01 12:22:32 +00001089
Georg Brandl116aa622007-08-15 14:28:22 +00001090.. function:: lchown(path, uid, gid)
1091
Christian Heimesfaf2f632008-01-06 16:59:19 +00001092 Change the owner and group id of *path* to the numeric *uid* and *gid*. This
Benjamin Petersonf650e462010-05-06 23:03:05 +00001093 function will not follow symbolic links.
1094
1095 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001096
Georg Brandl116aa622007-08-15 14:28:22 +00001097
Benjamin Peterson5879d412009-03-30 14:51:56 +00001098.. function:: link(source, link_name)
Georg Brandl116aa622007-08-15 14:28:22 +00001099
Benjamin Petersonf650e462010-05-06 23:03:05 +00001100 Create a hard link pointing to *source* named *link_name*.
1101
Brian Curtin1b9df392010-11-24 20:24:31 +00001102 Availability: Unix, Windows.
1103
1104 .. versionchanged:: 3.2
1105 Added Windows support.
Georg Brandl116aa622007-08-15 14:28:22 +00001106
1107
Martin v. Löwis9c71f902010-07-24 10:09:11 +00001108.. function:: listdir(path='.')
Georg Brandl116aa622007-08-15 14:28:22 +00001109
Benjamin Peterson4469d0c2008-11-30 22:46:23 +00001110 Return a list containing the names of the entries in the directory given by
Martin v. Löwis9c71f902010-07-24 10:09:11 +00001111 *path* (default: ``'.'``). The list is in arbitrary order. It does not include the special
Benjamin Peterson4469d0c2008-11-30 22:46:23 +00001112 entries ``'.'`` and ``'..'`` even if they are present in the directory.
Georg Brandl116aa622007-08-15 14:28:22 +00001113
Martin v. Löwis011e8422009-05-05 04:43:17 +00001114 This function can be called with a bytes or string argument, and returns
1115 filenames of the same datatype.
Georg Brandl116aa622007-08-15 14:28:22 +00001116
Benjamin Petersonf650e462010-05-06 23:03:05 +00001117 Availability: Unix, Windows.
1118
Martin v. Löwisc9e1c7d2010-07-23 12:16:41 +00001119 .. versionchanged:: 3.2
1120 The *path* parameter became optional.
Georg Brandl116aa622007-08-15 14:28:22 +00001121
1122.. function:: lstat(path)
1123
R. David Murray7b1aae92011-01-24 19:34:58 +00001124 Perform the equivalent of an :c:func:`lstat` system call on the given path.
1125 Similar to :func:`~os.stat`, but does not follow symbolic links. On
1126 platforms that do not support symbolic links, this is an alias for
1127 :func:`~os.stat`.
Brian Curtinc7395692010-07-09 15:15:09 +00001128
Georg Brandlb3823372010-07-10 08:58:37 +00001129 .. versionchanged:: 3.2
1130 Added support for Windows 6.0 (Vista) symbolic links.
Georg Brandl116aa622007-08-15 14:28:22 +00001131
1132
1133.. function:: mkfifo(path[, mode])
1134
Georg Brandlf4a41232008-05-26 17:55:52 +00001135 Create a FIFO (a named pipe) named *path* with numeric mode *mode*. The
1136 default *mode* is ``0o666`` (octal). The current umask value is first masked
Benjamin Petersonf650e462010-05-06 23:03:05 +00001137 out from the mode.
Georg Brandl116aa622007-08-15 14:28:22 +00001138
1139 FIFOs are pipes that can be accessed like regular files. FIFOs exist until they
1140 are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as
1141 rendezvous between "client" and "server" type processes: the server opens the
1142 FIFO for reading, and the client opens it for writing. Note that :func:`mkfifo`
1143 doesn't open the FIFO --- it just creates the rendezvous point.
1144
Benjamin Petersonf650e462010-05-06 23:03:05 +00001145 Availability: Unix.
1146
Georg Brandl116aa622007-08-15 14:28:22 +00001147
Georg Brandl18244152009-09-02 20:34:52 +00001148.. function:: mknod(filename[, mode=0o600[, device]])
Georg Brandl116aa622007-08-15 14:28:22 +00001149
1150 Create a filesystem node (file, device special file or named pipe) named
Georg Brandl18244152009-09-02 20:34:52 +00001151 *filename*. *mode* specifies both the permissions to use and the type of node
1152 to be created, being combined (bitwise OR) with one of ``stat.S_IFREG``,
1153 ``stat.S_IFCHR``, ``stat.S_IFBLK``, and ``stat.S_IFIFO`` (those constants are
1154 available in :mod:`stat`). For ``stat.S_IFCHR`` and ``stat.S_IFBLK``,
1155 *device* defines the newly created device special file (probably using
Georg Brandl116aa622007-08-15 14:28:22 +00001156 :func:`os.makedev`), otherwise it is ignored.
1157
Georg Brandl116aa622007-08-15 14:28:22 +00001158
1159.. function:: major(device)
1160
Christian Heimesfaf2f632008-01-06 16:59:19 +00001161 Extract the device major number from a raw device number (usually the
Georg Brandl60203b42010-10-06 10:11:56 +00001162 :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`).
Georg Brandl116aa622007-08-15 14:28:22 +00001163
Georg Brandl116aa622007-08-15 14:28:22 +00001164
1165.. function:: minor(device)
1166
Christian Heimesfaf2f632008-01-06 16:59:19 +00001167 Extract the device minor number from a raw device number (usually the
Georg Brandl60203b42010-10-06 10:11:56 +00001168 :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`).
Georg Brandl116aa622007-08-15 14:28:22 +00001169
Georg Brandl116aa622007-08-15 14:28:22 +00001170
1171.. function:: makedev(major, minor)
1172
Christian Heimesfaf2f632008-01-06 16:59:19 +00001173 Compose a raw device number from the major and minor device numbers.
Georg Brandl116aa622007-08-15 14:28:22 +00001174
Georg Brandl116aa622007-08-15 14:28:22 +00001175
1176.. function:: mkdir(path[, mode])
1177
Georg Brandlf4a41232008-05-26 17:55:52 +00001178 Create a directory named *path* with numeric mode *mode*. The default *mode*
1179 is ``0o777`` (octal). On some systems, *mode* is ignored. Where it is used,
Benjamin Petersond7c3ed52010-06-27 22:32:30 +00001180 the current umask value is first masked out. If the directory already
1181 exists, :exc:`OSError` is raised.
Georg Brandl116aa622007-08-15 14:28:22 +00001182
Guido van Rossum2cc30da2007-11-02 23:46:40 +00001183 It is also possible to create temporary directories; see the
1184 :mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
1185
Benjamin Petersonf650e462010-05-06 23:03:05 +00001186 Availability: Unix, Windows.
1187
Georg Brandl116aa622007-08-15 14:28:22 +00001188
Georg Brandlc1673682010-12-02 09:06:12 +00001189.. function:: makedirs(path, mode=0o777, exist_ok=False)
Georg Brandl116aa622007-08-15 14:28:22 +00001190
1191 .. index::
1192 single: directory; creating
1193 single: UNC paths; and os.makedirs()
1194
1195 Recursive directory creation function. Like :func:`mkdir`, but makes all
Terry Reedy5a22b652010-12-02 07:05:56 +00001196 intermediate-level directories needed to contain the leaf directory. If
Georg Brandlc1673682010-12-02 09:06:12 +00001197 the target directory with the same mode as specified already exists,
Terry Reedy5a22b652010-12-02 07:05:56 +00001198 raises an :exc:`OSError` exception if *exist_ok* is False, otherwise no
1199 exception is raised. If the directory cannot be created in other cases,
1200 raises an :exc:`OSError` exception. The default *mode* is ``0o777`` (octal).
Georg Brandlc1673682010-12-02 09:06:12 +00001201 On some systems, *mode* is ignored. Where it is used, the current umask
Terry Reedy5a22b652010-12-02 07:05:56 +00001202 value is first masked out.
Georg Brandl116aa622007-08-15 14:28:22 +00001203
1204 .. note::
1205
Georg Brandlc1673682010-12-02 09:06:12 +00001206 :func:`makedirs` will become confused if the path elements to create
1207 include :data:`pardir`.
Georg Brandl116aa622007-08-15 14:28:22 +00001208
Georg Brandl55ac8f02007-09-01 13:51:09 +00001209 This function handles UNC paths correctly.
Georg Brandl116aa622007-08-15 14:28:22 +00001210
Terry Reedy5a22b652010-12-02 07:05:56 +00001211 .. versionadded:: 3.2
1212 The *exist_ok* parameter.
1213
Georg Brandl116aa622007-08-15 14:28:22 +00001214
1215.. function:: pathconf(path, name)
1216
1217 Return system configuration information relevant to a named file. *name*
1218 specifies the configuration value to retrieve; it may be a string which is the
1219 name of a defined system value; these names are specified in a number of
1220 standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define
1221 additional names as well. The names known to the host operating system are
1222 given in the ``pathconf_names`` dictionary. For configuration variables not
1223 included in that mapping, passing an integer for *name* is also accepted.
Georg Brandl116aa622007-08-15 14:28:22 +00001224
1225 If *name* is a string and is not known, :exc:`ValueError` is raised. If a
1226 specific value for *name* is not supported by the host system, even if it is
1227 included in ``pathconf_names``, an :exc:`OSError` is raised with
1228 :const:`errno.EINVAL` for the error number.
1229
Benjamin Petersonf650e462010-05-06 23:03:05 +00001230 Availability: Unix.
1231
Georg Brandl116aa622007-08-15 14:28:22 +00001232
1233.. data:: pathconf_names
1234
1235 Dictionary mapping names accepted by :func:`pathconf` and :func:`fpathconf` to
1236 the integer values defined for those names by the host operating system. This
1237 can be used to determine the set of names known to the system. Availability:
Georg Brandlc575c902008-09-13 17:46:05 +00001238 Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001239
1240
1241.. function:: readlink(path)
1242
1243 Return a string representing the path to which the symbolic link points. The
1244 result may be either an absolute or relative pathname; if it is relative, it may
1245 be converted to an absolute pathname using ``os.path.join(os.path.dirname(path),
1246 result)``.
1247
Georg Brandl76e55382008-10-08 16:34:57 +00001248 If the *path* is a string object, the result will also be a string object,
1249 and the call may raise an UnicodeDecodeError. If the *path* is a bytes
1250 object, the result will be a bytes object.
Georg Brandl116aa622007-08-15 14:28:22 +00001251
Brian Curtinc7395692010-07-09 15:15:09 +00001252 Availability: Unix, Windows
1253
Georg Brandlb3823372010-07-10 08:58:37 +00001254 .. versionchanged:: 3.2
1255 Added support for Windows 6.0 (Vista) symbolic links.
Georg Brandl116aa622007-08-15 14:28:22 +00001256
1257
1258.. function:: remove(path)
1259
Georg Brandla6053b42009-09-01 08:11:14 +00001260 Remove (delete) the file *path*. If *path* is a directory, :exc:`OSError` is
1261 raised; see :func:`rmdir` below to remove a directory. This is identical to
1262 the :func:`unlink` function documented below. On Windows, attempting to
1263 remove a file that is in use causes an exception to be raised; on Unix, the
1264 directory entry is removed but the storage allocated to the file is not made
Benjamin Petersonf650e462010-05-06 23:03:05 +00001265 available until the original file is no longer in use.
1266
1267 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001268
1269
1270.. function:: removedirs(path)
1271
1272 .. index:: single: directory; deleting
1273
Christian Heimesfaf2f632008-01-06 16:59:19 +00001274 Remove directories recursively. Works like :func:`rmdir` except that, if the
Georg Brandl116aa622007-08-15 14:28:22 +00001275 leaf directory is successfully removed, :func:`removedirs` tries to
1276 successively remove every parent directory mentioned in *path* until an error
1277 is raised (which is ignored, because it generally means that a parent directory
1278 is not empty). For example, ``os.removedirs('foo/bar/baz')`` will first remove
1279 the directory ``'foo/bar/baz'``, and then remove ``'foo/bar'`` and ``'foo'`` if
1280 they are empty. Raises :exc:`OSError` if the leaf directory could not be
1281 successfully removed.
1282
Georg Brandl116aa622007-08-15 14:28:22 +00001283
1284.. function:: rename(src, dst)
1285
1286 Rename the file or directory *src* to *dst*. If *dst* is a directory,
1287 :exc:`OSError` will be raised. On Unix, if *dst* exists and is a file, it will
Christian Heimesfaf2f632008-01-06 16:59:19 +00001288 be replaced silently if the user has permission. The operation may fail on some
Georg Brandl116aa622007-08-15 14:28:22 +00001289 Unix flavors if *src* and *dst* are on different filesystems. If successful,
1290 the renaming will be an atomic operation (this is a POSIX requirement). On
1291 Windows, if *dst* already exists, :exc:`OSError` will be raised even if it is a
1292 file; there may be no way to implement an atomic rename when *dst* names an
Benjamin Petersonf650e462010-05-06 23:03:05 +00001293 existing file.
1294
1295 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001296
1297
1298.. function:: renames(old, new)
1299
1300 Recursive directory or file renaming function. Works like :func:`rename`, except
1301 creation of any intermediate directories needed to make the new pathname good is
1302 attempted first. After the rename, directories corresponding to rightmost path
1303 segments of the old name will be pruned away using :func:`removedirs`.
1304
Georg Brandl116aa622007-08-15 14:28:22 +00001305 .. note::
1306
1307 This function can fail with the new directory structure made if you lack
1308 permissions needed to remove the leaf directory or file.
1309
1310
1311.. function:: rmdir(path)
1312
Georg Brandla6053b42009-09-01 08:11:14 +00001313 Remove (delete) the directory *path*. Only works when the directory is
1314 empty, otherwise, :exc:`OSError` is raised. In order to remove whole
Benjamin Petersonf650e462010-05-06 23:03:05 +00001315 directory trees, :func:`shutil.rmtree` can be used.
1316
1317 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001318
1319
1320.. function:: stat(path)
1321
R. David Murray7b1aae92011-01-24 19:34:58 +00001322 Perform the equivalent of a :c:func:`stat` system call on the given path.
1323 (This function follows symlinks; to stat a symlink use :func:`lstat`.)
Georg Brandl116aa622007-08-15 14:28:22 +00001324
R. David Murray7b1aae92011-01-24 19:34:58 +00001325 The return value is an object whose attributes correspond to the members
1326 of the :c:type:`stat` structure, namely:
1327
1328 * :attr:`st_mode` - protection bits,
1329 * :attr:`st_ino` - inode number,
1330 * :attr:`st_dev` - device,
1331 * :attr:`st_nlink` - number of hard links,
1332 * :attr:`st_uid` - user id of owner,
1333 * :attr:`st_gid` - group id of owner,
1334 * :attr:`st_size` - size of file, in bytes,
1335 * :attr:`st_atime` - time of most recent access,
1336 * :attr:`st_mtime` - time of most recent content modification,
1337 * :attr:`st_ctime` - platform dependent; time of most recent metadata change on
1338 Unix, or the time of creation on Windows)
Georg Brandl116aa622007-08-15 14:28:22 +00001339
1340 On some Unix systems (such as Linux), the following attributes may also be
R. David Murray7b1aae92011-01-24 19:34:58 +00001341 available:
1342
1343 * :attr:`st_blocks` - number of blocks allocated for file
1344 * :attr:`st_blksize` - filesystem blocksize
1345 * :attr:`st_rdev` - type of device if an inode device
1346 * :attr:`st_flags` - user defined flags for file
Georg Brandl116aa622007-08-15 14:28:22 +00001347
1348 On other Unix systems (such as FreeBSD), the following attributes may be
R. David Murray7b1aae92011-01-24 19:34:58 +00001349 available (but may be only filled out if root tries to use them):
1350
1351 * :attr:`st_gen` - file generation number
1352 * :attr:`st_birthtime` - time of file creation
Georg Brandl116aa622007-08-15 14:28:22 +00001353
1354 On Mac OS systems, the following attributes may also be available:
Georg Brandl116aa622007-08-15 14:28:22 +00001355
R. David Murray7b1aae92011-01-24 19:34:58 +00001356 * :attr:`st_rsize`
1357 * :attr:`st_creator`
1358 * :attr:`st_type`
Georg Brandl116aa622007-08-15 14:28:22 +00001359
1360 .. note::
1361
1362 The exact meaning and resolution of the :attr:`st_atime`, :attr:`st_mtime`, and
1363 :attr:`st_ctime` members depends on the operating system and the file system.
1364 For example, on Windows systems using the FAT or FAT32 file systems,
1365 :attr:`st_mtime` has 2-second resolution, and :attr:`st_atime` has only 1-day
1366 resolution. See your operating system documentation for details.
1367
R. David Murray7b1aae92011-01-24 19:34:58 +00001368 For backward compatibility, the return value of :func:`~os.stat` is also accessible
1369 as a tuple of at least 10 integers giving the most important (and portable)
1370 members of the :c:type:`stat` structure, in the order :attr:`st_mode`,
1371 :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`,
1372 :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`,
1373 :attr:`st_ctime`. More items may be added at the end by some implementations.
1374
1375 .. index:: module: stat
1376
1377 The standard module :mod:`stat` defines functions and constants that are useful
1378 for extracting information from a :c:type:`stat` structure. (On Windows, some
1379 items are filled with dummy values.)
1380
1381 Example::
1382
1383 >>> import os
1384 >>> statinfo = os.stat('somefile.txt')
1385 >>> statinfo
Raymond Hettinger8f0ae9a2011-02-18 00:53:55 +00001386 posix.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,
1387 st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,
1388 st_mtime=1297230027, st_ctime=1297230027)
R. David Murray7b1aae92011-01-24 19:34:58 +00001389 >>> statinfo.st_size
Raymond Hettinger8f0ae9a2011-02-18 00:53:55 +00001390 264
R. David Murray7b1aae92011-01-24 19:34:58 +00001391
Georg Brandlc575c902008-09-13 17:46:05 +00001392 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001393
Georg Brandl116aa622007-08-15 14:28:22 +00001394
1395.. function:: stat_float_times([newvalue])
1396
1397 Determine whether :class:`stat_result` represents time stamps as float objects.
R. David Murray7b1aae92011-01-24 19:34:58 +00001398 If *newvalue* is ``True``, future calls to :func:`~os.stat` return floats, if it is
Georg Brandl116aa622007-08-15 14:28:22 +00001399 ``False``, future calls return ints. If *newvalue* is omitted, return the
1400 current setting.
1401
1402 For compatibility with older Python versions, accessing :class:`stat_result` as
1403 a tuple always returns integers.
1404
Georg Brandl55ac8f02007-09-01 13:51:09 +00001405 Python now returns float values by default. Applications which do not work
1406 correctly with floating point time stamps can use this function to restore the
1407 old behaviour.
Georg Brandl116aa622007-08-15 14:28:22 +00001408
1409 The resolution of the timestamps (that is the smallest possible fraction)
1410 depends on the system. Some systems only support second resolution; on these
1411 systems, the fraction will always be zero.
1412
1413 It is recommended that this setting is only changed at program startup time in
1414 the *__main__* module; libraries should never change this setting. If an
1415 application uses a library that works incorrectly if floating point time stamps
1416 are processed, this application should turn the feature off until the library
1417 has been corrected.
1418
1419
1420.. function:: statvfs(path)
1421
Georg Brandl60203b42010-10-06 10:11:56 +00001422 Perform a :c:func:`statvfs` system call on the given path. The return value is
Georg Brandl116aa622007-08-15 14:28:22 +00001423 an object whose attributes describe the filesystem on the given path, and
Georg Brandl60203b42010-10-06 10:11:56 +00001424 correspond to the members of the :c:type:`statvfs` structure, namely:
Georg Brandl116aa622007-08-15 14:28:22 +00001425 :attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`,
1426 :attr:`f_bavail`, :attr:`f_files`, :attr:`f_ffree`, :attr:`f_favail`,
Benjamin Petersonf650e462010-05-06 23:03:05 +00001427 :attr:`f_flag`, :attr:`f_namemax`.
1428
Andrew M. Kuchling4ea04a32010-08-18 22:30:34 +00001429 Two module-level constants are defined for the :attr:`f_flag` attribute's
1430 bit-flags: if :const:`ST_RDONLY` is set, the filesystem is mounted
1431 read-only, and if :const:`ST_NOSUID` is set, the semantics of
1432 setuid/setgid bits are disabled or not supported.
1433
1434 .. versionchanged:: 3.2
1435 The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added.
1436
Benjamin Petersonf650e462010-05-06 23:03:05 +00001437 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001438
Georg Brandl116aa622007-08-15 14:28:22 +00001439
Benjamin Peterson5879d412009-03-30 14:51:56 +00001440.. function:: symlink(source, link_name)
Georg Brandl64a41ed2010-10-06 08:52:48 +00001441 symlink(source, link_name, target_is_directory=False)
Georg Brandl116aa622007-08-15 14:28:22 +00001442
Brian Curtinc7395692010-07-09 15:15:09 +00001443 Create a symbolic link pointing to *source* named *link_name*.
1444
Georg Brandl64a41ed2010-10-06 08:52:48 +00001445 On Windows, symlink version takes an additional optional parameter,
1446 *target_is_directory*, which defaults to ``False``.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001447
Georg Brandl64a41ed2010-10-06 08:52:48 +00001448 On Windows, a symlink represents a file or a directory, and does not morph to
1449 the target dynamically. For this reason, when creating a symlink on Windows,
1450 if the target is not already present, the symlink will default to being a
1451 file symlink. If *target_is_directory* is set to ``True``, the symlink will
1452 be created as a directory symlink. This parameter is ignored if the target
1453 exists (and the symlink is created with the same type as the target).
Brian Curtind40e6f72010-07-08 21:39:08 +00001454
Georg Brandl64a41ed2010-10-06 08:52:48 +00001455 Symbolic link support was introduced in Windows 6.0 (Vista). :func:`symlink`
1456 will raise a :exc:`NotImplementedError` on Windows versions earlier than 6.0.
Brian Curtin52173d42010-12-02 18:29:18 +00001457
1458 .. note::
1459
Brian Curtin96245592010-12-28 17:08:22 +00001460 The *SeCreateSymbolicLinkPrivilege* is required in order to successfully
1461 create symlinks. This privilege is not typically granted to regular
1462 users but is available to accounts which can escalate privileges to the
1463 administrator level. Either obtaining the privilege or running your
1464 application as an administrator are ways to successfully create symlinks.
1465
1466
1467 :exc:`OSError` is raised when the function is called by an unprivileged
1468 user.
Brian Curtind40e6f72010-07-08 21:39:08 +00001469
Georg Brandl64a41ed2010-10-06 08:52:48 +00001470 Availability: Unix, Windows.
Brian Curtinc7395692010-07-09 15:15:09 +00001471
Georg Brandlb3823372010-07-10 08:58:37 +00001472 .. versionchanged:: 3.2
1473 Added support for Windows 6.0 (Vista) symbolic links.
Georg Brandl116aa622007-08-15 14:28:22 +00001474
1475
Georg Brandl116aa622007-08-15 14:28:22 +00001476.. function:: unlink(path)
1477
Georg Brandla6053b42009-09-01 08:11:14 +00001478 Remove (delete) the file *path*. This is the same function as
1479 :func:`remove`; the :func:`unlink` name is its traditional Unix
Benjamin Petersonf650e462010-05-06 23:03:05 +00001480 name.
1481
1482 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001483
1484
1485.. function:: utime(path, times)
1486
Benjamin Peterson4cd6a952008-08-17 20:23:46 +00001487 Set the access and modified times of the file specified by *path*. If *times*
1488 is ``None``, then the file's access and modified times are set to the current
1489 time. (The effect is similar to running the Unix program :program:`touch` on
1490 the path.) Otherwise, *times* must be a 2-tuple of numbers, of the form
1491 ``(atime, mtime)`` which is used to set the access and modified times,
1492 respectively. Whether a directory can be given for *path* depends on whether
1493 the operating system implements directories as files (for example, Windows
1494 does not). Note that the exact times you set here may not be returned by a
R. David Murray7b1aae92011-01-24 19:34:58 +00001495 subsequent :func:`~os.stat` call, depending on the resolution with which your
1496 operating system records access and modification times; see :func:`~os.stat`.
Georg Brandl116aa622007-08-15 14:28:22 +00001497
Georg Brandlc575c902008-09-13 17:46:05 +00001498 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001499
1500
Georg Brandl18244152009-09-02 20:34:52 +00001501.. function:: walk(top, topdown=True, onerror=None, followlinks=False)
Georg Brandl116aa622007-08-15 14:28:22 +00001502
1503 .. index::
1504 single: directory; walking
1505 single: directory; traversal
1506
Christian Heimesfaf2f632008-01-06 16:59:19 +00001507 Generate the file names in a directory tree by walking the tree
1508 either top-down or bottom-up. For each directory in the tree rooted at directory
Georg Brandl116aa622007-08-15 14:28:22 +00001509 *top* (including *top* itself), it yields a 3-tuple ``(dirpath, dirnames,
1510 filenames)``.
1511
1512 *dirpath* is a string, the path to the directory. *dirnames* is a list of the
1513 names of the subdirectories in *dirpath* (excluding ``'.'`` and ``'..'``).
1514 *filenames* is a list of the names of the non-directory files in *dirpath*.
1515 Note that the names in the lists contain no path components. To get a full path
1516 (which begins with *top*) to a file or directory in *dirpath*, do
1517 ``os.path.join(dirpath, name)``.
1518
Christian Heimesfaf2f632008-01-06 16:59:19 +00001519 If optional argument *topdown* is ``True`` or not specified, the triple for a
Georg Brandl116aa622007-08-15 14:28:22 +00001520 directory is generated before the triples for any of its subdirectories
Christian Heimesfaf2f632008-01-06 16:59:19 +00001521 (directories are generated top-down). If *topdown* is ``False``, the triple for a
Georg Brandl116aa622007-08-15 14:28:22 +00001522 directory is generated after the triples for all of its subdirectories
Christian Heimesfaf2f632008-01-06 16:59:19 +00001523 (directories are generated bottom-up).
Georg Brandl116aa622007-08-15 14:28:22 +00001524
Christian Heimesfaf2f632008-01-06 16:59:19 +00001525 When *topdown* is ``True``, the caller can modify the *dirnames* list in-place
Georg Brandl116aa622007-08-15 14:28:22 +00001526 (perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only
1527 recurse into the subdirectories whose names remain in *dirnames*; this can be
1528 used to prune the search, impose a specific order of visiting, or even to inform
1529 :func:`walk` about directories the caller creates or renames before it resumes
Christian Heimesfaf2f632008-01-06 16:59:19 +00001530 :func:`walk` again. Modifying *dirnames* when *topdown* is ``False`` is
Georg Brandl116aa622007-08-15 14:28:22 +00001531 ineffective, because in bottom-up mode the directories in *dirnames* are
1532 generated before *dirpath* itself is generated.
1533
Christian Heimesfaf2f632008-01-06 16:59:19 +00001534 By default errors from the :func:`listdir` call are ignored. If optional
Georg Brandl116aa622007-08-15 14:28:22 +00001535 argument *onerror* is specified, it should be a function; it will be called with
1536 one argument, an :exc:`OSError` instance. It can report the error to continue
1537 with the walk, or raise the exception to abort the walk. Note that the filename
1538 is available as the ``filename`` attribute of the exception object.
1539
1540 By default, :func:`walk` will not walk down into symbolic links that resolve to
Christian Heimesfaf2f632008-01-06 16:59:19 +00001541 directories. Set *followlinks* to ``True`` to visit directories pointed to by
Georg Brandl116aa622007-08-15 14:28:22 +00001542 symlinks, on systems that support them.
1543
Georg Brandl116aa622007-08-15 14:28:22 +00001544 .. note::
1545
Christian Heimesfaf2f632008-01-06 16:59:19 +00001546 Be aware that setting *followlinks* to ``True`` can lead to infinite recursion if a
Georg Brandl116aa622007-08-15 14:28:22 +00001547 link points to a parent directory of itself. :func:`walk` does not keep track of
1548 the directories it visited already.
1549
1550 .. note::
1551
1552 If you pass a relative pathname, don't change the current working directory
1553 between resumptions of :func:`walk`. :func:`walk` never changes the current
1554 directory, and assumes that its caller doesn't either.
1555
1556 This example displays the number of bytes taken by non-directory files in each
1557 directory under the starting directory, except that it doesn't look under any
1558 CVS subdirectory::
1559
1560 import os
1561 from os.path import join, getsize
1562 for root, dirs, files in os.walk('python/Lib/email'):
Georg Brandl6911e3c2007-09-04 07:15:32 +00001563 print(root, "consumes", end=" ")
1564 print(sum(getsize(join(root, name)) for name in files), end=" ")
1565 print("bytes in", len(files), "non-directory files")
Georg Brandl116aa622007-08-15 14:28:22 +00001566 if 'CVS' in dirs:
1567 dirs.remove('CVS') # don't visit CVS directories
1568
Christian Heimesfaf2f632008-01-06 16:59:19 +00001569 In the next example, walking the tree bottom-up is essential: :func:`rmdir`
Georg Brandl116aa622007-08-15 14:28:22 +00001570 doesn't allow deleting a directory before the directory is empty::
1571
Christian Heimesfaf2f632008-01-06 16:59:19 +00001572 # Delete everything reachable from the directory named in "top",
Georg Brandl116aa622007-08-15 14:28:22 +00001573 # assuming there are no symbolic links.
1574 # CAUTION: This is dangerous! For example, if top == '/', it
1575 # could delete all your disk files.
1576 import os
1577 for root, dirs, files in os.walk(top, topdown=False):
1578 for name in files:
1579 os.remove(os.path.join(root, name))
1580 for name in dirs:
1581 os.rmdir(os.path.join(root, name))
1582
Georg Brandl116aa622007-08-15 14:28:22 +00001583
1584.. _os-process:
1585
1586Process Management
1587------------------
1588
1589These functions may be used to create and manage processes.
1590
1591The various :func:`exec\*` functions take a list of arguments for the new
1592program loaded into the process. In each case, the first of these arguments is
1593passed to the new program as its own name rather than as an argument a user may
1594have typed on a command line. For the C programmer, this is the ``argv[0]``
Georg Brandl60203b42010-10-06 10:11:56 +00001595passed to a program's :c:func:`main`. For example, ``os.execv('/bin/echo',
Georg Brandl116aa622007-08-15 14:28:22 +00001596['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem
1597to be ignored.
1598
1599
1600.. function:: abort()
1601
1602 Generate a :const:`SIGABRT` signal to the current process. On Unix, the default
1603 behavior is to produce a core dump; on Windows, the process immediately returns
1604 an exit code of ``3``. Be aware that programs which use :func:`signal.signal`
1605 to register a handler for :const:`SIGABRT` will behave differently.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001606
Georg Brandlc575c902008-09-13 17:46:05 +00001607 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001608
1609
1610.. function:: execl(path, arg0, arg1, ...)
1611 execle(path, arg0, arg1, ..., env)
1612 execlp(file, arg0, arg1, ...)
1613 execlpe(file, arg0, arg1, ..., env)
1614 execv(path, args)
1615 execve(path, args, env)
1616 execvp(file, args)
1617 execvpe(file, args, env)
1618
1619 These functions all execute a new program, replacing the current process; they
1620 do not return. On Unix, the new executable is loaded into the current process,
Christian Heimesfaf2f632008-01-06 16:59:19 +00001621 and will have the same process id as the caller. Errors will be reported as
Georg Brandl48310cd2009-01-03 21:18:54 +00001622 :exc:`OSError` exceptions.
Benjamin Petersone9bbc8b2008-09-28 02:06:32 +00001623
1624 The current process is replaced immediately. Open file objects and
1625 descriptors are not flushed, so if there may be data buffered
1626 on these open files, you should flush them using
1627 :func:`sys.stdout.flush` or :func:`os.fsync` before calling an
1628 :func:`exec\*` function.
Georg Brandl116aa622007-08-15 14:28:22 +00001629
Christian Heimesfaf2f632008-01-06 16:59:19 +00001630 The "l" and "v" variants of the :func:`exec\*` functions differ in how
1631 command-line arguments are passed. The "l" variants are perhaps the easiest
Georg Brandl116aa622007-08-15 14:28:22 +00001632 to work with if the number of parameters is fixed when the code is written; the
1633 individual parameters simply become additional parameters to the :func:`execl\*`
Christian Heimesfaf2f632008-01-06 16:59:19 +00001634 functions. The "v" variants are good when the number of parameters is
Georg Brandl116aa622007-08-15 14:28:22 +00001635 variable, with the arguments being passed in a list or tuple as the *args*
1636 parameter. In either case, the arguments to the child process should start with
1637 the name of the command being run, but this is not enforced.
1638
Christian Heimesfaf2f632008-01-06 16:59:19 +00001639 The variants which include a "p" near the end (:func:`execlp`,
Georg Brandl116aa622007-08-15 14:28:22 +00001640 :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the
1641 :envvar:`PATH` environment variable to locate the program *file*. When the
1642 environment is being replaced (using one of the :func:`exec\*e` variants,
1643 discussed in the next paragraph), the new environment is used as the source of
1644 the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle`,
1645 :func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable to
1646 locate the executable; *path* must contain an appropriate absolute or relative
1647 path.
1648
1649 For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (note
Christian Heimesfaf2f632008-01-06 16:59:19 +00001650 that these all end in "e"), the *env* parameter must be a mapping which is
Christian Heimesa342c012008-04-20 21:01:16 +00001651 used to define the environment variables for the new process (these are used
1652 instead of the current process' environment); the functions :func:`execl`,
Georg Brandl116aa622007-08-15 14:28:22 +00001653 :func:`execlp`, :func:`execv`, and :func:`execvp` all cause the new process to
Georg Brandl48310cd2009-01-03 21:18:54 +00001654 inherit the environment of the current process.
Benjamin Petersone9bbc8b2008-09-28 02:06:32 +00001655
1656 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001657
1658
1659.. function:: _exit(n)
1660
Georg Brandl6f4e68d2010-10-17 10:51:45 +00001661 Exit the process with status *n*, without calling cleanup handlers, flushing
Benjamin Petersonf650e462010-05-06 23:03:05 +00001662 stdio buffers, etc.
1663
1664 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001665
1666 .. note::
1667
Georg Brandl6f4e68d2010-10-17 10:51:45 +00001668 The standard way to exit is ``sys.exit(n)``. :func:`_exit` should
1669 normally only be used in the child process after a :func:`fork`.
Georg Brandl116aa622007-08-15 14:28:22 +00001670
Christian Heimesfaf2f632008-01-06 16:59:19 +00001671The following exit codes are defined and can be used with :func:`_exit`,
Georg Brandl116aa622007-08-15 14:28:22 +00001672although they are not required. These are typically used for system programs
1673written in Python, such as a mail server's external command delivery program.
1674
1675.. note::
1676
1677 Some of these may not be available on all Unix platforms, since there is some
1678 variation. These constants are defined where they are defined by the underlying
1679 platform.
1680
1681
1682.. data:: EX_OK
1683
Benjamin Petersonf650e462010-05-06 23:03:05 +00001684 Exit code that means no error occurred.
1685
1686 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001687
Georg Brandl116aa622007-08-15 14:28:22 +00001688
1689.. data:: EX_USAGE
1690
1691 Exit code that means the command was used incorrectly, such as when the wrong
Benjamin Petersonf650e462010-05-06 23:03:05 +00001692 number of arguments are given.
1693
1694 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001695
Georg Brandl116aa622007-08-15 14:28:22 +00001696
1697.. data:: EX_DATAERR
1698
Benjamin Petersonf650e462010-05-06 23:03:05 +00001699 Exit code that means the input data was incorrect.
1700
1701 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001702
Georg Brandl116aa622007-08-15 14:28:22 +00001703
1704.. data:: EX_NOINPUT
1705
1706 Exit code that means an input file did not exist or was not readable.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001707
Georg Brandlc575c902008-09-13 17:46:05 +00001708 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001709
Georg Brandl116aa622007-08-15 14:28:22 +00001710
1711.. data:: EX_NOUSER
1712
Benjamin Petersonf650e462010-05-06 23:03:05 +00001713 Exit code that means a specified user did not exist.
1714
1715 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001716
Georg Brandl116aa622007-08-15 14:28:22 +00001717
1718.. data:: EX_NOHOST
1719
Benjamin Petersonf650e462010-05-06 23:03:05 +00001720 Exit code that means a specified host did not exist.
1721
1722 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001723
Georg Brandl116aa622007-08-15 14:28:22 +00001724
1725.. data:: EX_UNAVAILABLE
1726
Benjamin Petersonf650e462010-05-06 23:03:05 +00001727 Exit code that means that a required service is unavailable.
1728
1729 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001730
Georg Brandl116aa622007-08-15 14:28:22 +00001731
1732.. data:: EX_SOFTWARE
1733
Benjamin Petersonf650e462010-05-06 23:03:05 +00001734 Exit code that means an internal software error was detected.
1735
1736 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001737
Georg Brandl116aa622007-08-15 14:28:22 +00001738
1739.. data:: EX_OSERR
1740
1741 Exit code that means an operating system error was detected, such as the
Benjamin Petersonf650e462010-05-06 23:03:05 +00001742 inability to fork or create a pipe.
1743
1744 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001745
Georg Brandl116aa622007-08-15 14:28:22 +00001746
1747.. data:: EX_OSFILE
1748
1749 Exit code that means some system file did not exist, could not be opened, or had
Benjamin Petersonf650e462010-05-06 23:03:05 +00001750 some other kind of error.
1751
1752 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001753
Georg Brandl116aa622007-08-15 14:28:22 +00001754
1755.. data:: EX_CANTCREAT
1756
1757 Exit code that means a user specified output file could not be created.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001758
Georg Brandlc575c902008-09-13 17:46:05 +00001759 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001760
Georg Brandl116aa622007-08-15 14:28:22 +00001761
1762.. data:: EX_IOERR
1763
1764 Exit code that means that an error occurred while doing I/O on some file.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001765
Georg Brandlc575c902008-09-13 17:46:05 +00001766 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001767
Georg Brandl116aa622007-08-15 14:28:22 +00001768
1769.. data:: EX_TEMPFAIL
1770
1771 Exit code that means a temporary failure occurred. This indicates something
1772 that may not really be an error, such as a network connection that couldn't be
Benjamin Petersonf650e462010-05-06 23:03:05 +00001773 made during a retryable operation.
1774
1775 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001776
Georg Brandl116aa622007-08-15 14:28:22 +00001777
1778.. data:: EX_PROTOCOL
1779
1780 Exit code that means that a protocol exchange was illegal, invalid, or not
Benjamin Petersonf650e462010-05-06 23:03:05 +00001781 understood.
1782
1783 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001784
Georg Brandl116aa622007-08-15 14:28:22 +00001785
1786.. data:: EX_NOPERM
1787
1788 Exit code that means that there were insufficient permissions to perform the
Benjamin Petersonf650e462010-05-06 23:03:05 +00001789 operation (but not intended for file system problems).
1790
1791 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001792
Georg Brandl116aa622007-08-15 14:28:22 +00001793
1794.. data:: EX_CONFIG
1795
1796 Exit code that means that some kind of configuration error occurred.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001797
Georg Brandlc575c902008-09-13 17:46:05 +00001798 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001799
Georg Brandl116aa622007-08-15 14:28:22 +00001800
1801.. data:: EX_NOTFOUND
1802
Benjamin Petersonf650e462010-05-06 23:03:05 +00001803 Exit code that means something like "an entry was not found".
1804
1805 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001806
Georg Brandl116aa622007-08-15 14:28:22 +00001807
1808.. function:: fork()
1809
Christian Heimesfaf2f632008-01-06 16:59:19 +00001810 Fork a child process. Return ``0`` in the child and the child's process id in the
Christian Heimesdd15f6c2008-03-16 00:07:10 +00001811 parent. If an error occurs :exc:`OSError` is raised.
Benjamin Petersonbcd8ac32008-10-10 22:20:52 +00001812
1813 Note that some platforms including FreeBSD <= 6.3, Cygwin and OS/2 EMX have
1814 known issues when using fork() from a thread.
1815
Georg Brandlc575c902008-09-13 17:46:05 +00001816 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001817
1818
1819.. function:: forkpty()
1820
1821 Fork a child process, using a new pseudo-terminal as the child's controlling
1822 terminal. Return a pair of ``(pid, fd)``, where *pid* is ``0`` in the child, the
1823 new child's process id in the parent, and *fd* is the file descriptor of the
1824 master end of the pseudo-terminal. For a more portable approach, use the
Christian Heimesdd15f6c2008-03-16 00:07:10 +00001825 :mod:`pty` module. If an error occurs :exc:`OSError` is raised.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001826
Georg Brandlc575c902008-09-13 17:46:05 +00001827 Availability: some flavors of Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001828
1829
1830.. function:: kill(pid, sig)
1831
1832 .. index::
1833 single: process; killing
1834 single: process; signalling
1835
1836 Send signal *sig* to the process *pid*. Constants for the specific signals
1837 available on the host platform are defined in the :mod:`signal` module.
Brian Curtineb24d742010-04-12 17:16:38 +00001838
1839 Windows: The :data:`signal.CTRL_C_EVENT` and
1840 :data:`signal.CTRL_BREAK_EVENT` signals are special signals which can
1841 only be sent to console processes which share a common console window,
1842 e.g., some subprocesses. Any other value for *sig* will cause the process
1843 to be unconditionally killed by the TerminateProcess API, and the exit code
1844 will be set to *sig*. The Windows version of :func:`kill` additionally takes
1845 process handles to be killed.
Georg Brandl116aa622007-08-15 14:28:22 +00001846
Georg Brandl67b21b72010-08-17 15:07:14 +00001847 .. versionadded:: 3.2
1848 Windows support.
Brian Curtin904bd392010-04-20 15:28:06 +00001849
Georg Brandl116aa622007-08-15 14:28:22 +00001850
1851.. function:: killpg(pgid, sig)
1852
1853 .. index::
1854 single: process; killing
1855 single: process; signalling
1856
Benjamin Petersonf650e462010-05-06 23:03:05 +00001857 Send the signal *sig* to the process group *pgid*.
1858
1859 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001860
Georg Brandl116aa622007-08-15 14:28:22 +00001861
1862.. function:: nice(increment)
1863
1864 Add *increment* to the process's "niceness". Return the new niceness.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001865
Georg Brandlc575c902008-09-13 17:46:05 +00001866 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001867
1868
1869.. function:: plock(op)
1870
1871 Lock program segments into memory. The value of *op* (defined in
Benjamin Petersonf650e462010-05-06 23:03:05 +00001872 ``<sys/lock.h>``) determines which segments are locked.
1873
1874 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001875
1876
1877.. function:: popen(...)
1878 :noindex:
1879
1880 Run child processes, returning opened pipes for communications. These functions
1881 are described in section :ref:`os-newstreams`.
1882
1883
1884.. function:: spawnl(mode, path, ...)
1885 spawnle(mode, path, ..., env)
1886 spawnlp(mode, file, ...)
1887 spawnlpe(mode, file, ..., env)
1888 spawnv(mode, path, args)
1889 spawnve(mode, path, args, env)
1890 spawnvp(mode, file, args)
1891 spawnvpe(mode, file, args, env)
1892
1893 Execute the program *path* in a new process.
1894
1895 (Note that the :mod:`subprocess` module provides more powerful facilities for
1896 spawning new processes and retrieving their results; using that module is
Benjamin Peterson87c8d872009-06-11 22:54:11 +00001897 preferable to using these functions. Check especially the
1898 :ref:`subprocess-replacements` section.)
Georg Brandl116aa622007-08-15 14:28:22 +00001899
Christian Heimesfaf2f632008-01-06 16:59:19 +00001900 If *mode* is :const:`P_NOWAIT`, this function returns the process id of the new
Georg Brandl116aa622007-08-15 14:28:22 +00001901 process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it
1902 exits normally, or ``-signal``, where *signal* is the signal that killed the
Christian Heimesfaf2f632008-01-06 16:59:19 +00001903 process. On Windows, the process id will actually be the process handle, so can
Georg Brandl116aa622007-08-15 14:28:22 +00001904 be used with the :func:`waitpid` function.
1905
Christian Heimesfaf2f632008-01-06 16:59:19 +00001906 The "l" and "v" variants of the :func:`spawn\*` functions differ in how
1907 command-line arguments are passed. The "l" variants are perhaps the easiest
Georg Brandl116aa622007-08-15 14:28:22 +00001908 to work with if the number of parameters is fixed when the code is written; the
1909 individual parameters simply become additional parameters to the
Christian Heimesfaf2f632008-01-06 16:59:19 +00001910 :func:`spawnl\*` functions. The "v" variants are good when the number of
Georg Brandl116aa622007-08-15 14:28:22 +00001911 parameters is variable, with the arguments being passed in a list or tuple as
1912 the *args* parameter. In either case, the arguments to the child process must
1913 start with the name of the command being run.
1914
Christian Heimesfaf2f632008-01-06 16:59:19 +00001915 The variants which include a second "p" near the end (:func:`spawnlp`,
Georg Brandl116aa622007-08-15 14:28:22 +00001916 :func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the
1917 :envvar:`PATH` environment variable to locate the program *file*. When the
1918 environment is being replaced (using one of the :func:`spawn\*e` variants,
1919 discussed in the next paragraph), the new environment is used as the source of
1920 the :envvar:`PATH` variable. The other variants, :func:`spawnl`,
1921 :func:`spawnle`, :func:`spawnv`, and :func:`spawnve`, will not use the
1922 :envvar:`PATH` variable to locate the executable; *path* must contain an
1923 appropriate absolute or relative path.
1924
1925 For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe`
Christian Heimesfaf2f632008-01-06 16:59:19 +00001926 (note that these all end in "e"), the *env* parameter must be a mapping
Christian Heimesa342c012008-04-20 21:01:16 +00001927 which is used to define the environment variables for the new process (they are
1928 used instead of the current process' environment); the functions
Georg Brandl116aa622007-08-15 14:28:22 +00001929 :func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause
Benjamin Petersond23f8222009-04-05 19:13:16 +00001930 the new process to inherit the environment of the current process. Note that
1931 keys and values in the *env* dictionary must be strings; invalid keys or
1932 values will cause the function to fail, with a return value of ``127``.
Georg Brandl116aa622007-08-15 14:28:22 +00001933
1934 As an example, the following calls to :func:`spawnlp` and :func:`spawnvpe` are
1935 equivalent::
1936
1937 import os
1938 os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')
1939
1940 L = ['cp', 'index.html', '/dev/null']
1941 os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)
1942
1943 Availability: Unix, Windows. :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp`
1944 and :func:`spawnvpe` are not available on Windows.
1945
Georg Brandl116aa622007-08-15 14:28:22 +00001946
1947.. data:: P_NOWAIT
1948 P_NOWAITO
1949
1950 Possible values for the *mode* parameter to the :func:`spawn\*` family of
1951 functions. If either of these values is given, the :func:`spawn\*` functions
Christian Heimesfaf2f632008-01-06 16:59:19 +00001952 will return as soon as the new process has been created, with the process id as
Benjamin Petersonf650e462010-05-06 23:03:05 +00001953 the return value.
1954
1955 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001956
Georg Brandl116aa622007-08-15 14:28:22 +00001957
1958.. data:: P_WAIT
1959
1960 Possible value for the *mode* parameter to the :func:`spawn\*` family of
1961 functions. If this is given as *mode*, the :func:`spawn\*` functions will not
1962 return until the new process has run to completion and will return the exit code
1963 of the process the run is successful, or ``-signal`` if a signal kills the
Benjamin Petersonf650e462010-05-06 23:03:05 +00001964 process.
1965
1966 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001967
Georg Brandl116aa622007-08-15 14:28:22 +00001968
1969.. data:: P_DETACH
1970 P_OVERLAY
1971
1972 Possible values for the *mode* parameter to the :func:`spawn\*` family of
1973 functions. These are less portable than those listed above. :const:`P_DETACH`
1974 is similar to :const:`P_NOWAIT`, but the new process is detached from the
1975 console of the calling process. If :const:`P_OVERLAY` is used, the current
1976 process will be replaced; the :func:`spawn\*` function will not return.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001977
Georg Brandl116aa622007-08-15 14:28:22 +00001978 Availability: Windows.
1979
Georg Brandl116aa622007-08-15 14:28:22 +00001980
1981.. function:: startfile(path[, operation])
1982
1983 Start a file with its associated application.
1984
1985 When *operation* is not specified or ``'open'``, this acts like double-clicking
1986 the file in Windows Explorer, or giving the file name as an argument to the
1987 :program:`start` command from the interactive command shell: the file is opened
1988 with whatever application (if any) its extension is associated.
1989
1990 When another *operation* is given, it must be a "command verb" that specifies
1991 what should be done with the file. Common verbs documented by Microsoft are
1992 ``'print'`` and ``'edit'`` (to be used on files) as well as ``'explore'`` and
1993 ``'find'`` (to be used on directories).
1994
1995 :func:`startfile` returns as soon as the associated application is launched.
1996 There is no option to wait for the application to close, and no way to retrieve
1997 the application's exit status. The *path* parameter is relative to the current
1998 directory. If you want to use an absolute path, make sure the first character
Georg Brandl60203b42010-10-06 10:11:56 +00001999 is not a slash (``'/'``); the underlying Win32 :c:func:`ShellExecute` function
Georg Brandl116aa622007-08-15 14:28:22 +00002000 doesn't work if it is. Use the :func:`os.path.normpath` function to ensure that
Benjamin Petersonf650e462010-05-06 23:03:05 +00002001 the path is properly encoded for Win32.
2002
2003 Availability: Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00002004
Georg Brandl116aa622007-08-15 14:28:22 +00002005
2006.. function:: system(command)
2007
2008 Execute the command (a string) in a subshell. This is implemented by calling
Georg Brandl60203b42010-10-06 10:11:56 +00002009 the Standard C function :c:func:`system`, and has the same limitations.
Georg Brandl8f7b4272010-10-14 06:35:53 +00002010 Changes to :data:`sys.stdin`, etc. are not reflected in the environment of
2011 the executed command. If *command* generates any output, it will be sent to
2012 the interpreter standard output stream.
Georg Brandl116aa622007-08-15 14:28:22 +00002013
2014 On Unix, the return value is the exit status of the process encoded in the
Georg Brandl8f7b4272010-10-14 06:35:53 +00002015 format specified for :func:`wait`. Note that POSIX does not specify the
2016 meaning of the return value of the C :c:func:`system` function, so the return
2017 value of the Python function is system-dependent.
Georg Brandl116aa622007-08-15 14:28:22 +00002018
Georg Brandl8f7b4272010-10-14 06:35:53 +00002019 On Windows, the return value is that returned by the system shell after
2020 running *command*. The shell is given by the Windows environment variable
2021 :envvar:`COMSPEC`: it is usually :program:`cmd.exe`, which returns the exit
2022 status of the command run; on systems using a non-native shell, consult your
2023 shell documentation.
Georg Brandl116aa622007-08-15 14:28:22 +00002024
Georg Brandl8f7b4272010-10-14 06:35:53 +00002025 The :mod:`subprocess` module provides more powerful facilities for spawning
2026 new processes and retrieving their results; using that module is preferable
2027 to using this function. See the :ref:`subprocess-replacements` section in
2028 the :mod:`subprocess` documentation for some helpful recipes.
Georg Brandl116aa622007-08-15 14:28:22 +00002029
Benjamin Petersonf650e462010-05-06 23:03:05 +00002030 Availability: Unix, Windows.
2031
Georg Brandl116aa622007-08-15 14:28:22 +00002032
2033.. function:: times()
2034
Benjamin Petersonf650e462010-05-06 23:03:05 +00002035 Return a 5-tuple of floating point numbers indicating accumulated (processor
2036 or other) times, in seconds. The items are: user time, system time,
2037 children's user time, children's system time, and elapsed real time since a
2038 fixed point in the past, in that order. See the Unix manual page
2039 :manpage:`times(2)` or the corresponding Windows Platform API documentation.
2040 On Windows, only the first two items are filled, the others are zero.
2041
2042 Availability: Unix, Windows
Georg Brandl116aa622007-08-15 14:28:22 +00002043
2044
2045.. function:: wait()
2046
2047 Wait for completion of a child process, and return a tuple containing its pid
2048 and exit status indication: a 16-bit number, whose low byte is the signal number
2049 that killed the process, and whose high byte is the exit status (if the signal
2050 number is zero); the high bit of the low byte is set if a core file was
Benjamin Petersonf650e462010-05-06 23:03:05 +00002051 produced.
2052
2053 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002054
2055
2056.. function:: waitpid(pid, options)
2057
2058 The details of this function differ on Unix and Windows.
2059
2060 On Unix: Wait for completion of a child process given by process id *pid*, and
2061 return a tuple containing its process id and exit status indication (encoded as
2062 for :func:`wait`). The semantics of the call are affected by the value of the
2063 integer *options*, which should be ``0`` for normal operation.
2064
2065 If *pid* is greater than ``0``, :func:`waitpid` requests status information for
2066 that specific process. If *pid* is ``0``, the request is for the status of any
2067 child in the process group of the current process. If *pid* is ``-1``, the
2068 request pertains to any child of the current process. If *pid* is less than
2069 ``-1``, status is requested for any process in the process group ``-pid`` (the
2070 absolute value of *pid*).
2071
Benjamin Peterson4cd6a952008-08-17 20:23:46 +00002072 An :exc:`OSError` is raised with the value of errno when the syscall
2073 returns -1.
2074
Georg Brandl116aa622007-08-15 14:28:22 +00002075 On Windows: Wait for completion of a process given by process handle *pid*, and
2076 return a tuple containing *pid*, and its exit status shifted left by 8 bits
2077 (shifting makes cross-platform use of the function easier). A *pid* less than or
2078 equal to ``0`` has no special meaning on Windows, and raises an exception. The
2079 value of integer *options* has no effect. *pid* can refer to any process whose
2080 id is known, not necessarily a child process. The :func:`spawn` functions called
2081 with :const:`P_NOWAIT` return suitable process handles.
2082
2083
2084.. function:: wait3([options])
2085
2086 Similar to :func:`waitpid`, except no process id argument is given and a
2087 3-element tuple containing the child's process id, exit status indication, and
2088 resource usage information is returned. Refer to :mod:`resource`.\
2089 :func:`getrusage` for details on resource usage information. The option
2090 argument is the same as that provided to :func:`waitpid` and :func:`wait4`.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002091
Georg Brandl116aa622007-08-15 14:28:22 +00002092 Availability: Unix.
2093
Georg Brandl116aa622007-08-15 14:28:22 +00002094
2095.. function:: wait4(pid, options)
2096
2097 Similar to :func:`waitpid`, except a 3-element tuple, containing the child's
2098 process id, exit status indication, and resource usage information is returned.
2099 Refer to :mod:`resource`.\ :func:`getrusage` for details on resource usage
2100 information. The arguments to :func:`wait4` are the same as those provided to
Benjamin Petersonf650e462010-05-06 23:03:05 +00002101 :func:`waitpid`.
2102
2103 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002104
Georg Brandl116aa622007-08-15 14:28:22 +00002105
2106.. data:: WNOHANG
2107
2108 The option for :func:`waitpid` to return immediately if no child process status
2109 is available immediately. The function returns ``(0, 0)`` in this case.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002110
Georg Brandlc575c902008-09-13 17:46:05 +00002111 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002112
2113
2114.. data:: WCONTINUED
2115
2116 This option causes child processes to be reported if they have been continued
Benjamin Petersonf650e462010-05-06 23:03:05 +00002117 from a job control stop since their status was last reported.
2118
2119 Availability: Some Unix systems.
Georg Brandl116aa622007-08-15 14:28:22 +00002120
Georg Brandl116aa622007-08-15 14:28:22 +00002121
2122.. data:: WUNTRACED
2123
2124 This option causes child processes to be reported if they have been stopped but
Benjamin Petersonf650e462010-05-06 23:03:05 +00002125 their current state has not been reported since they were stopped.
2126
2127 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002128
Georg Brandl116aa622007-08-15 14:28:22 +00002129
2130The following functions take a process status code as returned by
2131:func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be
2132used to determine the disposition of a process.
2133
Georg Brandl116aa622007-08-15 14:28:22 +00002134.. function:: WCOREDUMP(status)
2135
Christian Heimesfaf2f632008-01-06 16:59:19 +00002136 Return ``True`` if a core dump was generated for the process, otherwise
Benjamin Petersonf650e462010-05-06 23:03:05 +00002137 return ``False``.
2138
2139 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002140
Georg Brandl116aa622007-08-15 14:28:22 +00002141
2142.. function:: WIFCONTINUED(status)
2143
Christian Heimesfaf2f632008-01-06 16:59:19 +00002144 Return ``True`` if the process has been continued from a job control stop,
Benjamin Petersonf650e462010-05-06 23:03:05 +00002145 otherwise return ``False``.
2146
2147 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002148
Georg Brandl116aa622007-08-15 14:28:22 +00002149
2150.. function:: WIFSTOPPED(status)
2151
Christian Heimesfaf2f632008-01-06 16:59:19 +00002152 Return ``True`` if the process has been stopped, otherwise return
Benjamin Petersonf650e462010-05-06 23:03:05 +00002153 ``False``.
2154
2155 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002156
2157
2158.. function:: WIFSIGNALED(status)
2159
Christian Heimesfaf2f632008-01-06 16:59:19 +00002160 Return ``True`` if the process exited due to a signal, otherwise return
Benjamin Petersonf650e462010-05-06 23:03:05 +00002161 ``False``.
2162
2163 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002164
2165
2166.. function:: WIFEXITED(status)
2167
Christian Heimesfaf2f632008-01-06 16:59:19 +00002168 Return ``True`` if the process exited using the :manpage:`exit(2)` system call,
Benjamin Petersonf650e462010-05-06 23:03:05 +00002169 otherwise return ``False``.
2170
2171 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002172
2173
2174.. function:: WEXITSTATUS(status)
2175
2176 If ``WIFEXITED(status)`` is true, return the integer parameter to the
2177 :manpage:`exit(2)` system call. Otherwise, the return value is meaningless.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002178
Georg Brandlc575c902008-09-13 17:46:05 +00002179 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002180
2181
2182.. function:: WSTOPSIG(status)
2183
Benjamin Petersonf650e462010-05-06 23:03:05 +00002184 Return the signal which caused the process to stop.
2185
2186 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002187
2188
2189.. function:: WTERMSIG(status)
2190
Benjamin Petersonf650e462010-05-06 23:03:05 +00002191 Return the signal which caused the process to exit.
2192
2193 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002194
2195
2196.. _os-path:
2197
2198Miscellaneous System Information
2199--------------------------------
2200
2201
2202.. function:: confstr(name)
2203
2204 Return string-valued system configuration values. *name* specifies the
2205 configuration value to retrieve; it may be a string which is the name of a
2206 defined system value; these names are specified in a number of standards (POSIX,
2207 Unix 95, Unix 98, and others). Some platforms define additional names as well.
2208 The names known to the host operating system are given as the keys of the
2209 ``confstr_names`` dictionary. For configuration variables not included in that
Benjamin Petersonf650e462010-05-06 23:03:05 +00002210 mapping, passing an integer for *name* is also accepted.
Georg Brandl116aa622007-08-15 14:28:22 +00002211
2212 If the configuration value specified by *name* isn't defined, ``None`` is
2213 returned.
2214
2215 If *name* is a string and is not known, :exc:`ValueError` is raised. If a
2216 specific value for *name* is not supported by the host system, even if it is
2217 included in ``confstr_names``, an :exc:`OSError` is raised with
2218 :const:`errno.EINVAL` for the error number.
2219
Benjamin Petersonf650e462010-05-06 23:03:05 +00002220 Availability: Unix
2221
Georg Brandl116aa622007-08-15 14:28:22 +00002222
2223.. data:: confstr_names
2224
2225 Dictionary mapping names accepted by :func:`confstr` to the integer values
2226 defined for those names by the host operating system. This can be used to
Benjamin Petersonf650e462010-05-06 23:03:05 +00002227 determine the set of names known to the system.
2228
2229 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002230
2231
2232.. function:: getloadavg()
2233
Christian Heimesa62da1d2008-01-12 19:39:10 +00002234 Return the number of processes in the system run queue averaged over the last
2235 1, 5, and 15 minutes or raises :exc:`OSError` if the load average was
Benjamin Petersonf650e462010-05-06 23:03:05 +00002236 unobtainable.
2237
2238 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002239
Georg Brandl116aa622007-08-15 14:28:22 +00002240
2241.. function:: sysconf(name)
2242
2243 Return integer-valued system configuration values. If the configuration value
2244 specified by *name* isn't defined, ``-1`` is returned. The comments regarding
2245 the *name* parameter for :func:`confstr` apply here as well; the dictionary that
2246 provides information on the known names is given by ``sysconf_names``.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002247
Georg Brandlc575c902008-09-13 17:46:05 +00002248 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002249
2250
2251.. data:: sysconf_names
2252
2253 Dictionary mapping names accepted by :func:`sysconf` to the integer values
2254 defined for those names by the host operating system. This can be used to
Benjamin Petersonf650e462010-05-06 23:03:05 +00002255 determine the set of names known to the system.
2256
2257 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002258
Christian Heimesfaf2f632008-01-06 16:59:19 +00002259The following data values are used to support path manipulation operations. These
Georg Brandl116aa622007-08-15 14:28:22 +00002260are defined for all platforms.
2261
2262Higher-level operations on pathnames are defined in the :mod:`os.path` module.
2263
2264
2265.. data:: curdir
2266
2267 The constant string used by the operating system to refer to the current
Georg Brandlc575c902008-09-13 17:46:05 +00002268 directory. This is ``'.'`` for Windows and POSIX. Also available via
2269 :mod:`os.path`.
Georg Brandl116aa622007-08-15 14:28:22 +00002270
2271
2272.. data:: pardir
2273
2274 The constant string used by the operating system to refer to the parent
Georg Brandlc575c902008-09-13 17:46:05 +00002275 directory. This is ``'..'`` for Windows and POSIX. Also available via
2276 :mod:`os.path`.
Georg Brandl116aa622007-08-15 14:28:22 +00002277
2278
2279.. data:: sep
2280
Georg Brandlc575c902008-09-13 17:46:05 +00002281 The character used by the operating system to separate pathname components.
2282 This is ``'/'`` for POSIX and ``'\\'`` for Windows. Note that knowing this
2283 is not sufficient to be able to parse or concatenate pathnames --- use
Georg Brandl116aa622007-08-15 14:28:22 +00002284 :func:`os.path.split` and :func:`os.path.join` --- but it is occasionally
2285 useful. Also available via :mod:`os.path`.
2286
2287
2288.. data:: altsep
2289
2290 An alternative character used by the operating system to separate pathname
2291 components, or ``None`` if only one separator character exists. This is set to
2292 ``'/'`` on Windows systems where ``sep`` is a backslash. Also available via
2293 :mod:`os.path`.
2294
2295
2296.. data:: extsep
2297
2298 The character which separates the base filename from the extension; for example,
2299 the ``'.'`` in :file:`os.py`. Also available via :mod:`os.path`.
2300
Georg Brandl116aa622007-08-15 14:28:22 +00002301
2302.. data:: pathsep
2303
2304 The character conventionally used by the operating system to separate search
2305 path components (as in :envvar:`PATH`), such as ``':'`` for POSIX or ``';'`` for
2306 Windows. Also available via :mod:`os.path`.
2307
2308
2309.. data:: defpath
2310
2311 The default search path used by :func:`exec\*p\*` and :func:`spawn\*p\*` if the
2312 environment doesn't have a ``'PATH'`` key. Also available via :mod:`os.path`.
2313
2314
2315.. data:: linesep
2316
2317 The string used to separate (or, rather, terminate) lines on the current
Georg Brandlc575c902008-09-13 17:46:05 +00002318 platform. This may be a single character, such as ``'\n'`` for POSIX, or
2319 multiple characters, for example, ``'\r\n'`` for Windows. Do not use
2320 *os.linesep* as a line terminator when writing files opened in text mode (the
2321 default); use a single ``'\n'`` instead, on all platforms.
Georg Brandl116aa622007-08-15 14:28:22 +00002322
2323
2324.. data:: devnull
2325
Georg Brandl850a9902010-05-21 22:04:32 +00002326 The file path of the null device. For example: ``'/dev/null'`` for
2327 POSIX, ``'nul'`` for Windows. Also available via :mod:`os.path`.
Georg Brandl116aa622007-08-15 14:28:22 +00002328
Georg Brandl116aa622007-08-15 14:28:22 +00002329
2330.. _os-miscfunc:
2331
2332Miscellaneous Functions
2333-----------------------
2334
2335
2336.. function:: urandom(n)
2337
2338 Return a string of *n* random bytes suitable for cryptographic use.
2339
2340 This function returns random bytes from an OS-specific randomness source. The
2341 returned data should be unpredictable enough for cryptographic applications,
2342 though its exact quality depends on the OS implementation. On a UNIX-like
2343 system this will query /dev/urandom, and on Windows it will use CryptGenRandom.
2344 If a randomness source is not found, :exc:`NotImplementedError` will be raised.