Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libos.tex @ 4566:6403c94de50d legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added safeguard against failure in __del__.
author Guido van Rossum <guido@python.org>
date Wed, 27 Nov 1996 19:39:58 +0000
parents f47bc5554418
children 3468ea8645ca
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \section{Standard Module \sectcode{os}}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
2
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
3 \stmodindex{os}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
4 This module provides a more portable way of using operating system
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
5 (OS) dependent functionality than importing an OS dependent built-in
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
6 module like \code{posix}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
7
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 When the optional built-in module \code{posix} is available, this
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
9 module exports the same functions and data as \code{posix}; otherwise,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
10 it searches for an OS dependent built-in module like \code{mac} and
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 exports the same functions and data as found there. The design of all
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
12 Python's built-in OS dependent modules is such that as long as the same
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 functionality is available, it uses the same interface; e.g., the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 function \code{os.stat(\var{file})} returns stat info about a \var{file} in a
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15 format compatible with the POSIX interface.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 Extensions peculiar to a particular OS are also available through the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 \code{os} module, but using them is of course a threat to portability!
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
19
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 Note that after the first time \code{os} is imported, there is \emph{no}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
21 performance penalty in using functions from \code{os} instead of
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 directly from the OS dependent built-in module, so there should be
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 \emph{no} reason not to use \code{os}!
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
24
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 In addition to whatever the correct OS dependent module exports, the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 following variables and functions are always exported by \code{os}:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 \renewcommand{\indexsubitem}{(in module os)}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
29
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 \begin{datadesc}{name}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
31 The name of the OS dependent module imported. The following names
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
32 have currently been registered: \code{'posix'}, \code{'nt'},
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
33 \code{'dos'}, \code{'mac'}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
35
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 \begin{datadesc}{path}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 The corresponding OS dependent standard module for pathname
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 operations, e.g., \code{posixpath} or \code{macpath}. Thus, (given
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 the proper imports), \code{os.path.split(\var{file})} is equivalent to but
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 more portable than \code{posixpath.split(\var{file})}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
42
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 \begin{datadesc}{curdir}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
44 The constant string used by the OS to refer to the current directory,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 e.g. \code{'.'} for POSIX or \code{':'} for the Mac.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 \begin{datadesc}{pardir}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
49 The constant string used by the OS to refer to the parent directory,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 e.g. \code{'..'} for POSIX or \code{'::'} for the Mac.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
53 \begin{datadesc}{sep}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
54 The character used by the OS to separate pathname components, e.g.\
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
55 \code{'/'} for POSIX or \code{':'} for the Mac. Note that knowing this
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
56 is not sufficient to be able to parse or concatenate pathnames---better
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
57 use \code{os.path.split()} and \code{os.path.join()}---but it is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
58 occasionally useful.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
59 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
60
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
61 \begin{datadesc}{pathsep}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
62 The character conventionally used by the OS to separate search patch
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
63 components (as in \code{\$PATH}), e.g.\ \code{':'} for POSIX or
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
64 \code{';'} for MS-DOS.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
65 \end{datadesc}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
66
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
67 \begin{datadesc}{defpath}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
68 The default search path used by \code{os.exec*p*()} if the environment
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
69 doesn't have a \code{'PATH'} key.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
70 \end{datadesc}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
71
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
72 \begin{funcdesc}{execl}{path\, arg0\, arg1\, ...}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
73 This is equivalent to
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
74 \code{os.execv(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
75 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
76
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
77 \begin{funcdesc}{execle}{path\, arg0\, arg1\, ...\, env}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
78 This is equivalent to
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
79 \code{os.execve(\var{path}, (\var{arg0}, \var{arg1}, ...), \var{env})}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
80 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
81
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
82 \begin{funcdesc}{execlp}{path\, arg0\, arg1\, ...}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
83 This is equivalent to
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
84 \code{os.execvp(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
85 \end{funcdesc}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
86
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
87 \begin{funcdesc}{execvp}{path\, args}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
88 This is like \code{os.execv(\var{path}, \var{args})} but duplicates
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
89 the shell's actions in searching for an executable file in a list of
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
90 directories. The directory list is obtained from
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
91 \code{os.environ['PATH']}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
92 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
93
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
94 \begin{funcdesc}{execvpe}{path\, args\, env}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
95 This is a cross between \code{os.execve()} and \code{os.execvp()}.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
96 The directory list is obtained from \code{\var{env}['PATH']}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
97 \end{funcdesc}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
98
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
99 (The functions \code{os.execv()} and \code{execve()} are not
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
100 documented here, since they are implemented by the OS dependent
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
101 module. If the OS dependent module doesn't define either of these,
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
102 the functions that rely on it will raise an exception. They are
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
103 documented in the section on module \code{posix}, together with all
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
104 other functions that \code{os} imports from the OS dependent module.)