blob: 35562ca7167b5f65d12c44d47e72698e42244f6b [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
778.. function:: tcgetpgrp(fd)
779
780 Return the process group associated with the terminal given by *fd* (an open
Benjamin Petersonf650e462010-05-06 23:03:05 +0000781 file descriptor as returned by :func:`os.open`).
782
783 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000784
785
786.. function:: tcsetpgrp(fd, pg)
787
788 Set the process group associated with the terminal given by *fd* (an open file
Benjamin Petersonf650e462010-05-06 23:03:05 +0000789 descriptor as returned by :func:`os.open`) to *pg*.
790
791 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000792
793
794.. function:: ttyname(fd)
795
796 Return a string which specifies the terminal device associated with
Georg Brandl9afde1c2007-11-01 20:32:30 +0000797 file descriptor *fd*. If *fd* is not associated with a terminal device, an
Benjamin Petersonf650e462010-05-06 23:03:05 +0000798 exception is raised.
799
800 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000801
802
803.. function:: write(fd, str)
804
Georg Brandlb90be692009-07-29 16:14:16 +0000805 Write the bytestring in *str* to file descriptor *fd*. Return the number of
Benjamin Petersonf650e462010-05-06 23:03:05 +0000806 bytes actually written.
807
808 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000809
810 .. note::
811
812 This function is intended for low-level I/O and must be applied to a file
Benjamin Petersonfa0d7032009-06-01 22:42:33 +0000813 descriptor as returned by :func:`os.open` or :func:`pipe`. To write a "file
Georg Brandl116aa622007-08-15 14:28:22 +0000814 object" returned by the built-in function :func:`open` or by :func:`popen` or
Benjamin Petersonfa0d7032009-06-01 22:42:33 +0000815 :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
816 :meth:`~file.write` method.
Georg Brandl116aa622007-08-15 14:28:22 +0000817
Georg Brandl8569e582010-05-19 20:57:08 +0000818
819.. _open-constants:
820
821``open()`` flag constants
822~~~~~~~~~~~~~~~~~~~~~~~~~
823
Georg Brandlaf265f42008-12-07 15:06:20 +0000824The following constants are options for the *flags* parameter to the
Benjamin Petersonfa0d7032009-06-01 22:42:33 +0000825:func:`~os.open` function. They can be combined using the bitwise OR operator
Georg Brandlaf265f42008-12-07 15:06:20 +0000826``|``. Some of them are not available on all platforms. For descriptions of
827their availability and use, consult the :manpage:`open(2)` manual page on Unix
Doug Hellmanneb097fc2009-09-20 20:56:56 +0000828or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000829
830
831.. data:: O_RDONLY
832 O_WRONLY
833 O_RDWR
834 O_APPEND
835 O_CREAT
836 O_EXCL
837 O_TRUNC
838
Georg Brandlaf265f42008-12-07 15:06:20 +0000839 These constants are available on Unix and Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000840
841
842.. data:: O_DSYNC
843 O_RSYNC
844 O_SYNC
845 O_NDELAY
846 O_NONBLOCK
847 O_NOCTTY
848 O_SHLOCK
849 O_EXLOCK
850
Georg Brandlaf265f42008-12-07 15:06:20 +0000851 These constants are only available on Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000852
853
854.. data:: O_BINARY
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000855 O_NOINHERIT
Georg Brandl116aa622007-08-15 14:28:22 +0000856 O_SHORT_LIVED
857 O_TEMPORARY
858 O_RANDOM
859 O_SEQUENTIAL
860 O_TEXT
861
Georg Brandlaf265f42008-12-07 15:06:20 +0000862 These constants are only available on Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000863
864
Alexandre Vassalottibee32532008-05-16 18:15:12 +0000865.. data:: O_ASYNC
866 O_DIRECT
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000867 O_DIRECTORY
868 O_NOFOLLOW
869 O_NOATIME
870
Georg Brandlaf265f42008-12-07 15:06:20 +0000871 These constants are GNU extensions and not present if they are not defined by
872 the C library.
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000873
874
Georg Brandl116aa622007-08-15 14:28:22 +0000875.. _os-file-dir:
876
877Files and Directories
878---------------------
879
Georg Brandl116aa622007-08-15 14:28:22 +0000880.. function:: access(path, mode)
881
882 Use the real uid/gid to test for access to *path*. Note that most operations
883 will use the effective uid/gid, therefore this routine can be used in a
884 suid/sgid environment to test if the invoking user has the specified access to
885 *path*. *mode* should be :const:`F_OK` to test the existence of *path*, or it
886 can be the inclusive OR of one or more of :const:`R_OK`, :const:`W_OK`, and
887 :const:`X_OK` to test permissions. Return :const:`True` if access is allowed,
888 :const:`False` if not. See the Unix man page :manpage:`access(2)` for more
Benjamin Petersonf650e462010-05-06 23:03:05 +0000889 information.
890
891 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000892
893 .. note::
894
Georg Brandl502d9a52009-07-26 15:02:41 +0000895 Using :func:`access` to check if a user is authorized to e.g. open a file
896 before actually doing so using :func:`open` creates a security hole,
897 because the user might exploit the short time interval between checking
898 and opening the file to manipulate it.
Georg Brandl116aa622007-08-15 14:28:22 +0000899
900 .. note::
901
902 I/O operations may fail even when :func:`access` indicates that they would
903 succeed, particularly for operations on network filesystems which may have
904 permissions semantics beyond the usual POSIX permission-bit model.
905
906
907.. data:: F_OK
908
909 Value to pass as the *mode* parameter of :func:`access` to test the existence of
910 *path*.
911
912
913.. data:: R_OK
914
915 Value to include in the *mode* parameter of :func:`access` to test the
916 readability of *path*.
917
918
919.. data:: W_OK
920
921 Value to include in the *mode* parameter of :func:`access` to test the
922 writability of *path*.
923
924
925.. data:: X_OK
926
927 Value to include in the *mode* parameter of :func:`access` to determine if
928 *path* can be executed.
929
930
931.. function:: chdir(path)
932
933 .. index:: single: directory; changing
934
Benjamin Petersonf650e462010-05-06 23:03:05 +0000935 Change the current working directory to *path*.
936
937 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000938
939
940.. function:: fchdir(fd)
941
942 Change the current working directory to the directory represented by the file
943 descriptor *fd*. The descriptor must refer to an opened directory, not an open
Benjamin Petersonf650e462010-05-06 23:03:05 +0000944 file.
945
946 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000947
Georg Brandl116aa622007-08-15 14:28:22 +0000948
949.. function:: getcwd()
950
Martin v. Löwis011e8422009-05-05 04:43:17 +0000951 Return a string representing the current working directory.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000952
Martin v. Löwis011e8422009-05-05 04:43:17 +0000953 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000954
Benjamin Petersonf650e462010-05-06 23:03:05 +0000955
Martin v. Löwisa731b992008-10-07 06:36:31 +0000956.. function:: getcwdb()
Georg Brandl116aa622007-08-15 14:28:22 +0000957
Georg Brandl76e55382008-10-08 16:34:57 +0000958 Return a bytestring representing the current working directory.
Benjamin Petersonf650e462010-05-06 23:03:05 +0000959
Georg Brandlc575c902008-09-13 17:46:05 +0000960 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000961
Georg Brandl116aa622007-08-15 14:28:22 +0000962
963.. function:: chflags(path, flags)
964
965 Set the flags of *path* to the numeric *flags*. *flags* may take a combination
966 (bitwise OR) of the following values (as defined in the :mod:`stat` module):
967
968 * ``UF_NODUMP``
969 * ``UF_IMMUTABLE``
970 * ``UF_APPEND``
971 * ``UF_OPAQUE``
972 * ``UF_NOUNLINK``
973 * ``SF_ARCHIVED``
974 * ``SF_IMMUTABLE``
975 * ``SF_APPEND``
976 * ``SF_NOUNLINK``
977 * ``SF_SNAPSHOT``
978
Georg Brandlc575c902008-09-13 17:46:05 +0000979 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000980
Georg Brandl116aa622007-08-15 14:28:22 +0000981
982.. function:: chroot(path)
983
984 Change the root directory of the current process to *path*. Availability:
Georg Brandlc575c902008-09-13 17:46:05 +0000985 Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000986
Georg Brandl116aa622007-08-15 14:28:22 +0000987
988.. function:: chmod(path, mode)
989
990 Change the mode of *path* to the numeric *mode*. *mode* may take one of the
Christian Heimesfaf2f632008-01-06 16:59:19 +0000991 following values (as defined in the :mod:`stat` module) or bitwise ORed
Georg Brandl116aa622007-08-15 14:28:22 +0000992 combinations of them:
993
Alexandre Vassalottic22c6f22009-07-21 00:51:58 +0000994 * :data:`stat.S_ISUID`
995 * :data:`stat.S_ISGID`
996 * :data:`stat.S_ENFMT`
997 * :data:`stat.S_ISVTX`
998 * :data:`stat.S_IREAD`
999 * :data:`stat.S_IWRITE`
1000 * :data:`stat.S_IEXEC`
1001 * :data:`stat.S_IRWXU`
1002 * :data:`stat.S_IRUSR`
1003 * :data:`stat.S_IWUSR`
1004 * :data:`stat.S_IXUSR`
1005 * :data:`stat.S_IRWXG`
1006 * :data:`stat.S_IRGRP`
1007 * :data:`stat.S_IWGRP`
1008 * :data:`stat.S_IXGRP`
1009 * :data:`stat.S_IRWXO`
1010 * :data:`stat.S_IROTH`
1011 * :data:`stat.S_IWOTH`
1012 * :data:`stat.S_IXOTH`
Georg Brandl116aa622007-08-15 14:28:22 +00001013
Georg Brandlc575c902008-09-13 17:46:05 +00001014 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001015
1016 .. note::
1017
1018 Although Windows supports :func:`chmod`, you can only set the file's read-only
1019 flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD``
1020 constants or a corresponding integer value). All other bits are
1021 ignored.
1022
1023
1024.. function:: chown(path, uid, gid)
1025
1026 Change the owner and group id of *path* to the numeric *uid* and *gid*. To leave
Benjamin Petersonf650e462010-05-06 23:03:05 +00001027 one of the ids unchanged, set it to -1.
1028
1029 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001030
1031
1032.. function:: lchflags(path, flags)
1033
1034 Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do not
Benjamin Petersonf650e462010-05-06 23:03:05 +00001035 follow symbolic links.
1036
1037 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001038
Georg Brandl116aa622007-08-15 14:28:22 +00001039
Christian Heimes93852662007-12-01 12:22:32 +00001040.. function:: lchmod(path, mode)
1041
1042 Change the mode of *path* to the numeric *mode*. If path is a symlink, this
1043 affects the symlink rather than the target. See the docs for :func:`chmod`
Benjamin Petersonf650e462010-05-06 23:03:05 +00001044 for possible values of *mode*.
1045
1046 Availability: Unix.
Christian Heimes93852662007-12-01 12:22:32 +00001047
Christian Heimes93852662007-12-01 12:22:32 +00001048
Georg Brandl116aa622007-08-15 14:28:22 +00001049.. function:: lchown(path, uid, gid)
1050
Christian Heimesfaf2f632008-01-06 16:59:19 +00001051 Change the owner and group id of *path* to the numeric *uid* and *gid*. This
Benjamin Petersonf650e462010-05-06 23:03:05 +00001052 function will not follow symbolic links.
1053
1054 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001055
Georg Brandl116aa622007-08-15 14:28:22 +00001056
Benjamin Peterson5879d412009-03-30 14:51:56 +00001057.. function:: link(source, link_name)
Georg Brandl116aa622007-08-15 14:28:22 +00001058
Benjamin Petersonf650e462010-05-06 23:03:05 +00001059 Create a hard link pointing to *source* named *link_name*.
1060
Brian Curtin1b9df392010-11-24 20:24:31 +00001061 Availability: Unix, Windows.
1062
1063 .. versionchanged:: 3.2
1064 Added Windows support.
Georg Brandl116aa622007-08-15 14:28:22 +00001065
1066
Martin v. Löwis9c71f902010-07-24 10:09:11 +00001067.. function:: listdir(path='.')
Georg Brandl116aa622007-08-15 14:28:22 +00001068
Benjamin Peterson4469d0c2008-11-30 22:46:23 +00001069 Return a list containing the names of the entries in the directory given by
Martin v. Löwis9c71f902010-07-24 10:09:11 +00001070 *path* (default: ``'.'``). The list is in arbitrary order. It does not include the special
Benjamin Peterson4469d0c2008-11-30 22:46:23 +00001071 entries ``'.'`` and ``'..'`` even if they are present in the directory.
Georg Brandl116aa622007-08-15 14:28:22 +00001072
Martin v. Löwis011e8422009-05-05 04:43:17 +00001073 This function can be called with a bytes or string argument, and returns
1074 filenames of the same datatype.
Georg Brandl116aa622007-08-15 14:28:22 +00001075
Benjamin Petersonf650e462010-05-06 23:03:05 +00001076 Availability: Unix, Windows.
1077
Martin v. Löwisc9e1c7d2010-07-23 12:16:41 +00001078 .. versionchanged:: 3.2
1079 The *path* parameter became optional.
Georg Brandl116aa622007-08-15 14:28:22 +00001080
1081.. function:: lstat(path)
1082
R. David Murray7b1aae92011-01-24 19:34:58 +00001083 Perform the equivalent of an :c:func:`lstat` system call on the given path.
1084 Similar to :func:`~os.stat`, but does not follow symbolic links. On
1085 platforms that do not support symbolic links, this is an alias for
1086 :func:`~os.stat`.
Brian Curtinc7395692010-07-09 15:15:09 +00001087
Georg Brandlb3823372010-07-10 08:58:37 +00001088 .. versionchanged:: 3.2
1089 Added support for Windows 6.0 (Vista) symbolic links.
Georg Brandl116aa622007-08-15 14:28:22 +00001090
1091
1092.. function:: mkfifo(path[, mode])
1093
Georg Brandlf4a41232008-05-26 17:55:52 +00001094 Create a FIFO (a named pipe) named *path* with numeric mode *mode*. The
1095 default *mode* is ``0o666`` (octal). The current umask value is first masked
Benjamin Petersonf650e462010-05-06 23:03:05 +00001096 out from the mode.
Georg Brandl116aa622007-08-15 14:28:22 +00001097
1098 FIFOs are pipes that can be accessed like regular files. FIFOs exist until they
1099 are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as
1100 rendezvous between "client" and "server" type processes: the server opens the
1101 FIFO for reading, and the client opens it for writing. Note that :func:`mkfifo`
1102 doesn't open the FIFO --- it just creates the rendezvous point.
1103
Benjamin Petersonf650e462010-05-06 23:03:05 +00001104 Availability: Unix.
1105
Georg Brandl116aa622007-08-15 14:28:22 +00001106
Georg Brandl18244152009-09-02 20:34:52 +00001107.. function:: mknod(filename[, mode=0o600[, device]])
Georg Brandl116aa622007-08-15 14:28:22 +00001108
1109 Create a filesystem node (file, device special file or named pipe) named
Georg Brandl18244152009-09-02 20:34:52 +00001110 *filename*. *mode* specifies both the permissions to use and the type of node
1111 to be created, being combined (bitwise OR) with one of ``stat.S_IFREG``,
1112 ``stat.S_IFCHR``, ``stat.S_IFBLK``, and ``stat.S_IFIFO`` (those constants are
1113 available in :mod:`stat`). For ``stat.S_IFCHR`` and ``stat.S_IFBLK``,
1114 *device* defines the newly created device special file (probably using
Georg Brandl116aa622007-08-15 14:28:22 +00001115 :func:`os.makedev`), otherwise it is ignored.
1116
Georg Brandl116aa622007-08-15 14:28:22 +00001117
1118.. function:: major(device)
1119
Christian Heimesfaf2f632008-01-06 16:59:19 +00001120 Extract the device major number from a raw device number (usually the
Georg Brandl60203b42010-10-06 10:11:56 +00001121 :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`).
Georg Brandl116aa622007-08-15 14:28:22 +00001122
Georg Brandl116aa622007-08-15 14:28:22 +00001123
1124.. function:: minor(device)
1125
Christian Heimesfaf2f632008-01-06 16:59:19 +00001126 Extract the device minor number from a raw device number (usually the
Georg Brandl60203b42010-10-06 10:11:56 +00001127 :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`).
Georg Brandl116aa622007-08-15 14:28:22 +00001128
Georg Brandl116aa622007-08-15 14:28:22 +00001129
1130.. function:: makedev(major, minor)
1131
Christian Heimesfaf2f632008-01-06 16:59:19 +00001132 Compose a raw device number from the major and minor device numbers.
Georg Brandl116aa622007-08-15 14:28:22 +00001133
Georg Brandl116aa622007-08-15 14:28:22 +00001134
1135.. function:: mkdir(path[, mode])
1136
Georg Brandlf4a41232008-05-26 17:55:52 +00001137 Create a directory named *path* with numeric mode *mode*. The default *mode*
1138 is ``0o777`` (octal). On some systems, *mode* is ignored. Where it is used,
Benjamin Petersond7c3ed52010-06-27 22:32:30 +00001139 the current umask value is first masked out. If the directory already
1140 exists, :exc:`OSError` is raised.
Georg Brandl116aa622007-08-15 14:28:22 +00001141
Guido van Rossum2cc30da2007-11-02 23:46:40 +00001142 It is also possible to create temporary directories; see the
1143 :mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
1144
Benjamin Petersonf650e462010-05-06 23:03:05 +00001145 Availability: Unix, Windows.
1146
Georg Brandl116aa622007-08-15 14:28:22 +00001147
Georg Brandlc1673682010-12-02 09:06:12 +00001148.. function:: makedirs(path, mode=0o777, exist_ok=False)
Georg Brandl116aa622007-08-15 14:28:22 +00001149
1150 .. index::
1151 single: directory; creating
1152 single: UNC paths; and os.makedirs()
1153
1154 Recursive directory creation function. Like :func:`mkdir`, but makes all
Terry Reedy5a22b652010-12-02 07:05:56 +00001155 intermediate-level directories needed to contain the leaf directory. If
Georg Brandlc1673682010-12-02 09:06:12 +00001156 the target directory with the same mode as specified already exists,
Terry Reedy5a22b652010-12-02 07:05:56 +00001157 raises an :exc:`OSError` exception if *exist_ok* is False, otherwise no
1158 exception is raised. If the directory cannot be created in other cases,
1159 raises an :exc:`OSError` exception. The default *mode* is ``0o777`` (octal).
Georg Brandlc1673682010-12-02 09:06:12 +00001160 On some systems, *mode* is ignored. Where it is used, the current umask
Terry Reedy5a22b652010-12-02 07:05:56 +00001161 value is first masked out.
Georg Brandl116aa622007-08-15 14:28:22 +00001162
1163 .. note::
1164
Georg Brandlc1673682010-12-02 09:06:12 +00001165 :func:`makedirs` will become confused if the path elements to create
1166 include :data:`pardir`.
Georg Brandl116aa622007-08-15 14:28:22 +00001167
Georg Brandl55ac8f02007-09-01 13:51:09 +00001168 This function handles UNC paths correctly.
Georg Brandl116aa622007-08-15 14:28:22 +00001169
Terry Reedy5a22b652010-12-02 07:05:56 +00001170 .. versionadded:: 3.2
1171 The *exist_ok* parameter.
1172
Georg Brandl116aa622007-08-15 14:28:22 +00001173
1174.. function:: pathconf(path, name)
1175
1176 Return system configuration information relevant to a named file. *name*
1177 specifies the configuration value to retrieve; it may be a string which is the
1178 name of a defined system value; these names are specified in a number of
1179 standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define
1180 additional names as well. The names known to the host operating system are
1181 given in the ``pathconf_names`` dictionary. For configuration variables not
1182 included in that mapping, passing an integer for *name* is also accepted.
Georg Brandl116aa622007-08-15 14:28:22 +00001183
1184 If *name* is a string and is not known, :exc:`ValueError` is raised. If a
1185 specific value for *name* is not supported by the host system, even if it is
1186 included in ``pathconf_names``, an :exc:`OSError` is raised with
1187 :const:`errno.EINVAL` for the error number.
1188
Benjamin Petersonf650e462010-05-06 23:03:05 +00001189 Availability: Unix.
1190
Georg Brandl116aa622007-08-15 14:28:22 +00001191
1192.. data:: pathconf_names
1193
1194 Dictionary mapping names accepted by :func:`pathconf` and :func:`fpathconf` to
1195 the integer values defined for those names by the host operating system. This
1196 can be used to determine the set of names known to the system. Availability:
Georg Brandlc575c902008-09-13 17:46:05 +00001197 Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001198
1199
1200.. function:: readlink(path)
1201
1202 Return a string representing the path to which the symbolic link points. The
1203 result may be either an absolute or relative pathname; if it is relative, it may
1204 be converted to an absolute pathname using ``os.path.join(os.path.dirname(path),
1205 result)``.
1206
Georg Brandl76e55382008-10-08 16:34:57 +00001207 If the *path* is a string object, the result will also be a string object,
1208 and the call may raise an UnicodeDecodeError. If the *path* is a bytes
1209 object, the result will be a bytes object.
Georg Brandl116aa622007-08-15 14:28:22 +00001210
Brian Curtinc7395692010-07-09 15:15:09 +00001211 Availability: Unix, Windows
1212
Georg Brandlb3823372010-07-10 08:58:37 +00001213 .. versionchanged:: 3.2
1214 Added support for Windows 6.0 (Vista) symbolic links.
Georg Brandl116aa622007-08-15 14:28:22 +00001215
1216
1217.. function:: remove(path)
1218
Georg Brandla6053b42009-09-01 08:11:14 +00001219 Remove (delete) the file *path*. If *path* is a directory, :exc:`OSError` is
1220 raised; see :func:`rmdir` below to remove a directory. This is identical to
1221 the :func:`unlink` function documented below. On Windows, attempting to
1222 remove a file that is in use causes an exception to be raised; on Unix, the
1223 directory entry is removed but the storage allocated to the file is not made
Benjamin Petersonf650e462010-05-06 23:03:05 +00001224 available until the original file is no longer in use.
1225
1226 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001227
1228
1229.. function:: removedirs(path)
1230
1231 .. index:: single: directory; deleting
1232
Christian Heimesfaf2f632008-01-06 16:59:19 +00001233 Remove directories recursively. Works like :func:`rmdir` except that, if the
Georg Brandl116aa622007-08-15 14:28:22 +00001234 leaf directory is successfully removed, :func:`removedirs` tries to
1235 successively remove every parent directory mentioned in *path* until an error
1236 is raised (which is ignored, because it generally means that a parent directory
1237 is not empty). For example, ``os.removedirs('foo/bar/baz')`` will first remove
1238 the directory ``'foo/bar/baz'``, and then remove ``'foo/bar'`` and ``'foo'`` if
1239 they are empty. Raises :exc:`OSError` if the leaf directory could not be
1240 successfully removed.
1241
Georg Brandl116aa622007-08-15 14:28:22 +00001242
1243.. function:: rename(src, dst)
1244
1245 Rename the file or directory *src* to *dst*. If *dst* is a directory,
1246 :exc:`OSError` will be raised. On Unix, if *dst* exists and is a file, it will
Christian Heimesfaf2f632008-01-06 16:59:19 +00001247 be replaced silently if the user has permission. The operation may fail on some
Georg Brandl116aa622007-08-15 14:28:22 +00001248 Unix flavors if *src* and *dst* are on different filesystems. If successful,
1249 the renaming will be an atomic operation (this is a POSIX requirement). On
1250 Windows, if *dst* already exists, :exc:`OSError` will be raised even if it is a
1251 file; there may be no way to implement an atomic rename when *dst* names an
Benjamin Petersonf650e462010-05-06 23:03:05 +00001252 existing file.
1253
1254 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001255
1256
1257.. function:: renames(old, new)
1258
1259 Recursive directory or file renaming function. Works like :func:`rename`, except
1260 creation of any intermediate directories needed to make the new pathname good is
1261 attempted first. After the rename, directories corresponding to rightmost path
1262 segments of the old name will be pruned away using :func:`removedirs`.
1263
Georg Brandl116aa622007-08-15 14:28:22 +00001264 .. note::
1265
1266 This function can fail with the new directory structure made if you lack
1267 permissions needed to remove the leaf directory or file.
1268
1269
1270.. function:: rmdir(path)
1271
Georg Brandla6053b42009-09-01 08:11:14 +00001272 Remove (delete) the directory *path*. Only works when the directory is
1273 empty, otherwise, :exc:`OSError` is raised. In order to remove whole
Benjamin Petersonf650e462010-05-06 23:03:05 +00001274 directory trees, :func:`shutil.rmtree` can be used.
1275
1276 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001277
1278
1279.. function:: stat(path)
1280
R. David Murray7b1aae92011-01-24 19:34:58 +00001281 Perform the equivalent of a :c:func:`stat` system call on the given path.
1282 (This function follows symlinks; to stat a symlink use :func:`lstat`.)
Georg Brandl116aa622007-08-15 14:28:22 +00001283
R. David Murray7b1aae92011-01-24 19:34:58 +00001284 The return value is an object whose attributes correspond to the members
1285 of the :c:type:`stat` structure, namely:
1286
1287 * :attr:`st_mode` - protection bits,
1288 * :attr:`st_ino` - inode number,
1289 * :attr:`st_dev` - device,
1290 * :attr:`st_nlink` - number of hard links,
1291 * :attr:`st_uid` - user id of owner,
1292 * :attr:`st_gid` - group id of owner,
1293 * :attr:`st_size` - size of file, in bytes,
1294 * :attr:`st_atime` - time of most recent access,
1295 * :attr:`st_mtime` - time of most recent content modification,
1296 * :attr:`st_ctime` - platform dependent; time of most recent metadata change on
1297 Unix, or the time of creation on Windows)
Georg Brandl116aa622007-08-15 14:28:22 +00001298
1299 On some Unix systems (such as Linux), the following attributes may also be
R. David Murray7b1aae92011-01-24 19:34:58 +00001300 available:
1301
1302 * :attr:`st_blocks` - number of blocks allocated for file
1303 * :attr:`st_blksize` - filesystem blocksize
1304 * :attr:`st_rdev` - type of device if an inode device
1305 * :attr:`st_flags` - user defined flags for file
Georg Brandl116aa622007-08-15 14:28:22 +00001306
1307 On other Unix systems (such as FreeBSD), the following attributes may be
R. David Murray7b1aae92011-01-24 19:34:58 +00001308 available (but may be only filled out if root tries to use them):
1309
1310 * :attr:`st_gen` - file generation number
1311 * :attr:`st_birthtime` - time of file creation
Georg Brandl116aa622007-08-15 14:28:22 +00001312
1313 On Mac OS systems, the following attributes may also be available:
Georg Brandl116aa622007-08-15 14:28:22 +00001314
R. David Murray7b1aae92011-01-24 19:34:58 +00001315 * :attr:`st_rsize`
1316 * :attr:`st_creator`
1317 * :attr:`st_type`
Georg Brandl116aa622007-08-15 14:28:22 +00001318
1319 .. note::
1320
1321 The exact meaning and resolution of the :attr:`st_atime`, :attr:`st_mtime`, and
1322 :attr:`st_ctime` members depends on the operating system and the file system.
1323 For example, on Windows systems using the FAT or FAT32 file systems,
1324 :attr:`st_mtime` has 2-second resolution, and :attr:`st_atime` has only 1-day
1325 resolution. See your operating system documentation for details.
1326
R. David Murray7b1aae92011-01-24 19:34:58 +00001327 For backward compatibility, the return value of :func:`~os.stat` is also accessible
1328 as a tuple of at least 10 integers giving the most important (and portable)
1329 members of the :c:type:`stat` structure, in the order :attr:`st_mode`,
1330 :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`,
1331 :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`,
1332 :attr:`st_ctime`. More items may be added at the end by some implementations.
1333
1334 .. index:: module: stat
1335
1336 The standard module :mod:`stat` defines functions and constants that are useful
1337 for extracting information from a :c:type:`stat` structure. (On Windows, some
1338 items are filled with dummy values.)
1339
1340 Example::
1341
1342 >>> import os
1343 >>> statinfo = os.stat('somefile.txt')
1344 >>> statinfo
Raymond Hettinger8f0ae9a2011-02-18 00:53:55 +00001345 posix.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,
1346 st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,
1347 st_mtime=1297230027, st_ctime=1297230027)
R. David Murray7b1aae92011-01-24 19:34:58 +00001348 >>> statinfo.st_size
Raymond Hettinger8f0ae9a2011-02-18 00:53:55 +00001349 264
R. David Murray7b1aae92011-01-24 19:34:58 +00001350
Georg Brandlc575c902008-09-13 17:46:05 +00001351 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001352
Georg Brandl116aa622007-08-15 14:28:22 +00001353
1354.. function:: stat_float_times([newvalue])
1355
1356 Determine whether :class:`stat_result` represents time stamps as float objects.
R. David Murray7b1aae92011-01-24 19:34:58 +00001357 If *newvalue* is ``True``, future calls to :func:`~os.stat` return floats, if it is
Georg Brandl116aa622007-08-15 14:28:22 +00001358 ``False``, future calls return ints. If *newvalue* is omitted, return the
1359 current setting.
1360
1361 For compatibility with older Python versions, accessing :class:`stat_result` as
1362 a tuple always returns integers.
1363
Georg Brandl55ac8f02007-09-01 13:51:09 +00001364 Python now returns float values by default. Applications which do not work
1365 correctly with floating point time stamps can use this function to restore the
1366 old behaviour.
Georg Brandl116aa622007-08-15 14:28:22 +00001367
1368 The resolution of the timestamps (that is the smallest possible fraction)
1369 depends on the system. Some systems only support second resolution; on these
1370 systems, the fraction will always be zero.
1371
1372 It is recommended that this setting is only changed at program startup time in
1373 the *__main__* module; libraries should never change this setting. If an
1374 application uses a library that works incorrectly if floating point time stamps
1375 are processed, this application should turn the feature off until the library
1376 has been corrected.
1377
1378
1379.. function:: statvfs(path)
1380
Georg Brandl60203b42010-10-06 10:11:56 +00001381 Perform a :c:func:`statvfs` system call on the given path. The return value is
Georg Brandl116aa622007-08-15 14:28:22 +00001382 an object whose attributes describe the filesystem on the given path, and
Georg Brandl60203b42010-10-06 10:11:56 +00001383 correspond to the members of the :c:type:`statvfs` structure, namely:
Georg Brandl116aa622007-08-15 14:28:22 +00001384 :attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`,
1385 :attr:`f_bavail`, :attr:`f_files`, :attr:`f_ffree`, :attr:`f_favail`,
Benjamin Petersonf650e462010-05-06 23:03:05 +00001386 :attr:`f_flag`, :attr:`f_namemax`.
1387
Andrew M. Kuchling4ea04a32010-08-18 22:30:34 +00001388 Two module-level constants are defined for the :attr:`f_flag` attribute's
1389 bit-flags: if :const:`ST_RDONLY` is set, the filesystem is mounted
1390 read-only, and if :const:`ST_NOSUID` is set, the semantics of
1391 setuid/setgid bits are disabled or not supported.
1392
1393 .. versionchanged:: 3.2
1394 The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added.
1395
Benjamin Petersonf650e462010-05-06 23:03:05 +00001396 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001397
Georg Brandl116aa622007-08-15 14:28:22 +00001398
Benjamin Peterson5879d412009-03-30 14:51:56 +00001399.. function:: symlink(source, link_name)
Georg Brandl64a41ed2010-10-06 08:52:48 +00001400 symlink(source, link_name, target_is_directory=False)
Georg Brandl116aa622007-08-15 14:28:22 +00001401
Brian Curtinc7395692010-07-09 15:15:09 +00001402 Create a symbolic link pointing to *source* named *link_name*.
1403
Georg Brandl64a41ed2010-10-06 08:52:48 +00001404 On Windows, symlink version takes an additional optional parameter,
1405 *target_is_directory*, which defaults to ``False``.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001406
Georg Brandl64a41ed2010-10-06 08:52:48 +00001407 On Windows, a symlink represents a file or a directory, and does not morph to
1408 the target dynamically. For this reason, when creating a symlink on Windows,
1409 if the target is not already present, the symlink will default to being a
1410 file symlink. If *target_is_directory* is set to ``True``, the symlink will
1411 be created as a directory symlink. This parameter is ignored if the target
1412 exists (and the symlink is created with the same type as the target).
Brian Curtind40e6f72010-07-08 21:39:08 +00001413
Georg Brandl64a41ed2010-10-06 08:52:48 +00001414 Symbolic link support was introduced in Windows 6.0 (Vista). :func:`symlink`
1415 will raise a :exc:`NotImplementedError` on Windows versions earlier than 6.0.
Brian Curtin52173d42010-12-02 18:29:18 +00001416
1417 .. note::
1418
Brian Curtin96245592010-12-28 17:08:22 +00001419 The *SeCreateSymbolicLinkPrivilege* is required in order to successfully
1420 create symlinks. This privilege is not typically granted to regular
1421 users but is available to accounts which can escalate privileges to the
1422 administrator level. Either obtaining the privilege or running your
1423 application as an administrator are ways to successfully create symlinks.
1424
1425
1426 :exc:`OSError` is raised when the function is called by an unprivileged
1427 user.
Brian Curtind40e6f72010-07-08 21:39:08 +00001428
Georg Brandl64a41ed2010-10-06 08:52:48 +00001429 Availability: Unix, Windows.
Brian Curtinc7395692010-07-09 15:15:09 +00001430
Georg Brandlb3823372010-07-10 08:58:37 +00001431 .. versionchanged:: 3.2
1432 Added support for Windows 6.0 (Vista) symbolic links.
Georg Brandl116aa622007-08-15 14:28:22 +00001433
1434
Georg Brandl116aa622007-08-15 14:28:22 +00001435.. function:: unlink(path)
1436
Georg Brandla6053b42009-09-01 08:11:14 +00001437 Remove (delete) the file *path*. This is the same function as
1438 :func:`remove`; the :func:`unlink` name is its traditional Unix
Benjamin Petersonf650e462010-05-06 23:03:05 +00001439 name.
1440
1441 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001442
1443
1444.. function:: utime(path, times)
1445
Benjamin Peterson4cd6a952008-08-17 20:23:46 +00001446 Set the access and modified times of the file specified by *path*. If *times*
1447 is ``None``, then the file's access and modified times are set to the current
1448 time. (The effect is similar to running the Unix program :program:`touch` on
1449 the path.) Otherwise, *times* must be a 2-tuple of numbers, of the form
1450 ``(atime, mtime)`` which is used to set the access and modified times,
1451 respectively. Whether a directory can be given for *path* depends on whether
1452 the operating system implements directories as files (for example, Windows
1453 does not). Note that the exact times you set here may not be returned by a
R. David Murray7b1aae92011-01-24 19:34:58 +00001454 subsequent :func:`~os.stat` call, depending on the resolution with which your
1455 operating system records access and modification times; see :func:`~os.stat`.
Georg Brandl116aa622007-08-15 14:28:22 +00001456
Georg Brandlc575c902008-09-13 17:46:05 +00001457 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001458
1459
Georg Brandl18244152009-09-02 20:34:52 +00001460.. function:: walk(top, topdown=True, onerror=None, followlinks=False)
Georg Brandl116aa622007-08-15 14:28:22 +00001461
1462 .. index::
1463 single: directory; walking
1464 single: directory; traversal
1465
Christian Heimesfaf2f632008-01-06 16:59:19 +00001466 Generate the file names in a directory tree by walking the tree
1467 either top-down or bottom-up. For each directory in the tree rooted at directory
Georg Brandl116aa622007-08-15 14:28:22 +00001468 *top* (including *top* itself), it yields a 3-tuple ``(dirpath, dirnames,
1469 filenames)``.
1470
1471 *dirpath* is a string, the path to the directory. *dirnames* is a list of the
1472 names of the subdirectories in *dirpath* (excluding ``'.'`` and ``'..'``).
1473 *filenames* is a list of the names of the non-directory files in *dirpath*.
1474 Note that the names in the lists contain no path components. To get a full path
1475 (which begins with *top*) to a file or directory in *dirpath*, do
1476 ``os.path.join(dirpath, name)``.
1477
Christian Heimesfaf2f632008-01-06 16:59:19 +00001478 If optional argument *topdown* is ``True`` or not specified, the triple for a
Georg Brandl116aa622007-08-15 14:28:22 +00001479 directory is generated before the triples for any of its subdirectories
Christian Heimesfaf2f632008-01-06 16:59:19 +00001480 (directories are generated top-down). If *topdown* is ``False``, the triple for a
Georg Brandl116aa622007-08-15 14:28:22 +00001481 directory is generated after the triples for all of its subdirectories
Christian Heimesfaf2f632008-01-06 16:59:19 +00001482 (directories are generated bottom-up).
Georg Brandl116aa622007-08-15 14:28:22 +00001483
Christian Heimesfaf2f632008-01-06 16:59:19 +00001484 When *topdown* is ``True``, the caller can modify the *dirnames* list in-place
Georg Brandl116aa622007-08-15 14:28:22 +00001485 (perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only
1486 recurse into the subdirectories whose names remain in *dirnames*; this can be
1487 used to prune the search, impose a specific order of visiting, or even to inform
1488 :func:`walk` about directories the caller creates or renames before it resumes
Christian Heimesfaf2f632008-01-06 16:59:19 +00001489 :func:`walk` again. Modifying *dirnames* when *topdown* is ``False`` is
Georg Brandl116aa622007-08-15 14:28:22 +00001490 ineffective, because in bottom-up mode the directories in *dirnames* are
1491 generated before *dirpath* itself is generated.
1492
Christian Heimesfaf2f632008-01-06 16:59:19 +00001493 By default errors from the :func:`listdir` call are ignored. If optional
Georg Brandl116aa622007-08-15 14:28:22 +00001494 argument *onerror* is specified, it should be a function; it will be called with
1495 one argument, an :exc:`OSError` instance. It can report the error to continue
1496 with the walk, or raise the exception to abort the walk. Note that the filename
1497 is available as the ``filename`` attribute of the exception object.
1498
1499 By default, :func:`walk` will not walk down into symbolic links that resolve to
Christian Heimesfaf2f632008-01-06 16:59:19 +00001500 directories. Set *followlinks* to ``True`` to visit directories pointed to by
Georg Brandl116aa622007-08-15 14:28:22 +00001501 symlinks, on systems that support them.
1502
Georg Brandl116aa622007-08-15 14:28:22 +00001503 .. note::
1504
Christian Heimesfaf2f632008-01-06 16:59:19 +00001505 Be aware that setting *followlinks* to ``True`` can lead to infinite recursion if a
Georg Brandl116aa622007-08-15 14:28:22 +00001506 link points to a parent directory of itself. :func:`walk` does not keep track of
1507 the directories it visited already.
1508
1509 .. note::
1510
1511 If you pass a relative pathname, don't change the current working directory
1512 between resumptions of :func:`walk`. :func:`walk` never changes the current
1513 directory, and assumes that its caller doesn't either.
1514
1515 This example displays the number of bytes taken by non-directory files in each
1516 directory under the starting directory, except that it doesn't look under any
1517 CVS subdirectory::
1518
1519 import os
1520 from os.path import join, getsize
1521 for root, dirs, files in os.walk('python/Lib/email'):
Georg Brandl6911e3c2007-09-04 07:15:32 +00001522 print(root, "consumes", end=" ")
1523 print(sum(getsize(join(root, name)) for name in files), end=" ")
1524 print("bytes in", len(files), "non-directory files")
Georg Brandl116aa622007-08-15 14:28:22 +00001525 if 'CVS' in dirs:
1526 dirs.remove('CVS') # don't visit CVS directories
1527
Christian Heimesfaf2f632008-01-06 16:59:19 +00001528 In the next example, walking the tree bottom-up is essential: :func:`rmdir`
Georg Brandl116aa622007-08-15 14:28:22 +00001529 doesn't allow deleting a directory before the directory is empty::
1530
Christian Heimesfaf2f632008-01-06 16:59:19 +00001531 # Delete everything reachable from the directory named in "top",
Georg Brandl116aa622007-08-15 14:28:22 +00001532 # assuming there are no symbolic links.
1533 # CAUTION: This is dangerous! For example, if top == '/', it
1534 # could delete all your disk files.
1535 import os
1536 for root, dirs, files in os.walk(top, topdown=False):
1537 for name in files:
1538 os.remove(os.path.join(root, name))
1539 for name in dirs:
1540 os.rmdir(os.path.join(root, name))
1541
Georg Brandl116aa622007-08-15 14:28:22 +00001542
1543.. _os-process:
1544
1545Process Management
1546------------------
1547
1548These functions may be used to create and manage processes.
1549
1550The various :func:`exec\*` functions take a list of arguments for the new
1551program loaded into the process. In each case, the first of these arguments is
1552passed to the new program as its own name rather than as an argument a user may
1553have typed on a command line. For the C programmer, this is the ``argv[0]``
Georg Brandl60203b42010-10-06 10:11:56 +00001554passed to a program's :c:func:`main`. For example, ``os.execv('/bin/echo',
Georg Brandl116aa622007-08-15 14:28:22 +00001555['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem
1556to be ignored.
1557
1558
1559.. function:: abort()
1560
1561 Generate a :const:`SIGABRT` signal to the current process. On Unix, the default
1562 behavior is to produce a core dump; on Windows, the process immediately returns
1563 an exit code of ``3``. Be aware that programs which use :func:`signal.signal`
1564 to register a handler for :const:`SIGABRT` will behave differently.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001565
Georg Brandlc575c902008-09-13 17:46:05 +00001566 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001567
1568
1569.. function:: execl(path, arg0, arg1, ...)
1570 execle(path, arg0, arg1, ..., env)
1571 execlp(file, arg0, arg1, ...)
1572 execlpe(file, arg0, arg1, ..., env)
1573 execv(path, args)
1574 execve(path, args, env)
1575 execvp(file, args)
1576 execvpe(file, args, env)
1577
1578 These functions all execute a new program, replacing the current process; they
1579 do not return. On Unix, the new executable is loaded into the current process,
Christian Heimesfaf2f632008-01-06 16:59:19 +00001580 and will have the same process id as the caller. Errors will be reported as
Georg Brandl48310cd2009-01-03 21:18:54 +00001581 :exc:`OSError` exceptions.
Benjamin Petersone9bbc8b2008-09-28 02:06:32 +00001582
1583 The current process is replaced immediately. Open file objects and
1584 descriptors are not flushed, so if there may be data buffered
1585 on these open files, you should flush them using
1586 :func:`sys.stdout.flush` or :func:`os.fsync` before calling an
1587 :func:`exec\*` function.
Georg Brandl116aa622007-08-15 14:28:22 +00001588
Christian Heimesfaf2f632008-01-06 16:59:19 +00001589 The "l" and "v" variants of the :func:`exec\*` functions differ in how
1590 command-line arguments are passed. The "l" variants are perhaps the easiest
Georg Brandl116aa622007-08-15 14:28:22 +00001591 to work with if the number of parameters is fixed when the code is written; the
1592 individual parameters simply become additional parameters to the :func:`execl\*`
Christian Heimesfaf2f632008-01-06 16:59:19 +00001593 functions. The "v" variants are good when the number of parameters is
Georg Brandl116aa622007-08-15 14:28:22 +00001594 variable, with the arguments being passed in a list or tuple as the *args*
1595 parameter. In either case, the arguments to the child process should start with
1596 the name of the command being run, but this is not enforced.
1597
Christian Heimesfaf2f632008-01-06 16:59:19 +00001598 The variants which include a "p" near the end (:func:`execlp`,
Georg Brandl116aa622007-08-15 14:28:22 +00001599 :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the
1600 :envvar:`PATH` environment variable to locate the program *file*. When the
1601 environment is being replaced (using one of the :func:`exec\*e` variants,
1602 discussed in the next paragraph), the new environment is used as the source of
1603 the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle`,
1604 :func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable to
1605 locate the executable; *path* must contain an appropriate absolute or relative
1606 path.
1607
1608 For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (note
Christian Heimesfaf2f632008-01-06 16:59:19 +00001609 that these all end in "e"), the *env* parameter must be a mapping which is
Christian Heimesa342c012008-04-20 21:01:16 +00001610 used to define the environment variables for the new process (these are used
1611 instead of the current process' environment); the functions :func:`execl`,
Georg Brandl116aa622007-08-15 14:28:22 +00001612 :func:`execlp`, :func:`execv`, and :func:`execvp` all cause the new process to
Georg Brandl48310cd2009-01-03 21:18:54 +00001613 inherit the environment of the current process.
Benjamin Petersone9bbc8b2008-09-28 02:06:32 +00001614
1615 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001616
1617
1618.. function:: _exit(n)
1619
Georg Brandl6f4e68d2010-10-17 10:51:45 +00001620 Exit the process with status *n*, without calling cleanup handlers, flushing
Benjamin Petersonf650e462010-05-06 23:03:05 +00001621 stdio buffers, etc.
1622
1623 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001624
1625 .. note::
1626
Georg Brandl6f4e68d2010-10-17 10:51:45 +00001627 The standard way to exit is ``sys.exit(n)``. :func:`_exit` should
1628 normally only be used in the child process after a :func:`fork`.
Georg Brandl116aa622007-08-15 14:28:22 +00001629
Christian Heimesfaf2f632008-01-06 16:59:19 +00001630The following exit codes are defined and can be used with :func:`_exit`,
Georg Brandl116aa622007-08-15 14:28:22 +00001631although they are not required. These are typically used for system programs
1632written in Python, such as a mail server's external command delivery program.
1633
1634.. note::
1635
1636 Some of these may not be available on all Unix platforms, since there is some
1637 variation. These constants are defined where they are defined by the underlying
1638 platform.
1639
1640
1641.. data:: EX_OK
1642
Benjamin Petersonf650e462010-05-06 23:03:05 +00001643 Exit code that means no error occurred.
1644
1645 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001646
Georg Brandl116aa622007-08-15 14:28:22 +00001647
1648.. data:: EX_USAGE
1649
1650 Exit code that means the command was used incorrectly, such as when the wrong
Benjamin Petersonf650e462010-05-06 23:03:05 +00001651 number of arguments are given.
1652
1653 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001654
Georg Brandl116aa622007-08-15 14:28:22 +00001655
1656.. data:: EX_DATAERR
1657
Benjamin Petersonf650e462010-05-06 23:03:05 +00001658 Exit code that means the input data was incorrect.
1659
1660 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001661
Georg Brandl116aa622007-08-15 14:28:22 +00001662
1663.. data:: EX_NOINPUT
1664
1665 Exit code that means an input file did not exist or was not readable.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001666
Georg Brandlc575c902008-09-13 17:46:05 +00001667 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001668
Georg Brandl116aa622007-08-15 14:28:22 +00001669
1670.. data:: EX_NOUSER
1671
Benjamin Petersonf650e462010-05-06 23:03:05 +00001672 Exit code that means a specified user did not exist.
1673
1674 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001675
Georg Brandl116aa622007-08-15 14:28:22 +00001676
1677.. data:: EX_NOHOST
1678
Benjamin Petersonf650e462010-05-06 23:03:05 +00001679 Exit code that means a specified host did not exist.
1680
1681 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001682
Georg Brandl116aa622007-08-15 14:28:22 +00001683
1684.. data:: EX_UNAVAILABLE
1685
Benjamin Petersonf650e462010-05-06 23:03:05 +00001686 Exit code that means that a required service is unavailable.
1687
1688 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001689
Georg Brandl116aa622007-08-15 14:28:22 +00001690
1691.. data:: EX_SOFTWARE
1692
Benjamin Petersonf650e462010-05-06 23:03:05 +00001693 Exit code that means an internal software error was detected.
1694
1695 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001696
Georg Brandl116aa622007-08-15 14:28:22 +00001697
1698.. data:: EX_OSERR
1699
1700 Exit code that means an operating system error was detected, such as the
Benjamin Petersonf650e462010-05-06 23:03:05 +00001701 inability to fork or create a pipe.
1702
1703 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001704
Georg Brandl116aa622007-08-15 14:28:22 +00001705
1706.. data:: EX_OSFILE
1707
1708 Exit code that means some system file did not exist, could not be opened, or had
Benjamin Petersonf650e462010-05-06 23:03:05 +00001709 some other kind of error.
1710
1711 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001712
Georg Brandl116aa622007-08-15 14:28:22 +00001713
1714.. data:: EX_CANTCREAT
1715
1716 Exit code that means a user specified output file could not be created.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001717
Georg Brandlc575c902008-09-13 17:46:05 +00001718 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001719
Georg Brandl116aa622007-08-15 14:28:22 +00001720
1721.. data:: EX_IOERR
1722
1723 Exit code that means that an error occurred while doing I/O on some file.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001724
Georg Brandlc575c902008-09-13 17:46:05 +00001725 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001726
Georg Brandl116aa622007-08-15 14:28:22 +00001727
1728.. data:: EX_TEMPFAIL
1729
1730 Exit code that means a temporary failure occurred. This indicates something
1731 that may not really be an error, such as a network connection that couldn't be
Benjamin Petersonf650e462010-05-06 23:03:05 +00001732 made during a retryable operation.
1733
1734 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001735
Georg Brandl116aa622007-08-15 14:28:22 +00001736
1737.. data:: EX_PROTOCOL
1738
1739 Exit code that means that a protocol exchange was illegal, invalid, or not
Benjamin Petersonf650e462010-05-06 23:03:05 +00001740 understood.
1741
1742 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001743
Georg Brandl116aa622007-08-15 14:28:22 +00001744
1745.. data:: EX_NOPERM
1746
1747 Exit code that means that there were insufficient permissions to perform the
Benjamin Petersonf650e462010-05-06 23:03:05 +00001748 operation (but not intended for file system problems).
1749
1750 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001751
Georg Brandl116aa622007-08-15 14:28:22 +00001752
1753.. data:: EX_CONFIG
1754
1755 Exit code that means that some kind of configuration error occurred.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001756
Georg Brandlc575c902008-09-13 17:46:05 +00001757 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001758
Georg Brandl116aa622007-08-15 14:28:22 +00001759
1760.. data:: EX_NOTFOUND
1761
Benjamin Petersonf650e462010-05-06 23:03:05 +00001762 Exit code that means something like "an entry was not found".
1763
1764 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001765
Georg Brandl116aa622007-08-15 14:28:22 +00001766
1767.. function:: fork()
1768
Christian Heimesfaf2f632008-01-06 16:59:19 +00001769 Fork a child process. Return ``0`` in the child and the child's process id in the
Christian Heimesdd15f6c2008-03-16 00:07:10 +00001770 parent. If an error occurs :exc:`OSError` is raised.
Benjamin Petersonbcd8ac32008-10-10 22:20:52 +00001771
1772 Note that some platforms including FreeBSD <= 6.3, Cygwin and OS/2 EMX have
1773 known issues when using fork() from a thread.
1774
Georg Brandlc575c902008-09-13 17:46:05 +00001775 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001776
1777
1778.. function:: forkpty()
1779
1780 Fork a child process, using a new pseudo-terminal as the child's controlling
1781 terminal. Return a pair of ``(pid, fd)``, where *pid* is ``0`` in the child, the
1782 new child's process id in the parent, and *fd* is the file descriptor of the
1783 master end of the pseudo-terminal. For a more portable approach, use the
Christian Heimesdd15f6c2008-03-16 00:07:10 +00001784 :mod:`pty` module. If an error occurs :exc:`OSError` is raised.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001785
Georg Brandlc575c902008-09-13 17:46:05 +00001786 Availability: some flavors of Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001787
1788
1789.. function:: kill(pid, sig)
1790
1791 .. index::
1792 single: process; killing
1793 single: process; signalling
1794
1795 Send signal *sig* to the process *pid*. Constants for the specific signals
1796 available on the host platform are defined in the :mod:`signal` module.
Brian Curtineb24d742010-04-12 17:16:38 +00001797
1798 Windows: The :data:`signal.CTRL_C_EVENT` and
1799 :data:`signal.CTRL_BREAK_EVENT` signals are special signals which can
1800 only be sent to console processes which share a common console window,
1801 e.g., some subprocesses. Any other value for *sig* will cause the process
1802 to be unconditionally killed by the TerminateProcess API, and the exit code
1803 will be set to *sig*. The Windows version of :func:`kill` additionally takes
1804 process handles to be killed.
Georg Brandl116aa622007-08-15 14:28:22 +00001805
Georg Brandl67b21b72010-08-17 15:07:14 +00001806 .. versionadded:: 3.2
1807 Windows support.
Brian Curtin904bd392010-04-20 15:28:06 +00001808
Georg Brandl116aa622007-08-15 14:28:22 +00001809
1810.. function:: killpg(pgid, sig)
1811
1812 .. index::
1813 single: process; killing
1814 single: process; signalling
1815
Benjamin Petersonf650e462010-05-06 23:03:05 +00001816 Send the signal *sig* to the process group *pgid*.
1817
1818 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001819
Georg Brandl116aa622007-08-15 14:28:22 +00001820
1821.. function:: nice(increment)
1822
1823 Add *increment* to the process's "niceness". Return the new niceness.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001824
Georg Brandlc575c902008-09-13 17:46:05 +00001825 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001826
1827
1828.. function:: plock(op)
1829
1830 Lock program segments into memory. The value of *op* (defined in
Benjamin Petersonf650e462010-05-06 23:03:05 +00001831 ``<sys/lock.h>``) determines which segments are locked.
1832
1833 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00001834
1835
1836.. function:: popen(...)
1837 :noindex:
1838
1839 Run child processes, returning opened pipes for communications. These functions
1840 are described in section :ref:`os-newstreams`.
1841
1842
1843.. function:: spawnl(mode, path, ...)
1844 spawnle(mode, path, ..., env)
1845 spawnlp(mode, file, ...)
1846 spawnlpe(mode, file, ..., env)
1847 spawnv(mode, path, args)
1848 spawnve(mode, path, args, env)
1849 spawnvp(mode, file, args)
1850 spawnvpe(mode, file, args, env)
1851
1852 Execute the program *path* in a new process.
1853
1854 (Note that the :mod:`subprocess` module provides more powerful facilities for
1855 spawning new processes and retrieving their results; using that module is
Benjamin Peterson87c8d872009-06-11 22:54:11 +00001856 preferable to using these functions. Check especially the
1857 :ref:`subprocess-replacements` section.)
Georg Brandl116aa622007-08-15 14:28:22 +00001858
Christian Heimesfaf2f632008-01-06 16:59:19 +00001859 If *mode* is :const:`P_NOWAIT`, this function returns the process id of the new
Georg Brandl116aa622007-08-15 14:28:22 +00001860 process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it
1861 exits normally, or ``-signal``, where *signal* is the signal that killed the
Christian Heimesfaf2f632008-01-06 16:59:19 +00001862 process. On Windows, the process id will actually be the process handle, so can
Georg Brandl116aa622007-08-15 14:28:22 +00001863 be used with the :func:`waitpid` function.
1864
Christian Heimesfaf2f632008-01-06 16:59:19 +00001865 The "l" and "v" variants of the :func:`spawn\*` functions differ in how
1866 command-line arguments are passed. The "l" variants are perhaps the easiest
Georg Brandl116aa622007-08-15 14:28:22 +00001867 to work with if the number of parameters is fixed when the code is written; the
1868 individual parameters simply become additional parameters to the
Christian Heimesfaf2f632008-01-06 16:59:19 +00001869 :func:`spawnl\*` functions. The "v" variants are good when the number of
Georg Brandl116aa622007-08-15 14:28:22 +00001870 parameters is variable, with the arguments being passed in a list or tuple as
1871 the *args* parameter. In either case, the arguments to the child process must
1872 start with the name of the command being run.
1873
Christian Heimesfaf2f632008-01-06 16:59:19 +00001874 The variants which include a second "p" near the end (:func:`spawnlp`,
Georg Brandl116aa622007-08-15 14:28:22 +00001875 :func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the
1876 :envvar:`PATH` environment variable to locate the program *file*. When the
1877 environment is being replaced (using one of the :func:`spawn\*e` variants,
1878 discussed in the next paragraph), the new environment is used as the source of
1879 the :envvar:`PATH` variable. The other variants, :func:`spawnl`,
1880 :func:`spawnle`, :func:`spawnv`, and :func:`spawnve`, will not use the
1881 :envvar:`PATH` variable to locate the executable; *path* must contain an
1882 appropriate absolute or relative path.
1883
1884 For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe`
Christian Heimesfaf2f632008-01-06 16:59:19 +00001885 (note that these all end in "e"), the *env* parameter must be a mapping
Christian Heimesa342c012008-04-20 21:01:16 +00001886 which is used to define the environment variables for the new process (they are
1887 used instead of the current process' environment); the functions
Georg Brandl116aa622007-08-15 14:28:22 +00001888 :func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause
Benjamin Petersond23f8222009-04-05 19:13:16 +00001889 the new process to inherit the environment of the current process. Note that
1890 keys and values in the *env* dictionary must be strings; invalid keys or
1891 values will cause the function to fail, with a return value of ``127``.
Georg Brandl116aa622007-08-15 14:28:22 +00001892
1893 As an example, the following calls to :func:`spawnlp` and :func:`spawnvpe` are
1894 equivalent::
1895
1896 import os
1897 os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')
1898
1899 L = ['cp', 'index.html', '/dev/null']
1900 os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)
1901
1902 Availability: Unix, Windows. :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp`
1903 and :func:`spawnvpe` are not available on Windows.
1904
Georg Brandl116aa622007-08-15 14:28:22 +00001905
1906.. data:: P_NOWAIT
1907 P_NOWAITO
1908
1909 Possible values for the *mode* parameter to the :func:`spawn\*` family of
1910 functions. If either of these values is given, the :func:`spawn\*` functions
Christian Heimesfaf2f632008-01-06 16:59:19 +00001911 will return as soon as the new process has been created, with the process id as
Benjamin Petersonf650e462010-05-06 23:03:05 +00001912 the return value.
1913
1914 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001915
Georg Brandl116aa622007-08-15 14:28:22 +00001916
1917.. data:: P_WAIT
1918
1919 Possible value for the *mode* parameter to the :func:`spawn\*` family of
1920 functions. If this is given as *mode*, the :func:`spawn\*` functions will not
1921 return until the new process has run to completion and will return the exit code
1922 of the process the run is successful, or ``-signal`` if a signal kills the
Benjamin Petersonf650e462010-05-06 23:03:05 +00001923 process.
1924
1925 Availability: Unix, Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001926
Georg Brandl116aa622007-08-15 14:28:22 +00001927
1928.. data:: P_DETACH
1929 P_OVERLAY
1930
1931 Possible values for the *mode* parameter to the :func:`spawn\*` family of
1932 functions. These are less portable than those listed above. :const:`P_DETACH`
1933 is similar to :const:`P_NOWAIT`, but the new process is detached from the
1934 console of the calling process. If :const:`P_OVERLAY` is used, the current
1935 process will be replaced; the :func:`spawn\*` function will not return.
Benjamin Petersonf650e462010-05-06 23:03:05 +00001936
Georg Brandl116aa622007-08-15 14:28:22 +00001937 Availability: Windows.
1938
Georg Brandl116aa622007-08-15 14:28:22 +00001939
1940.. function:: startfile(path[, operation])
1941
1942 Start a file with its associated application.
1943
1944 When *operation* is not specified or ``'open'``, this acts like double-clicking
1945 the file in Windows Explorer, or giving the file name as an argument to the
1946 :program:`start` command from the interactive command shell: the file is opened
1947 with whatever application (if any) its extension is associated.
1948
1949 When another *operation* is given, it must be a "command verb" that specifies
1950 what should be done with the file. Common verbs documented by Microsoft are
1951 ``'print'`` and ``'edit'`` (to be used on files) as well as ``'explore'`` and
1952 ``'find'`` (to be used on directories).
1953
1954 :func:`startfile` returns as soon as the associated application is launched.
1955 There is no option to wait for the application to close, and no way to retrieve
1956 the application's exit status. The *path* parameter is relative to the current
1957 directory. If you want to use an absolute path, make sure the first character
Georg Brandl60203b42010-10-06 10:11:56 +00001958 is not a slash (``'/'``); the underlying Win32 :c:func:`ShellExecute` function
Georg Brandl116aa622007-08-15 14:28:22 +00001959 doesn't work if it is. Use the :func:`os.path.normpath` function to ensure that
Benjamin Petersonf650e462010-05-06 23:03:05 +00001960 the path is properly encoded for Win32.
1961
1962 Availability: Windows.
Georg Brandl116aa622007-08-15 14:28:22 +00001963
Georg Brandl116aa622007-08-15 14:28:22 +00001964
1965.. function:: system(command)
1966
1967 Execute the command (a string) in a subshell. This is implemented by calling
Georg Brandl60203b42010-10-06 10:11:56 +00001968 the Standard C function :c:func:`system`, and has the same limitations.
Georg Brandl8f7b4272010-10-14 06:35:53 +00001969 Changes to :data:`sys.stdin`, etc. are not reflected in the environment of
1970 the executed command. If *command* generates any output, it will be sent to
1971 the interpreter standard output stream.
Georg Brandl116aa622007-08-15 14:28:22 +00001972
1973 On Unix, the return value is the exit status of the process encoded in the
Georg Brandl8f7b4272010-10-14 06:35:53 +00001974 format specified for :func:`wait`. Note that POSIX does not specify the
1975 meaning of the return value of the C :c:func:`system` function, so the return
1976 value of the Python function is system-dependent.
Georg Brandl116aa622007-08-15 14:28:22 +00001977
Georg Brandl8f7b4272010-10-14 06:35:53 +00001978 On Windows, the return value is that returned by the system shell after
1979 running *command*. The shell is given by the Windows environment variable
1980 :envvar:`COMSPEC`: it is usually :program:`cmd.exe`, which returns the exit
1981 status of the command run; on systems using a non-native shell, consult your
1982 shell documentation.
Georg Brandl116aa622007-08-15 14:28:22 +00001983
Georg Brandl8f7b4272010-10-14 06:35:53 +00001984 The :mod:`subprocess` module provides more powerful facilities for spawning
1985 new processes and retrieving their results; using that module is preferable
1986 to using this function. See the :ref:`subprocess-replacements` section in
1987 the :mod:`subprocess` documentation for some helpful recipes.
Georg Brandl116aa622007-08-15 14:28:22 +00001988
Benjamin Petersonf650e462010-05-06 23:03:05 +00001989 Availability: Unix, Windows.
1990
Georg Brandl116aa622007-08-15 14:28:22 +00001991
1992.. function:: times()
1993
Benjamin Petersonf650e462010-05-06 23:03:05 +00001994 Return a 5-tuple of floating point numbers indicating accumulated (processor
1995 or other) times, in seconds. The items are: user time, system time,
1996 children's user time, children's system time, and elapsed real time since a
1997 fixed point in the past, in that order. See the Unix manual page
1998 :manpage:`times(2)` or the corresponding Windows Platform API documentation.
1999 On Windows, only the first two items are filled, the others are zero.
2000
2001 Availability: Unix, Windows
Georg Brandl116aa622007-08-15 14:28:22 +00002002
2003
2004.. function:: wait()
2005
2006 Wait for completion of a child process, and return a tuple containing its pid
2007 and exit status indication: a 16-bit number, whose low byte is the signal number
2008 that killed the process, and whose high byte is the exit status (if the signal
2009 number is zero); the high bit of the low byte is set if a core file was
Benjamin Petersonf650e462010-05-06 23:03:05 +00002010 produced.
2011
2012 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002013
2014
2015.. function:: waitpid(pid, options)
2016
2017 The details of this function differ on Unix and Windows.
2018
2019 On Unix: Wait for completion of a child process given by process id *pid*, and
2020 return a tuple containing its process id and exit status indication (encoded as
2021 for :func:`wait`). The semantics of the call are affected by the value of the
2022 integer *options*, which should be ``0`` for normal operation.
2023
2024 If *pid* is greater than ``0``, :func:`waitpid` requests status information for
2025 that specific process. If *pid* is ``0``, the request is for the status of any
2026 child in the process group of the current process. If *pid* is ``-1``, the
2027 request pertains to any child of the current process. If *pid* is less than
2028 ``-1``, status is requested for any process in the process group ``-pid`` (the
2029 absolute value of *pid*).
2030
Benjamin Peterson4cd6a952008-08-17 20:23:46 +00002031 An :exc:`OSError` is raised with the value of errno when the syscall
2032 returns -1.
2033
Georg Brandl116aa622007-08-15 14:28:22 +00002034 On Windows: Wait for completion of a process given by process handle *pid*, and
2035 return a tuple containing *pid*, and its exit status shifted left by 8 bits
2036 (shifting makes cross-platform use of the function easier). A *pid* less than or
2037 equal to ``0`` has no special meaning on Windows, and raises an exception. The
2038 value of integer *options* has no effect. *pid* can refer to any process whose
2039 id is known, not necessarily a child process. The :func:`spawn` functions called
2040 with :const:`P_NOWAIT` return suitable process handles.
2041
2042
2043.. function:: wait3([options])
2044
2045 Similar to :func:`waitpid`, except no process id argument is given and a
2046 3-element tuple containing the child's process id, exit status indication, and
2047 resource usage information is returned. Refer to :mod:`resource`.\
2048 :func:`getrusage` for details on resource usage information. The option
2049 argument is the same as that provided to :func:`waitpid` and :func:`wait4`.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002050
Georg Brandl116aa622007-08-15 14:28:22 +00002051 Availability: Unix.
2052
Georg Brandl116aa622007-08-15 14:28:22 +00002053
2054.. function:: wait4(pid, options)
2055
2056 Similar to :func:`waitpid`, except a 3-element tuple, containing the child's
2057 process id, exit status indication, and resource usage information is returned.
2058 Refer to :mod:`resource`.\ :func:`getrusage` for details on resource usage
2059 information. The arguments to :func:`wait4` are the same as those provided to
Benjamin Petersonf650e462010-05-06 23:03:05 +00002060 :func:`waitpid`.
2061
2062 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002063
Georg Brandl116aa622007-08-15 14:28:22 +00002064
2065.. data:: WNOHANG
2066
2067 The option for :func:`waitpid` to return immediately if no child process status
2068 is available immediately. The function returns ``(0, 0)`` in this case.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002069
Georg Brandlc575c902008-09-13 17:46:05 +00002070 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002071
2072
2073.. data:: WCONTINUED
2074
2075 This option causes child processes to be reported if they have been continued
Benjamin Petersonf650e462010-05-06 23:03:05 +00002076 from a job control stop since their status was last reported.
2077
2078 Availability: Some Unix systems.
Georg Brandl116aa622007-08-15 14:28:22 +00002079
Georg Brandl116aa622007-08-15 14:28:22 +00002080
2081.. data:: WUNTRACED
2082
2083 This option causes child processes to be reported if they have been stopped but
Benjamin Petersonf650e462010-05-06 23:03:05 +00002084 their current state has not been reported since they were stopped.
2085
2086 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002087
Georg Brandl116aa622007-08-15 14:28:22 +00002088
2089The following functions take a process status code as returned by
2090:func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be
2091used to determine the disposition of a process.
2092
Georg Brandl116aa622007-08-15 14:28:22 +00002093.. function:: WCOREDUMP(status)
2094
Christian Heimesfaf2f632008-01-06 16:59:19 +00002095 Return ``True`` if a core dump was generated for the process, otherwise
Benjamin Petersonf650e462010-05-06 23:03:05 +00002096 return ``False``.
2097
2098 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002099
Georg Brandl116aa622007-08-15 14:28:22 +00002100
2101.. function:: WIFCONTINUED(status)
2102
Christian Heimesfaf2f632008-01-06 16:59:19 +00002103 Return ``True`` if the process has been continued from a job control stop,
Benjamin Petersonf650e462010-05-06 23:03:05 +00002104 otherwise return ``False``.
2105
2106 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002107
Georg Brandl116aa622007-08-15 14:28:22 +00002108
2109.. function:: WIFSTOPPED(status)
2110
Christian Heimesfaf2f632008-01-06 16:59:19 +00002111 Return ``True`` if the process has been stopped, otherwise return
Benjamin Petersonf650e462010-05-06 23:03:05 +00002112 ``False``.
2113
2114 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002115
2116
2117.. function:: WIFSIGNALED(status)
2118
Christian Heimesfaf2f632008-01-06 16:59:19 +00002119 Return ``True`` if the process exited due to a signal, otherwise return
Benjamin Petersonf650e462010-05-06 23:03:05 +00002120 ``False``.
2121
2122 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002123
2124
2125.. function:: WIFEXITED(status)
2126
Christian Heimesfaf2f632008-01-06 16:59:19 +00002127 Return ``True`` if the process exited using the :manpage:`exit(2)` system call,
Benjamin Petersonf650e462010-05-06 23:03:05 +00002128 otherwise return ``False``.
2129
2130 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002131
2132
2133.. function:: WEXITSTATUS(status)
2134
2135 If ``WIFEXITED(status)`` is true, return the integer parameter to the
2136 :manpage:`exit(2)` system call. Otherwise, the return value is meaningless.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002137
Georg Brandlc575c902008-09-13 17:46:05 +00002138 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002139
2140
2141.. function:: WSTOPSIG(status)
2142
Benjamin Petersonf650e462010-05-06 23:03:05 +00002143 Return the signal which caused the process to stop.
2144
2145 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002146
2147
2148.. function:: WTERMSIG(status)
2149
Benjamin Petersonf650e462010-05-06 23:03:05 +00002150 Return the signal which caused the process to exit.
2151
2152 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002153
2154
2155.. _os-path:
2156
2157Miscellaneous System Information
2158--------------------------------
2159
2160
2161.. function:: confstr(name)
2162
2163 Return string-valued system configuration values. *name* specifies the
2164 configuration value to retrieve; it may be a string which is the name of a
2165 defined system value; these names are specified in a number of standards (POSIX,
2166 Unix 95, Unix 98, and others). Some platforms define additional names as well.
2167 The names known to the host operating system are given as the keys of the
2168 ``confstr_names`` dictionary. For configuration variables not included in that
Benjamin Petersonf650e462010-05-06 23:03:05 +00002169 mapping, passing an integer for *name* is also accepted.
Georg Brandl116aa622007-08-15 14:28:22 +00002170
2171 If the configuration value specified by *name* isn't defined, ``None`` is
2172 returned.
2173
2174 If *name* is a string and is not known, :exc:`ValueError` is raised. If a
2175 specific value for *name* is not supported by the host system, even if it is
2176 included in ``confstr_names``, an :exc:`OSError` is raised with
2177 :const:`errno.EINVAL` for the error number.
2178
Benjamin Petersonf650e462010-05-06 23:03:05 +00002179 Availability: Unix
2180
Georg Brandl116aa622007-08-15 14:28:22 +00002181
2182.. data:: confstr_names
2183
2184 Dictionary mapping names accepted by :func:`confstr` to the integer values
2185 defined for those names by the host operating system. This can be used to
Benjamin Petersonf650e462010-05-06 23:03:05 +00002186 determine the set of names known to the system.
2187
2188 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002189
2190
2191.. function:: getloadavg()
2192
Christian Heimesa62da1d2008-01-12 19:39:10 +00002193 Return the number of processes in the system run queue averaged over the last
2194 1, 5, and 15 minutes or raises :exc:`OSError` if the load average was
Benjamin Petersonf650e462010-05-06 23:03:05 +00002195 unobtainable.
2196
2197 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002198
Georg Brandl116aa622007-08-15 14:28:22 +00002199
2200.. function:: sysconf(name)
2201
2202 Return integer-valued system configuration values. If the configuration value
2203 specified by *name* isn't defined, ``-1`` is returned. The comments regarding
2204 the *name* parameter for :func:`confstr` apply here as well; the dictionary that
2205 provides information on the known names is given by ``sysconf_names``.
Benjamin Petersonf650e462010-05-06 23:03:05 +00002206
Georg Brandlc575c902008-09-13 17:46:05 +00002207 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002208
2209
2210.. data:: sysconf_names
2211
2212 Dictionary mapping names accepted by :func:`sysconf` to the integer values
2213 defined for those names by the host operating system. This can be used to
Benjamin Petersonf650e462010-05-06 23:03:05 +00002214 determine the set of names known to the system.
2215
2216 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +00002217
Christian Heimesfaf2f632008-01-06 16:59:19 +00002218The following data values are used to support path manipulation operations. These
Georg Brandl116aa622007-08-15 14:28:22 +00002219are defined for all platforms.
2220
2221Higher-level operations on pathnames are defined in the :mod:`os.path` module.
2222
2223
2224.. data:: curdir
2225
2226 The constant string used by the operating system to refer to the current
Georg Brandlc575c902008-09-13 17:46:05 +00002227 directory. This is ``'.'`` for Windows and POSIX. Also available via
2228 :mod:`os.path`.
Georg Brandl116aa622007-08-15 14:28:22 +00002229
2230
2231.. data:: pardir
2232
2233 The constant string used by the operating system to refer to the parent
Georg Brandlc575c902008-09-13 17:46:05 +00002234 directory. This is ``'..'`` for Windows and POSIX. Also available via
2235 :mod:`os.path`.
Georg Brandl116aa622007-08-15 14:28:22 +00002236
2237
2238.. data:: sep
2239
Georg Brandlc575c902008-09-13 17:46:05 +00002240 The character used by the operating system to separate pathname components.
2241 This is ``'/'`` for POSIX and ``'\\'`` for Windows. Note that knowing this
2242 is not sufficient to be able to parse or concatenate pathnames --- use
Georg Brandl116aa622007-08-15 14:28:22 +00002243 :func:`os.path.split` and :func:`os.path.join` --- but it is occasionally
2244 useful. Also available via :mod:`os.path`.
2245
2246
2247.. data:: altsep
2248
2249 An alternative character used by the operating system to separate pathname
2250 components, or ``None`` if only one separator character exists. This is set to
2251 ``'/'`` on Windows systems where ``sep`` is a backslash. Also available via
2252 :mod:`os.path`.
2253
2254
2255.. data:: extsep
2256
2257 The character which separates the base filename from the extension; for example,
2258 the ``'.'`` in :file:`os.py`. Also available via :mod:`os.path`.
2259
Georg Brandl116aa622007-08-15 14:28:22 +00002260
2261.. data:: pathsep
2262
2263 The character conventionally used by the operating system to separate search
2264 path components (as in :envvar:`PATH`), such as ``':'`` for POSIX or ``';'`` for
2265 Windows. Also available via :mod:`os.path`.
2266
2267
2268.. data:: defpath
2269
2270 The default search path used by :func:`exec\*p\*` and :func:`spawn\*p\*` if the
2271 environment doesn't have a ``'PATH'`` key. Also available via :mod:`os.path`.
2272
2273
2274.. data:: linesep
2275
2276 The string used to separate (or, rather, terminate) lines on the current
Georg Brandlc575c902008-09-13 17:46:05 +00002277 platform. This may be a single character, such as ``'\n'`` for POSIX, or
2278 multiple characters, for example, ``'\r\n'`` for Windows. Do not use
2279 *os.linesep* as a line terminator when writing files opened in text mode (the
2280 default); use a single ``'\n'`` instead, on all platforms.
Georg Brandl116aa622007-08-15 14:28:22 +00002281
2282
2283.. data:: devnull
2284
Georg Brandl850a9902010-05-21 22:04:32 +00002285 The file path of the null device. For example: ``'/dev/null'`` for
2286 POSIX, ``'nul'`` for Windows. Also available via :mod:`os.path`.
Georg Brandl116aa622007-08-15 14:28:22 +00002287
Georg Brandl116aa622007-08-15 14:28:22 +00002288
2289.. _os-miscfunc:
2290
2291Miscellaneous Functions
2292-----------------------
2293
2294
2295.. function:: urandom(n)
2296
2297 Return a string of *n* random bytes suitable for cryptographic use.
2298
2299 This function returns random bytes from an OS-specific randomness source. The
2300 returned data should be unpredictable enough for cryptographic applications,
2301 though its exact quality depends on the OS implementation. On a UNIX-like
2302 system this will query /dev/urandom, and on Windows it will use CryptGenRandom.
2303 If a randomness source is not found, :exc:`NotImplementedError` will be raised.