cpython-lru_cache-weakref: Doc/lib/libos.tex annotate

annotate Doc/lib/libos.tex @ 21467:4e35fa5d5708 legacy-trunk

Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.

author	Fred Drake <fdrake@acm.org>
date	Tue, 18 Dec 2001 16:31:08 +0000
parents	643244f7f467
children	3815a959819c

rev	line source
8918 acfffe14628e New section header style. Fred Drake <fdrake@acm.org> parents: 8850 diff changeset	1 \section{\module{os} ---
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	2 Miscellaneous operating system interfaces}
10659 69fb81facb03 Small markup nits. Fred Drake <fdrake@acm.org> parents: 10346 diff changeset	3
8716 760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 8597 diff changeset	4 \declaremodule{standard}{os}
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	5 \modulesynopsis{Miscellaneous operating system interfaces.}
8716 760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 8597 diff changeset	6
1471 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 This module provides a more portable way of using operating system
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	9 dependent functionality than importing a operating system dependent
346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	10 built-in module like \refmodule{posix} or \module{nt}.
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	11
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	12 This module searches for an operating system dependent built-in module like
10977 0f2292f57a83 Added 'ce' to the list of "registered" values for os.name. Fred Drake <fdrake@acm.org> parents: 10957 diff changeset	13 \module{mac} or \refmodule{posix} and exports the same functions and data
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	14 as found there. The design of all Python's built-in operating system dependent
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	15 modules is such that as long as the same functionality is available,
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18080 diff changeset	16 it uses the same interface; for example, the function
10659 69fb81facb03 Small markup nits. Fred Drake <fdrake@acm.org> parents: 10346 diff changeset	17 \code{os.stat(\var{path})} returns stat information about \var{path} in
69fb81facb03 Small markup nits. Fred Drake <fdrake@acm.org> parents: 10346 diff changeset	18 the same format (which happens to have originated with the
69fb81facb03 Small markup nits. Fred Drake <fdrake@acm.org> parents: 10346 diff changeset	19 \POSIX{} interface).
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	20
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	21 Extensions peculiar to a particular operating system are also
346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	22 available through the \module{os} module, but using them is of course a
346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	23 threat to portability!
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	24
7626 5aa7037a1e3f Logical markup. small nits. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	25 Note that after the first time \module{os} is imported, there is
5aa7037a1e3f Logical markup. small nits. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	26 \emph{no} performance penalty in using functions from \module{os}
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	27 instead of directly from the operating system dependent built-in module,
346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	28 so there should be \emph{no} reason not to use \module{os}!
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	29
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	30
11088 4463dd7bb3e8 Per Frank Stajano's suggestion, state explicitly that the functions Fred Drake <fdrake@acm.org> parents: 11015 diff changeset	31 % Frank Stajano <fstajano@uk.research.att.com> complained that it
4463dd7bb3e8 Per Frank Stajano's suggestion, state explicitly that the functions Fred Drake <fdrake@acm.org> parents: 11015 diff changeset	32 % wasn't clear that the entries described in the subsections were all
4463dd7bb3e8 Per Frank Stajano's suggestion, state explicitly that the functions Fred Drake <fdrake@acm.org> parents: 11015 diff changeset	33 % available at the module level (most uses of subsections are
4463dd7bb3e8 Per Frank Stajano's suggestion, state explicitly that the functions Fred Drake <fdrake@acm.org> parents: 11015 diff changeset	34 % different); I think this is only a problem for the HTML version,
4463dd7bb3e8 Per Frank Stajano's suggestion, state explicitly that the functions Fred Drake <fdrake@acm.org> parents: 11015 diff changeset	35 % where the relationship may not be as clear.
4463dd7bb3e8 Per Frank Stajano's suggestion, state explicitly that the functions Fred Drake <fdrake@acm.org> parents: 11015 diff changeset	36 %
4463dd7bb3e8 Per Frank Stajano's suggestion, state explicitly that the functions Fred Drake <fdrake@acm.org> parents: 11015 diff changeset	37 \ifhtml
4463dd7bb3e8 Per Frank Stajano's suggestion, state explicitly that the functions Fred Drake <fdrake@acm.org> parents: 11015 diff changeset	38 The \module{os} module contains many functions and data values.
4463dd7bb3e8 Per Frank Stajano's suggestion, state explicitly that the functions Fred Drake <fdrake@acm.org> parents: 11015 diff changeset	39 The items below and in the following sub-sections are all available
4463dd7bb3e8 Per Frank Stajano's suggestion, state explicitly that the functions Fred Drake <fdrake@acm.org> parents: 11015 diff changeset	40 directly from the \module{os} module.
4463dd7bb3e8 Per Frank Stajano's suggestion, state explicitly that the functions Fred Drake <fdrake@acm.org> parents: 11015 diff changeset	41 \fi
4463dd7bb3e8 Per Frank Stajano's suggestion, state explicitly that the functions Fred Drake <fdrake@acm.org> parents: 11015 diff changeset	42
4463dd7bb3e8 Per Frank Stajano's suggestion, state explicitly that the functions Fred Drake <fdrake@acm.org> parents: 11015 diff changeset	43
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	44 \begin{excdesc}{error}
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18080 diff changeset	45 This exception is raised when a function returns a system-related
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18080 diff changeset	46 error (not for illegal argument types or other incidental errors).
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18080 diff changeset	47 This is also known as the built-in exception \exception{OSError}. The
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	48 accompanying value is a pair containing the numeric error code from
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	49 \cdata{errno} and the corresponding string, as would be printed by the
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	50 C function \cfunction{perror()}. See the module
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	51 \refmodule{errno}\refbimodindex{errno}, which contains names for the
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	52 error codes defined by the underlying operating system.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	53
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	54 When exceptions are classes, this exception carries two attributes,
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	55 \member{errno} and \member{strerror}. The first holds the value of
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	56 the C \cdata{errno} variable, and the latter holds the corresponding
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	57 error message from \cfunction{strerror()}. For exceptions that
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18080 diff changeset	58 involve a file system path (such as \function{chdir()} or
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	59 \function{unlink()}), the exception instance will contain a third
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	60 attribute, \member{filename}, which is the file name passed to the
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	61 function.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	62 \end{excdesc}
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2527 diff changeset	63
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	64 \begin{datadesc}{name}
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	65 The name of the operating system dependent module imported. The
21108 12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	66 following names have currently been registered: \code{'posix'},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	67 \code{'nt'}, \code{'dos'}, \code{'mac'}, \code{'os2'}, \code{'ce'},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	68 \code{'java'}, \code{'riscos'}.
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	69 \end{datadesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	70
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	71 \begin{datadesc}{path}
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	72 The corresponding operating system dependent standard module for pathname
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18080 diff changeset	73 operations, such as \module{posixpath} or \module{macpath}. Thus,
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18080 diff changeset	74 given the proper imports, \code{os.path.split(\var{file})} is
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18080 diff changeset	75 equivalent to but more portable than
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18080 diff changeset	76 \code{posixpath.split(\var{file})}. Note that this is also an
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18080 diff changeset	77 importable module: it may be imported directly as
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	78 \refmodule{os.path}.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	79 \end{datadesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	80
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	81
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	82
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	83 \subsection{Process Parameters \label{os-procinfo}}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	84
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	85 These functions and data items provide information and operate on the
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	86 current process and user.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	87
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	88 \begin{datadesc}{environ}
10789 767351f4944a Minor nits, partly in response to comments from Jonathan Black Fred Drake <fdrake@acm.org> parents: 10659 diff changeset	89 A mapping object representing the string environment. For example,
767351f4944a Minor nits, partly in response to comments from Jonathan Black Fred Drake <fdrake@acm.org> parents: 10659 diff changeset	90 \code{environ['HOME']} is the pathname of your home directory (on some
767351f4944a Minor nits, partly in response to comments from Jonathan Black Fred Drake <fdrake@acm.org> parents: 10659 diff changeset	91 platforms), and is equivalent to \code{getenv("HOME")} in C.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	92
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	93 If the platform supports the \function{putenv()} function, this
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	94 mapping may be used to modify the environment as well as query the
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	95 environment. \function{putenv()} will be called automatically when
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	96 the mapping is modified.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	97
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	98 If \function{putenv()} is not provided, this mapping may be passed to
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	99 the appropriate process-creation functions to cause child processes to
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	100 use a modified environment.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	101 \end{datadesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	102
11122 306b49d68233 Move chdir() and getcwd() descriptions to "Files and Directories" with Fred Drake <fdrake@acm.org> parents: 11096 diff changeset	103 \begin{funcdescni}{chdir}{path}
306b49d68233 Move chdir() and getcwd() descriptions to "Files and Directories" with Fred Drake <fdrake@acm.org> parents: 11096 diff changeset	104 \funclineni{getcwd}{}
306b49d68233 Move chdir() and getcwd() descriptions to "Files and Directories" with Fred Drake <fdrake@acm.org> parents: 11096 diff changeset	105 These functions are described in ``Files and Directories'' (section
306b49d68233 Move chdir() and getcwd() descriptions to "Files and Directories" with Fred Drake <fdrake@acm.org> parents: 11096 diff changeset	106 \ref{os-file-dir}).
306b49d68233 Move chdir() and getcwd() descriptions to "Files and Directories" with Fred Drake <fdrake@acm.org> parents: 11096 diff changeset	107 \end{funcdescni}
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	108
11534 68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	109 \begin{funcdesc}{ctermid}{}
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	110 Return the filename corresponding to the controlling terminal of the
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	111 process.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	112 Availability: \UNIX.
11534 68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	113 \end{funcdesc}
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	114
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	115 \begin{funcdesc}{getegid}{}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	116 Return the current process' effective group id.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	117 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	118 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	119
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	120 \begin{funcdesc}{geteuid}{}
10878 b9ef424165d6 "proces" --> "process"; reported by Gerry Wiener <gerry@ucar.edu>. Fred Drake <fdrake@acm.org> parents: 10789 diff changeset	121 \index{user!effective id}
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	122 Return the current process' effective user id.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	123 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	124 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	125
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	126 \begin{funcdesc}{getgid}{}
10878 b9ef424165d6 "proces" --> "process"; reported by Gerry Wiener <gerry@ucar.edu>. Fred Drake <fdrake@acm.org> parents: 10789 diff changeset	127 \index{process!group}
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	128 Return the current process' group id.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	129 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	130 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	131
11578 4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	132 \begin{funcdesc}{getgroups}{}
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	133 Return list of supplemental group ids associated with the current
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	134 process.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	135 Availability: \UNIX.
11578 4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	136 \end{funcdesc}
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	137
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	138 \begin{funcdesc}{getlogin}{}
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	139 Return the actual login name for the current process, even if there
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	140 are multiple login names which map to the same user id.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	141 Availability: \UNIX.
11578 4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	142 \end{funcdesc}
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	143
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	144 \begin{funcdesc}{getpgrp}{}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	145 \index{process!group}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	146 Return the current process group id.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	147 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	148 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	149
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	150 \begin{funcdesc}{getpid}{}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	151 \index{process!id}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	152 Return the current process id.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	153 Availability: \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	154 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	155
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	156 \begin{funcdesc}{getppid}{}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	157 \index{process!id of parent}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	158 Return the parent's process id.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	159 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	160 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	161
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	162 \begin{funcdesc}{getuid}{}
10878 b9ef424165d6 "proces" --> "process"; reported by Gerry Wiener <gerry@ucar.edu>. Fred Drake <fdrake@acm.org> parents: 10789 diff changeset	163 \index{user!id}
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	164 Return the current process' user id.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	165 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	166 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	167
18012 582845e14e5c Document os.getenv(). Fred Drake <fdrake@acm.org> parents: 17998 diff changeset	168 \begin{funcdesc}{getenv}{varname\optional{, value}}
582845e14e5c Document os.getenv(). Fred Drake <fdrake@acm.org> parents: 17998 diff changeset	169 Return the value of the environment variable \var{varname} if it
582845e14e5c Document os.getenv(). Fred Drake <fdrake@acm.org> parents: 17998 diff changeset	170 exists, or \var{value} if it doesn't. \var{value} defaults to
582845e14e5c Document os.getenv(). Fred Drake <fdrake@acm.org> parents: 17998 diff changeset	171 \code{None}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	172 Availability: most flavors of \UNIX, Windows.
18012 582845e14e5c Document os.getenv(). Fred Drake <fdrake@acm.org> parents: 17998 diff changeset	173 \end{funcdesc}
582845e14e5c Document os.getenv(). Fred Drake <fdrake@acm.org> parents: 17998 diff changeset	174
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	175 \begin{funcdesc}{putenv}{varname, value}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	176 \index{environment variables!setting}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	177 Set the environment variable named \var{varname} to the string
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	178 \var{value}. Such changes to the environment affect subprocesses
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	179 started with \function{os.system()}, \function{popen()} or
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	180 \function{fork()} and \function{execv()}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	181 Availability: most flavors of \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	182
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	183 When \function{putenv()} is
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	184 supported, assignments to items in \code{os.environ} are automatically
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	185 translated into corresponding calls to \function{putenv()}; however,
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	186 calls to \function{putenv()} don't update \code{os.environ}, so it is
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	187 actually preferable to assign to items of \code{os.environ}.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	188 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	189
13582 084a758051e0 From Sam Rushing's Medusa, via SF patch #100858: add & document Andrew M. Kuchling <amk@amk.ca> parents: 13222 diff changeset	190 \begin{funcdesc}{setegid}{egid}
084a758051e0 From Sam Rushing's Medusa, via SF patch #100858: add & document Andrew M. Kuchling <amk@amk.ca> parents: 13222 diff changeset	191 Set the current process's effective group id.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	192 Availability: \UNIX.
13582 084a758051e0 From Sam Rushing's Medusa, via SF patch #100858: add & document Andrew M. Kuchling <amk@amk.ca> parents: 13222 diff changeset	193 \end{funcdesc}
084a758051e0 From Sam Rushing's Medusa, via SF patch #100858: add & document Andrew M. Kuchling <amk@amk.ca> parents: 13222 diff changeset	194
084a758051e0 From Sam Rushing's Medusa, via SF patch #100858: add & document Andrew M. Kuchling <amk@amk.ca> parents: 13222 diff changeset	195 \begin{funcdesc}{seteuid}{euid}
084a758051e0 From Sam Rushing's Medusa, via SF patch #100858: add & document Andrew M. Kuchling <amk@amk.ca> parents: 13222 diff changeset	196 Set the current process's effective user id.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	197 Availability: \UNIX.
13582 084a758051e0 From Sam Rushing's Medusa, via SF patch #100858: add & document Andrew M. Kuchling <amk@amk.ca> parents: 13222 diff changeset	198 \end{funcdesc}
084a758051e0 From Sam Rushing's Medusa, via SF patch #100858: add & document Andrew M. Kuchling <amk@amk.ca> parents: 13222 diff changeset	199
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	200 \begin{funcdesc}{setgid}{gid}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	201 Set the current process' group id.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	202 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	203 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	204
20508 8e0c31849c64 Expose setgroups. Fixes feature request #468116. Martin v. Löwis <martin@v.loewis.de> parents: 20337 diff changeset	205 \begin{funcdesc}{setgroups}{groups}
20511 c13a473ce1b7 Elaborate on types and meaning of the setgroups arguments. Martin v. Löwis <martin@v.loewis.de> parents: 20508 diff changeset	206 Set the list of supplemental group ids associated with the current
c13a473ce1b7 Elaborate on types and meaning of the setgroups arguments. Martin v. Löwis <martin@v.loewis.de> parents: 20508 diff changeset	207 process to \var{groups}. \var{groups} must be a sequence, and each
c13a473ce1b7 Elaborate on types and meaning of the setgroups arguments. Martin v. Löwis <martin@v.loewis.de> parents: 20508 diff changeset	208 element must be an integer identifying a group. This operation is
c13a473ce1b7 Elaborate on types and meaning of the setgroups arguments. Martin v. Löwis <martin@v.loewis.de> parents: 20508 diff changeset	209 typical available only to the superuser.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	210 Availability: \UNIX.
20508 8e0c31849c64 Expose setgroups. Fixes feature request #468116. Martin v. Löwis <martin@v.loewis.de> parents: 20337 diff changeset	211 \versionadded{2.2}
8e0c31849c64 Expose setgroups. Fixes feature request #468116. Martin v. Löwis <martin@v.loewis.de> parents: 20337 diff changeset	212 \end{funcdesc}
8e0c31849c64 Expose setgroups. Fixes feature request #468116. Martin v. Löwis <martin@v.loewis.de> parents: 20337 diff changeset	213
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	214 \begin{funcdesc}{setpgrp}{}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	215 Calls the system call \cfunction{setpgrp()} or \cfunction{setpgrp(0,
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	216 0)} depending on which version is implemented (if any). See the
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	217 \UNIX{} manual for the semantics.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	218 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	219 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	220
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	221 \begin{funcdesc}{setpgid}{pid, pgrp}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	222 Calls the system call \cfunction{setpgid()}. See the \UNIX{} manual
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	223 for the semantics.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	224 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	225 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	226
13582 084a758051e0 From Sam Rushing's Medusa, via SF patch #100858: add & document Andrew M. Kuchling <amk@amk.ca> parents: 13222 diff changeset	227 \begin{funcdesc}{setreuid}{ruid, euid}
084a758051e0 From Sam Rushing's Medusa, via SF patch #100858: add & document Andrew M. Kuchling <amk@amk.ca> parents: 13222 diff changeset	228 Set the current process's real and effective user ids.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	229 Availability: \UNIX.
13582 084a758051e0 From Sam Rushing's Medusa, via SF patch #100858: add & document Andrew M. Kuchling <amk@amk.ca> parents: 13222 diff changeset	230 \end{funcdesc}
084a758051e0 From Sam Rushing's Medusa, via SF patch #100858: add & document Andrew M. Kuchling <amk@amk.ca> parents: 13222 diff changeset	231
084a758051e0 From Sam Rushing's Medusa, via SF patch #100858: add & document Andrew M. Kuchling <amk@amk.ca> parents: 13222 diff changeset	232 \begin{funcdesc}{setregid}{rgid, egid}
084a758051e0 From Sam Rushing's Medusa, via SF patch #100858: add & document Andrew M. Kuchling <amk@amk.ca> parents: 13222 diff changeset	233 Set the current process's real and effective group ids.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	234 Availability: \UNIX.
13582 084a758051e0 From Sam Rushing's Medusa, via SF patch #100858: add & document Andrew M. Kuchling <amk@amk.ca> parents: 13222 diff changeset	235 \end{funcdesc}
084a758051e0 From Sam Rushing's Medusa, via SF patch #100858: add & document Andrew M. Kuchling <amk@amk.ca> parents: 13222 diff changeset	236
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	237 \begin{funcdesc}{setsid}{}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	238 Calls the system call \cfunction{setsid()}. See the \UNIX{} manual
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	239 for the semantics.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	240 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	241 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	242
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	243 \begin{funcdesc}{setuid}{uid}
10878 b9ef424165d6 "proces" --> "process"; reported by Gerry Wiener <gerry@ucar.edu>. Fred Drake <fdrake@acm.org> parents: 10789 diff changeset	244 \index{user!id, setting}
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	245 Set the current process' user id.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	246 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	247 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	248
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	249 % placed in this section since it relates to errno.... a little weak ;-(
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	250 \begin{funcdesc}{strerror}{code}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	251 Return the error message corresponding to the error code in
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	252 \var{code}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	253 Availability: \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	254 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	255
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	256 \begin{funcdesc}{umask}{mask}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	257 Set the current numeric umask and returns the previous umask.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	258 Availability: \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	259 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	260
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	261 \begin{funcdesc}{uname}{}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	262 Return a 5-tuple containing information identifying the current
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	263 operating system. The tuple contains 5 strings:
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	264 \code{(\var{sysname}, \var{nodename}, \var{release}, \var{version},
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	265 \var{machine})}. Some systems truncate the nodename to 8
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	266 characters or to the leading component; a better way to get the
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	267 hostname is \function{socket.gethostname()}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	268 \withsubitem{(in module socket)}{\ttindex{gethostname()}}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	269 or even
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	270 \withsubitem{(in module socket)}{\ttindex{gethostbyaddr()}}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	271 \code{socket.gethostbyaddr(socket.gethostname())}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	272 Availability: recent flavors of \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	273 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	274
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	275
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	276
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	277 \subsection{File Object Creation \label{os-newstreams}}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	278
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	279 These functions create new file objects.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	280
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	281
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	282 \begin{funcdesc}{fdopen}{fd\optional{, mode\optional{, bufsize}}}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	283 Return an open file object connected to the file descriptor \var{fd}.
11179 d6ab72cb1625 Add index entry "I/O control, buffering" for fdopen(). Fred Drake <fdrake@acm.org> parents: 11122 diff changeset	284 \index{I/O control!buffering}
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	285 The \var{mode} and \var{bufsize} arguments have the same meaning as
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	286 the corresponding arguments to the built-in \function{open()}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	287 function.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	288 Availability: Macintosh, \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	289 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	290
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	291 \begin{funcdesc}{popen}{command\optional{, mode\optional{, bufsize}}}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	292 Open a pipe to or from \var{command}. The return value is an open
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	293 file object connected to the pipe, which can be read or written
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	294 depending on whether \var{mode} is \code{'r'} (default) or \code{'w'}.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	295 The \var{bufsize} argument has the same meaning as the corresponding
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	296 argument to the built-in \function{open()} function. The exit status of
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	297 the command (encoded in the format specified for \function{wait()}) is
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	298 available as the return value of the \method{close()} method of the file
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	299 object, except that when the exit status is zero (termination without
14997 0c5b02cc5489 Remove old note that os.popen() on Windows is unreliable; this is no Fred Drake <fdrake@acm.org> parents: 14922 diff changeset	300 errors), \code{None} is returned.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	301 Availability: \UNIX, Windows.
15008 aa052a52ef87 Added \versionchanged comment to os.popen() noting that it was unreliable Fred Drake <fdrake@acm.org> parents: 14997 diff changeset	302
aa052a52ef87 Added \versionchanged comment to os.popen() noting that it was unreliable Fred Drake <fdrake@acm.org> parents: 14997 diff changeset	303 \versionchanged[This function worked unreliably under Windows in
aa052a52ef87 Added \versionchanged comment to os.popen() noting that it was unreliable Fred Drake <fdrake@acm.org> parents: 14997 diff changeset	304 earlier versions of Python. This was due to the use of the
aa052a52ef87 Added \versionchanged comment to os.popen() noting that it was unreliable Fred Drake <fdrake@acm.org> parents: 14997 diff changeset	305 \cfunction{_popen()} function from the libraries provided with
aa052a52ef87 Added \versionchanged comment to os.popen() noting that it was unreliable Fred Drake <fdrake@acm.org> parents: 14997 diff changeset	306 Windows. Newer versions of Python do not use the broken
aa052a52ef87 Added \versionchanged comment to os.popen() noting that it was unreliable Fred Drake <fdrake@acm.org> parents: 14997 diff changeset	307 implementation from the Windows libraries]{2.0}
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	308 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	309
11534 68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	310 \begin{funcdesc}{tmpfile}{}
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	311 Return a new file object opened in update mode (\samp{w+}). The file
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	312 has no directory entries associated with it and will be automatically
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	313 deleted once there are no file descriptors for the file.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	314 Availability: \UNIX, Windows.
11534 68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	315 \end{funcdesc}
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	316
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	317
14915 ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	318 For each of these \function{popen()} variants, if \var{bufsize} is
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	319 specified, it specifies the buffer size for the I/O pipes.
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	320 \var{mode}, if provided, should be the string \code{'b'} or
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	321 \code{'t'}; on Windows this is needed to determine whether the file
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	322 objects should be opened in binary or text mode. The default value
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	323 for \var{mode} is \code{'t'}.
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	324
19873 a19eea41668f Document clearly that the only way to retrieve the return code from the Fred Drake <fdrake@acm.org> parents: 19325 diff changeset	325 These methods do not make it possible to retrieve the return code from
a19eea41668f Document clearly that the only way to retrieve the return code from the Fred Drake <fdrake@acm.org> parents: 19325 diff changeset	326 the child processes. The only way to control the input and output
a19eea41668f Document clearly that the only way to retrieve the return code from the Fred Drake <fdrake@acm.org> parents: 19325 diff changeset	327 streams and also retrieve the return codes is to use the
a19eea41668f Document clearly that the only way to retrieve the return code from the Fred Drake <fdrake@acm.org> parents: 19325 diff changeset	328 \class{Popen3} and \class{Popen4} classes from the \refmodule{popen2}
a19eea41668f Document clearly that the only way to retrieve the return code from the Fred Drake <fdrake@acm.org> parents: 19325 diff changeset	329 module; these are only available on \UNIX.
a19eea41668f Document clearly that the only way to retrieve the return code from the Fred Drake <fdrake@acm.org> parents: 19325 diff changeset	330
18074 410bbf5d98f9 Fixed parameter order for os.popen2(), os.popen3(), and os.popen(4). Added Fred Drake <fdrake@acm.org> parents: 18029 diff changeset	331 \begin{funcdesc}{popen2}{cmd\optional{, mode\optional{, bufsize}}}
14915 ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	332 Executes \var{cmd} as a sub-process. Returns the file objects
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	333 \code{(\var{child_stdin}, \var{child_stdout})}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	334 Availability: \UNIX, Windows.
14915 ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	335 \versionadded{2.0}
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	336 \end{funcdesc}
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	337
18074 410bbf5d98f9 Fixed parameter order for os.popen2(), os.popen3(), and os.popen(4). Added Fred Drake <fdrake@acm.org> parents: 18029 diff changeset	338 \begin{funcdesc}{popen3}{cmd\optional{, mode\optional{, bufsize}}}
14915 ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	339 Executes \var{cmd} as a sub-process. Returns the file objects
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	340 \code{(\var{child_stdin}, \var{child_stdout}, \var{child_stderr})}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	341 Availability: \UNIX, Windows.
14915 ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	342 \versionadded{2.0}
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	343 \end{funcdesc}
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	344
18074 410bbf5d98f9 Fixed parameter order for os.popen2(), os.popen3(), and os.popen(4). Added Fred Drake <fdrake@acm.org> parents: 18029 diff changeset	345 \begin{funcdesc}{popen4}{cmd\optional{, mode\optional{, bufsize}}}
14915 ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	346 Executes \var{cmd} as a sub-process. Returns the file objects
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	347 \code{(\var{child_stdin}, \var{child_stdout_and_stderr})}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	348 Availability: \UNIX, Windows.
14915 ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	349 \versionadded{2.0}
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	350 \end{funcdesc}
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	351
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	352 This functionality is also available in the \refmodule{popen2} module
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	353 using functions of the same names, but the return values of those
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	354 functions have a different order.
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	355
ea2ba910e5f0 Updated documentation relating to the various flavors of popen[234]() Fred Drake <fdrake@acm.org> parents: 14789 diff changeset	356
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	357 \subsection{File Descriptor Operations \label{os-fd-ops}}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	358
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	359 These functions operate on I/O streams referred to
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	360 using file descriptors.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	361
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	362
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	363 \begin{funcdesc}{close}{fd}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	364 Close file descriptor \var{fd}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	365 Availability: Macintosh, \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	366
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	367 Note: this function is intended for low-level I/O and must be applied
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	368 to a file descriptor as returned by \function{open()} or
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	369 \function{pipe()}. To close a ``file object'' returned by the
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	370 built-in function \function{open()} or by \function{popen()} or
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	371 \function{fdopen()}, use its \method{close()} method.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	372 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	373
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	374 \begin{funcdesc}{dup}{fd}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	375 Return a duplicate of file descriptor \var{fd}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	376 Availability: Macintosh, \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	377 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	378
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	379 \begin{funcdesc}{dup2}{fd, fd2}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	380 Duplicate file descriptor \var{fd} to \var{fd2}, closing the latter
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	381 first if necessary.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	382 Availability: \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	383 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	384
11578 4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	385 \begin{funcdesc}{fpathconf}{fd, name}
13625 fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope Thomas Wouters <thomas@python.org> parents: 13582 diff changeset	386 Return system configuration information relevant to an open file.
11578 4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	387 \var{name} specifies the configuration value to retrieve; it may be a
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	388 string which is the name of a defined system value; these names are
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	389 specified in a number of standards (\POSIX.1, \UNIX 95, \UNIX 98, and
11578 4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	390 others). Some platforms define additional names as well. The names
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	391 known to the host operating system are given in the
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	392 \code{pathconf_names} dictionary. For configuration variables not
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	393 included in that mapping, passing an integer for \var{name} is also
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	394 accepted.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	395 Availability: \UNIX.
11578 4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	396
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	397 If \var{name} is a string and is not known, \exception{ValueError} is
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	398 raised. If a specific value for \var{name} is not supported by the
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	399 host system, even if it is included in \code{pathconf_names}, an
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	400 \exception{OSError} is raised with \constant{errno.EINVAL} for the
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	401 error number.
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	402 \end{funcdesc}
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	403
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	404 \begin{funcdesc}{fstat}{fd}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	405 Return status for file descriptor \var{fd}, like \function{stat()}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	406 Availability: \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	407 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	408
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	409 \begin{funcdesc}{fstatvfs}{fd}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	410 Return information about the filesystem containing the file associated
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	411 with file descriptor \var{fd}, like \function{statvfs()}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	412 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	413 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	414
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	415 \begin{funcdesc}{ftruncate}{fd, length}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	416 Truncate the file corresponding to file descriptor \var{fd},
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	417 so that it is at most \var{length} bytes in size.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	418 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	419 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	420
13649 f80571bb2913 added doc for isatty() Skip Montanaro <skip@pobox.com> parents: 13625 diff changeset	421 \begin{funcdesc}{isatty}{fd}
f80571bb2913 added doc for isatty() Skip Montanaro <skip@pobox.com> parents: 13625 diff changeset	422 Return \code{1} if the file descriptor \var{fd} is open and connected to a
f80571bb2913 added doc for isatty() Skip Montanaro <skip@pobox.com> parents: 13625 diff changeset	423 tty(-like) device, else \code{0}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	424 Availability: \UNIX.
13649 f80571bb2913 added doc for isatty() Skip Montanaro <skip@pobox.com> parents: 13625 diff changeset	425 \end{funcdesc}
f80571bb2913 added doc for isatty() Skip Montanaro <skip@pobox.com> parents: 13625 diff changeset	426
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	427 \begin{funcdesc}{lseek}{fd, pos, how}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	428 Set the current position of file descriptor \var{fd} to position
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	429 \var{pos}, modified by \var{how}: \code{0} to set the position
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	430 relative to the beginning of the file; \code{1} to set it relative to
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	431 the current position; \code{2} to set it relative to the end of the
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	432 file.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	433 Availability: Macintosh, \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	434 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	435
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	436 \begin{funcdesc}{open}{file, flags\optional{, mode}}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	437 Open the file \var{file} and set various flags according to
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	438 \var{flags} and possibly its mode according to \var{mode}.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	439 The default \var{mode} is \code{0777} (octal), and the current umask
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	440 value is first masked out. Return the file descriptor for the newly
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	441 opened file.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	442 Availability: Macintosh, \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	443
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	444 For a description of the flag and mode values, see the C run-time
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	445 documentation; flag constants (like \constant{O_RDONLY} and
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	446 \constant{O_WRONLY}) are defined in this module too (see below).
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	447
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	448 Note: this function is intended for low-level I/O. For normal usage,
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	449 use the built-in function \function{open()}, which returns a ``file
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	450 object'' with \method{read()} and \method{write()} methods (and many
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	451 more).
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	452 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	453
13067 a679bdb43fad Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 12550 diff changeset	454 \begin{funcdesc}{openpty}{}
a679bdb43fad Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 12550 diff changeset	455 Open a new pseudo-terminal pair. Return a pair of file descriptors
a679bdb43fad Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 12550 diff changeset	456 \code{(\var{master}, \var{slave})} for the pty and the tty,
a679bdb43fad Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 12550 diff changeset	457 respectively. For a (slightly) more portable approach, use the
a679bdb43fad Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 12550 diff changeset	458 \refmodule{pty}\refstmodindex{pty} module.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	459 Availability: Some flavors of \UNIX.
13067 a679bdb43fad Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 12550 diff changeset	460 \end{funcdesc}
a679bdb43fad Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 12550 diff changeset	461
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	462 \begin{funcdesc}{pipe}{}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	463 Create a pipe. Return a pair of file descriptors \code{(\var{r},
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	464 \var{w})} usable for reading and writing, respectively.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	465 Availability: \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	466 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	467
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	468 \begin{funcdesc}{read}{fd, n}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	469 Read at most \var{n} bytes from file descriptor \var{fd}.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	470 Return a string containing the bytes read.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	471 Availability: Macintosh, \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	472
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	473 Note: this function is intended for low-level I/O and must be applied
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	474 to a file descriptor as returned by \function{open()} or
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	475 \function{pipe()}. To read a ``file object'' returned by the
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	476 built-in function \function{open()} or by \function{popen()} or
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	477 \function{fdopen()}, or \code{sys.stdin}, use its
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	478 \method{read()} or \method{readline()} methods.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	479 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	480
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	481 \begin{funcdesc}{tcgetpgrp}{fd}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	482 Return the process group associated with the terminal given by
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	483 \var{fd} (an open file descriptor as returned by \function{open()}).
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	484 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	485 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	486
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	487 \begin{funcdesc}{tcsetpgrp}{fd, pg}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	488 Set the process group associated with the terminal given by
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	489 \var{fd} (an open file descriptor as returned by \function{open()})
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	490 to \var{pg}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	491 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	492 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	493
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	494 \begin{funcdesc}{ttyname}{fd}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	495 Return a string which specifies the terminal device associated with
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	496 file-descriptor \var{fd}. If \var{fd} is not associated with a terminal
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	497 device, an exception is raised.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	498 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	499 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	500
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	501 \begin{funcdesc}{write}{fd, str}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	502 Write the string \var{str} to file descriptor \var{fd}.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	503 Return the number of bytes actually written.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	504 Availability: Macintosh, \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	505
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	506 Note: this function is intended for low-level I/O and must be applied
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	507 to a file descriptor as returned by \function{open()} or
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	508 \function{pipe()}. To write a ``file object'' returned by the
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	509 built-in function \function{open()} or by \function{popen()} or
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	510 \function{fdopen()}, or \code{sys.stdout} or \code{sys.stderr}, use
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	511 its \method{write()} method.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	512 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	513
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	514
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	515 The following data items are available for use in constructing the
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	516 \var{flags} parameter to the \function{open()} function.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	517
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	518 \begin{datadesc}{O_RDONLY}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	519 \dataline{O_WRONLY}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	520 \dataline{O_RDWR}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	521 \dataline{O_NDELAY}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	522 \dataline{O_NONBLOCK}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	523 \dataline{O_APPEND}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	524 \dataline{O_DSYNC}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	525 \dataline{O_RSYNC}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	526 \dataline{O_SYNC}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	527 \dataline{O_NOCTTY}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	528 \dataline{O_CREAT}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	529 \dataline{O_EXCL}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	530 \dataline{O_TRUNC}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	531 Options for the \var{flag} argument to the \function{open()} function.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	532 These can be bit-wise OR'd together.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	533 Availability: Macintosh, \UNIX, Windows.
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	534 \end{datadesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	535
13927 266fb6302f31 O_BINARY: Documented this constant; omission noted by David Ascher. Fred Drake <fdrake@acm.org> parents: 13649 diff changeset	536 \begin{datadesc}{O_BINARY}
266fb6302f31 O_BINARY: Documented this constant; omission noted by David Ascher. Fred Drake <fdrake@acm.org> parents: 13649 diff changeset	537 Option for the \var{flag} argument to the \function{open()} function.
266fb6302f31 O_BINARY: Documented this constant; omission noted by David Ascher. Fred Drake <fdrake@acm.org> parents: 13649 diff changeset	538 This can be bit-wise OR'd together with those listed above.
266fb6302f31 O_BINARY: Documented this constant; omission noted by David Ascher. Fred Drake <fdrake@acm.org> parents: 13649 diff changeset	539 Availability: Macintosh, Windows.
266fb6302f31 O_BINARY: Documented this constant; omission noted by David Ascher. Fred Drake <fdrake@acm.org> parents: 13649 diff changeset	540 % XXX need to check on the availability of this one.
266fb6302f31 O_BINARY: Documented this constant; omission noted by David Ascher. Fred Drake <fdrake@acm.org> parents: 13649 diff changeset	541 \end{datadesc}
266fb6302f31 O_BINARY: Documented this constant; omission noted by David Ascher. Fred Drake <fdrake@acm.org> parents: 13649 diff changeset	542
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	543
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	544 \subsection{Files and Directories \label{os-file-dir}}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	545
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	546 \begin{funcdesc}{access}{path, mode}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	547 Check read/write/execute permissions for this process or existence of
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	548 file \var{path}. \var{mode} should be \constant{F_OK} to test the
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	549 existence of \var{path}, or it can be the inclusive OR of one or more
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	550 of \constant{R_OK}, \constant{W_OK}, and \constant{X_OK} to test
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	551 permissions. Return \code{1} if access is allowed, \code{0} if not.
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	552 See the \UNIX{} man page \manpage{access}{2} for more information.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	553 Availability: \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	554 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	555
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	556 \begin{datadesc}{F_OK}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	557 Value to pass as the \var{mode} parameter of \function{access()} to
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	558 test the existence of \var{path}.
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	559 \end{datadesc}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	560
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	561 \begin{datadesc}{R_OK}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	562 Value to include in the \var{mode} parameter of \function{access()}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	563 to test the readability of \var{path}.
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	564 \end{datadesc}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	565
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	566 \begin{datadesc}{W_OK}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	567 Value to include in the \var{mode} parameter of \function{access()}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	568 to test the writability of \var{path}.
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	569 \end{datadesc}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	570
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	571 \begin{datadesc}{X_OK}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	572 Value to include in the \var{mode} parameter of \function{access()}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	573 to determine if \var{path} can be executed.
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	574 \end{datadesc}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	575
11122 306b49d68233 Move chdir() and getcwd() descriptions to "Files and Directories" with Fred Drake <fdrake@acm.org> parents: 11096 diff changeset	576 \begin{funcdesc}{chdir}{path}
306b49d68233 Move chdir() and getcwd() descriptions to "Files and Directories" with Fred Drake <fdrake@acm.org> parents: 11096 diff changeset	577 \index{directory!changing}
306b49d68233 Move chdir() and getcwd() descriptions to "Files and Directories" with Fred Drake <fdrake@acm.org> parents: 11096 diff changeset	578 Change the current working directory to \var{path}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	579 Availability: Macintosh, \UNIX, Windows.
11122 306b49d68233 Move chdir() and getcwd() descriptions to "Files and Directories" with Fred Drake <fdrake@acm.org> parents: 11096 diff changeset	580 \end{funcdesc}
306b49d68233 Move chdir() and getcwd() descriptions to "Files and Directories" with Fred Drake <fdrake@acm.org> parents: 11096 diff changeset	581
306b49d68233 Move chdir() and getcwd() descriptions to "Files and Directories" with Fred Drake <fdrake@acm.org> parents: 11096 diff changeset	582 \begin{funcdesc}{getcwd}{}
306b49d68233 Move chdir() and getcwd() descriptions to "Files and Directories" with Fred Drake <fdrake@acm.org> parents: 11096 diff changeset	583 Return a string representing the current working directory.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	584 Availability: Macintosh, \UNIX, Windows.
11122 306b49d68233 Move chdir() and getcwd() descriptions to "Files and Directories" with Fred Drake <fdrake@acm.org> parents: 11096 diff changeset	585 \end{funcdesc}
306b49d68233 Move chdir() and getcwd() descriptions to "Files and Directories" with Fred Drake <fdrake@acm.org> parents: 11096 diff changeset	586
20264 d092abcf9c4b Add chroot call. Implements feature #459267. Martin v. Löwis <martin@v.loewis.de> parents: 20145 diff changeset	587 \begin{funcdesc}{chroot}{path}
d092abcf9c4b Add chroot call. Implements feature #459267. Martin v. Löwis <martin@v.loewis.de> parents: 20145 diff changeset	588 Change the root directory of the current process to \var{path}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	589 Availability: \UNIX.
20264 d092abcf9c4b Add chroot call. Implements feature #459267. Martin v. Löwis <martin@v.loewis.de> parents: 20145 diff changeset	590 \versionadded{2.2}
d092abcf9c4b Add chroot call. Implements feature #459267. Martin v. Löwis <martin@v.loewis.de> parents: 20145 diff changeset	591 \end{funcdesc}
d092abcf9c4b Add chroot call. Implements feature #459267. Martin v. Löwis <martin@v.loewis.de> parents: 20145 diff changeset	592
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	593 \begin{funcdesc}{chmod}{path, mode}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	594 Change the mode of \var{path} to the numeric \var{mode}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	595 Availability: \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	596 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	597
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	598 \begin{funcdesc}{chown}{path, uid, gid}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	599 Change the owner and group id of \var{path} to the numeric \var{uid}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	600 and \var{gid}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	601 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	602 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	603
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	604 \begin{funcdesc}{link}{src, dst}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	605 Create a hard link pointing to \var{src} named \var{dst}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	606 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	607 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	608
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	609 \begin{funcdesc}{listdir}{path}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	610 Return a list containing the names of the entries in the directory.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	611 The list is in arbitrary order. It does not include the special
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	612 entries \code{'.'} and \code{'..'} even if they are present in the
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	613 directory.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	614 Availability: Macintosh, \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	615 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	616
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	617 \begin{funcdesc}{lstat}{path}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	618 Like \function{stat()}, but do not follow symbolic links.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	619 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	620 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	621
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	622 \begin{funcdesc}{mkfifo}{path\optional{, mode}}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	623 Create a FIFO (a named pipe) named \var{path} with numeric mode
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	624 \var{mode}. The default \var{mode} is \code{0666} (octal). The current
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	625 umask value is first masked out from the mode.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	626 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	627
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	628 FIFOs are pipes that can be accessed like regular files. FIFOs exist
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	629 until they are deleted (for example with \function{os.unlink()}).
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	630 Generally, FIFOs are used as rendezvous between ``client'' and
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	631 ``server'' type processes: the server opens the FIFO for reading, and
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	632 the client opens it for writing. Note that \function{mkfifo()}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	633 doesn't open the FIFO --- it just creates the rendezvous point.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	634 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	635
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	636 \begin{funcdesc}{mkdir}{path\optional{, mode}}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	637 Create a directory named \var{path} with numeric mode \var{mode}.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	638 The default \var{mode} is \code{0777} (octal). On some systems,
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	639 \var{mode} is ignored. Where it is used, the current umask value is
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	640 first masked out.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	641 Availability: Macintosh, \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	642 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	643
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	644 \begin{funcdesc}{makedirs}{path\optional{, mode}}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	645 \index{directory!creating}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	646 Recursive directory creation function. Like \function{mkdir()},
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	647 but makes all intermediate-level directories needed to contain the
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	648 leaf directory. Throws an \exception{error} exception if the leaf
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	649 directory already exists or cannot be created. The default \var{mode}
20145 c6fc87810551 Added note about non-support of UNC paths on Windows. Fred Drake <fdrake@acm.org> parents: 19873 diff changeset	650 is \code{0777} (octal). This function does not properly handle UNC
c6fc87810551 Added note about non-support of UNC paths on Windows. Fred Drake <fdrake@acm.org> parents: 19873 diff changeset	651 paths (only relevant on Windows systems).
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	652 \versionadded{1.5.2}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	653 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	654
11578 4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	655 \begin{funcdesc}{pathconf}{path, name}
13625 fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope Thomas Wouters <thomas@python.org> parents: 13582 diff changeset	656 Return system configuration information relevant to a named file.
11578 4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	657 \var{name} specifies the configuration value to retrieve; it may be a
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	658 string which is the name of a defined system value; these names are
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	659 specified in a number of standards (\POSIX.1, \UNIX 95, \UNIX 98, and
11578 4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	660 others). Some platforms define additional names as well. The names
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	661 known to the host operating system are given in the
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	662 \code{pathconf_names} dictionary. For configuration variables not
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	663 included in that mapping, passing an integer for \var{name} is also
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	664 accepted.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	665 Availability: \UNIX.
11578 4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	666
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	667 If \var{name} is a string and is not known, \exception{ValueError} is
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	668 raised. If a specific value for \var{name} is not supported by the
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	669 host system, even if it is included in \code{pathconf_names}, an
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	670 \exception{OSError} is raised with \constant{errno.EINVAL} for the
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	671 error number.
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	672 \end{funcdesc}
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	673
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	674 \begin{datadesc}{pathconf_names}
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	675 Dictionary mapping names accepted by \function{pathconf()} and
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	676 \function{fpathconf()} to the integer values defined for those names
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	677 by the host operating system. This can be used to determine the set
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	678 of names known to the system.
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	679 Availability: \UNIX.
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	680 \end{datadesc}
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	681
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	682 \begin{funcdesc}{readlink}{path}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	683 Return a string representing the path to which the symbolic link
17998 c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	684 points. The result may be either an absolute or relative pathname; if
c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	685 it is relative, it may be converted to an absolute pathname using
c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	686 \code{os.path.join(os.path.dirname(\var{path}), \var{result})}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	687 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	688 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	689
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	690 \begin{funcdesc}{remove}{path}
17998 c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	691 Remove the file \var{path}. If \var{path} is a directory,
c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	692 \exception{OSError} is raised; see \function{rmdir()} below to remove
c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	693 a directory. This is identical to the \function{unlink()} function
c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	694 documented below. On Windows, attempting to remove a file that is in
c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	695 use causes an exception to be raised; on \UNIX, the directory entry is
c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	696 removed but the storage allocated to the file is not made available
c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	697 until the original file is no longer in use.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	698 Availability: Macintosh, \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	699 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	700
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	701 \begin{funcdesc}{removedirs}{path}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	702 \index{directory!deleting}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	703 Recursive directory removal function. Works like
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	704 \function{rmdir()} except that, if the leaf directory is
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	705 successfully removed, directories corresponding to rightmost path
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	706 segments will be pruned way until either the whole path is consumed or
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	707 an error is raised (which is ignored, because it generally means that
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	708 a parent directory is not empty). Throws an \exception{error}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	709 exception if the leaf directory could not be successfully removed.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	710 \versionadded{1.5.2}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	711 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	712
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	713 \begin{funcdesc}{rename}{src, dst}
17998 c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	714 Rename the file or directory \var{src} to \var{dst}. If \var{dst} is
c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	715 a directory, \exception{OSError} will be raised. On \UNIX, if
c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	716 \var{dst} exists and is a file, it will be removed silently if the
c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	717 user has permission. The operation may fail on some \UNIX{} flavors
18029 4d62a2fec930 is -> if in rename description Skip Montanaro <skip@pobox.com> parents: 18012 diff changeset	718 if \var{src} and \var{dst} are on different filesystems. If
17998 c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	719 successful, the renaming will be an atomic operation (this is a
c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	720 \POSIX{} requirement). On Windows, if \var{dst} already exists,
c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	721 \exception{OSError} will be raised even if it is a file; there may be
c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	722 no way to implement an atomic rename when \var{dst} names an existing
c8cb79772364 readlink() description: Added note that the return value may be either Fred Drake <fdrake@acm.org> parents: 15264 diff changeset	723 file.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	724 Availability: Macintosh, \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	725 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	726
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	727 \begin{funcdesc}{renames}{old, new}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	728 Recursive directory or file renaming function.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	729 Works like \function{rename()}, except creation of any intermediate
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	730 directories needed to make the new pathname good is attempted first.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	731 After the rename, directories corresponding to rightmost path segments
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	732 of the old name will be pruned away using \function{removedirs()}.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	733
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	734 Note: this function can fail with the new directory structure made if
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	735 you lack permissions needed to remove the leaf directory or file.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	736 \versionadded{1.5.2}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	737 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	738
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	739 \begin{funcdesc}{rmdir}{path}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	740 Remove the directory \var{path}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	741 Availability: Macintosh, \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	742 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	743
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	744 \begin{funcdesc}{stat}{path}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	745 Perform a \cfunction{stat()} system call on the given path. The
21108 12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	746 return value is an object whose attributes correspond to the members of
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	747 the \ctype{stat} structure, namely:
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	748 \member{st_mode} (protection bits),
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	749 \member{st_ino} (inode number),
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	750 \member{st_dev} (device),
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	751 \member{st_nlink} (number of hard links,
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	752 \member{st_uid} (user ID of owner),
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	753 \member{st_gid} (group ID of owner),
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	754 \member{st_size} (size of file, in bytes),
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	755 \member{st_atime} (time of most recent access),
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	756 \member{st_mtime} (time of most recent content modification),
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	757 \member{st_ctime}
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	758 (time of most recent content modification or metadata change).
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	759
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	760 On some Unix systems (such as Linux), the following attributes may
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	761 also be available:
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	762 \member{st_blocks} (number of blocks allocated for file),
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	763 \member{st_blksize} (filesystem blocksize),
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	764 \member{st_rdev} (type of device if an inode device).
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	765
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	766 On Mac OS systems, the following attributes may also be available:
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	767 \member{st_rsize},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	768 \member{st_creator},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	769 \member{st_type}.
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	770
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	771 On RISCOS systems, the following attributes are also available:
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	772 \member{st_ftype} (file type),
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	773 \member{st_attrs} (attributes),
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	774 \member{st_obtype} (object type).
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	775
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	776 For backward compatibility, the return value of \function{stat()} is
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	777 also accessible as a tuple of at least 10 integers giving the most
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	778 important (and portable) members of the \ctype{stat} structure, in the
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	779 order
21108 12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	780 \member{st_mode},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	781 \member{st_ino},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	782 \member{st_dev},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	783 \member{st_nlink},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	784 \member{st_uid},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	785 \member{st_gid},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	786 \member{st_size},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	787 \member{st_atime},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	788 \member{st_mtime},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	789 \member{st_ctime}.
15234 8fe2a7981d70 For os.stat() & friends, note that the time fields are returned as Fred Drake <fdrake@acm.org> parents: 15008 diff changeset	790 More items may be added at the end by some implementations. Note that
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	791 on the Mac OS, the time values are floating point values, like all
346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	792 time values on the Mac OS.
21108 12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	793 The standard module \refmodule{stat}\refstmodindex{stat} defines
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	794 functions and constants that are useful for extracting information
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	795 from a \ctype{stat} structure.
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	796 (On Windows, some items are filled with dummy values.)
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	797 Availability: Macintosh, \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	798
21108 12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	799 \versionchanged
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	800 [Added access to values as attributes of the returned object]{2.2}
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	801 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	802
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	803 \begin{funcdesc}{statvfs}{path}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	804 Perform a \cfunction{statvfs()} system call on the given path. The
21108 12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	805 return value is an object whose attributes describe the filesystem on
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	806 the given path, and correspond to the members of the
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	807 \ctype{statvfs} structure, namely:
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	808 \member{f_frsize},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	809 \member{f_blocks},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	810 \member{f_bfree},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	811 \member{f_bavail},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	812 \member{f_files},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	813 \member{f_ffree},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	814 \member{f_favail},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	815 \member{f_flag},
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	816 \member{f_namemax}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	817 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	818
21108 12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	819 For backward compatibility, the return value is also accessible as a
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	820 tuple whose values correspond to the attributes, in the order given above.
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	821 The standard module \refmodule{statvfs}\refstmodindex{statvfs}
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	822 defines constants that are useful for extracting information
21108 12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	823 from a \ctype{statvfs} structure when accessing it as a sequence; this
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	824 remains useful when writing code that needs to work with versions of
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	825 Python that don't support accessing the fields as attributes.
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	826
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	827 \versionchanged
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	828 [Added access to values as attributes of the returned object]{2.2}
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	829 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	830
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	831 \begin{funcdesc}{symlink}{src, dst}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	832 Create a symbolic link pointing to \var{src} named \var{dst}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	833 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	834 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	835
11534 68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	836 \begin{funcdesc}{tempnam}{\optional{dir\optional{, prefix}}}
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	837 Return a unique path name that is reasonable for creating a temporary
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	838 file. This will be an absolute path that names a potential directory
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	839 entry in the directory \var{dir} or a common location for temporary
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	840 files if \var{dir} is omitted or \code{None}. If given and not
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	841 \code{None}, \var{prefix} is used to provide a short prefix to the
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	842 filename. Applications are responsible for properly creating and
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	843 managing files created using paths returned by \function{tempnam()};
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	844 no automatic cleanup is provided.
20337 4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	845 \warning{Use of \function{tempnam()} is vulnerable to symlink attacks;
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	846 consider using \function{tmpfile()} instead.}
18675 f7be7e9a6f20 Update the availability information for os.tempnam(), os.tmpfile(), and Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	847 Availability: \UNIX, Windows.
11534 68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	848 \end{funcdesc}
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	849
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	850 \begin{funcdesc}{tmpnam}{}
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	851 Return a unique path name that is reasonable for creating a temporary
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	852 file. This will be an absolute path that names a potential directory
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	853 entry in a common location for temporary files. Applications are
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	854 responsible for properly creating and managing files created using
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	855 paths returned by \function{tmpnam()}; no automatic cleanup is
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	856 provided.
20337 4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	857 \warning{Use of \function{tmpnam()} is vulnerable to symlink attacks;
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	858 consider using \function{tmpfile()} instead.}
18675 f7be7e9a6f20 Update the availability information for os.tempnam(), os.tmpfile(), and Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	859 Availability: \UNIX, Windows.
11534 68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	860 \end{funcdesc}
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	861
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	862 \begin{datadesc}{TMP_MAX}
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	863 The maximum number of unique names that \function{tmpnam()} will
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	864 generate before reusing names.
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	865 \end{datadesc}
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	866
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	867 \begin{funcdesc}{unlink}{path}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	868 Remove the file \var{path}. This is the same function as
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	869 \function{remove()}; the \function{unlink()} name is its traditional
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	870 \UNIX{} name.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	871 Availability: Macintosh, \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	872 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	873
12535 8a5036544727 Document the new additional signature for utime(). In addition to the Barry Warsaw <barry@python.org> parents: 12223 diff changeset	874 \begin{funcdesc}{utime}{path, times}
8a5036544727 Document the new additional signature for utime(). In addition to the Barry Warsaw <barry@python.org> parents: 12223 diff changeset	875 Set the access and modified times of the file specified by \var{path}.
8a5036544727 Document the new additional signature for utime(). In addition to the Barry Warsaw <barry@python.org> parents: 12223 diff changeset	876 If \var{times} is \code{None}, then the file's access and modified
8a5036544727 Document the new additional signature for utime(). In addition to the Barry Warsaw <barry@python.org> parents: 12223 diff changeset	877 times are set to the current time. Otherwise, \var{times} must be a
12550 dc9d1b71cc38 Use \versionchanged to indicate when the second parameter to utime() Fred Drake <fdrake@acm.org> parents: 12535 diff changeset	878 2-tuple of numbers, of the form \code{(\var{atime}, \var{mtime})}
dc9d1b71cc38 Use \versionchanged to indicate when the second parameter to utime() Fred Drake <fdrake@acm.org> parents: 12535 diff changeset	879 which is used to set the access and modified times, respectively.
15264 b51629980c88 Capitalize first letter of an explanation for a \versionchanged Fred Drake <fdrake@acm.org> parents: 15234 diff changeset	880 \versionchanged[Added support for \code{None} for \var{times}]{2.0}
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	881 Availability: Macintosh, \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	882 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	883
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	884
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	885 \subsection{Process Management \label{os-process}}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	886
11534 68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	887 These functions may be used to create and manage processes.
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	888
14789 be2df9935edd Added explanation of the use of the first program argument passed to the Fred Drake <fdrake@acm.org> parents: 13927 diff changeset	889 The various \function{exec*()} functions take a list of arguments for
be2df9935edd Added explanation of the use of the first program argument passed to the Fred Drake <fdrake@acm.org> parents: 13927 diff changeset	890 the new program loaded into the process. In each case, the first of
be2df9935edd Added explanation of the use of the first program argument passed to the Fred Drake <fdrake@acm.org> parents: 13927 diff changeset	891 these arguments is passed to the new program as its own name rather
be2df9935edd Added explanation of the use of the first program argument passed to the Fred Drake <fdrake@acm.org> parents: 13927 diff changeset	892 than as an argument a user may have typed on a command line. For the
be2df9935edd Added explanation of the use of the first program argument passed to the Fred Drake <fdrake@acm.org> parents: 13927 diff changeset	893 C programmer, this is the \code{argv[0]} passed to a program's
be2df9935edd Added explanation of the use of the first program argument passed to the Fred Drake <fdrake@acm.org> parents: 13927 diff changeset	894 \cfunction{main()}. For example, \samp{os.execv('/bin/echo', ['foo',
be2df9935edd Added explanation of the use of the first program argument passed to the Fred Drake <fdrake@acm.org> parents: 13927 diff changeset	895 'bar'])} will only print \samp{bar} on standard output; \samp{foo}
be2df9935edd Added explanation of the use of the first program argument passed to the Fred Drake <fdrake@acm.org> parents: 13927 diff changeset	896 will seem to be ignored.
be2df9935edd Added explanation of the use of the first program argument passed to the Fred Drake <fdrake@acm.org> parents: 13927 diff changeset	897
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	898
11534 68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	899 \begin{funcdesc}{abort}{}
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	900 Generate a \constant{SIGABRT} signal to the current process. On
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	901 \UNIX, the default behavior is to produce a core dump; on Windows, the
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	902 process immediately returns an exit code of \code{3}. Be aware that
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	903 programs which use \function{signal.signal()} to register a handler
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	904 for \constant{SIGABRT} will behave differently.
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	905 Availability: \UNIX, Windows.
68364bf002f1 Document the new stuff in the os module. Fred Drake <fdrake@acm.org> parents: 11292 diff changeset	906 \end{funcdesc}
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	907
20529 dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	908 \begin{funcdesc}{execl}{path, arg0, arg1, \moreargs}
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	909 \funcline{execle}{path, arg0, arg1, \moreargs, env}
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	910 \funcline{execlp}{file, arg0, arg1, \moreargs}
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	911 \funcline{execlpe}{file, arg0, arg1, \moreargs, env}
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	912 \funcline{execv}{path, args}
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	913 \funcline{execve}{path, args, env}
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	914 \funcline{execvp}{file, args}
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	915 \funcline{execvpe}{file, args, env}
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	916 These functions all execute a new program, replacing the current
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	917 process; they do not return. On \UNIX, the new executable is loaded
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	918 into the current process, and will have the same process ID as the
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	919 caller. Errors will be reported as \exception{OSError} exceptions.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	920
20529 dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	921 The \character{l} and \character{v} variants of the
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	922 \function{exec*()} functions differ in how command-line arguments are
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	923 passed. The \character{l} variants are perhaps the easiest to work
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	924 with if the number of parameters is fixed when the code is written;
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	925 the individual parameters simply become additional parameters to the
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	926 \function{execl*()} functions. The \character{v} variants are good
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	927 when the number of parameters is variable, with the arguments being
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	928 passed in a list or tuple as the \var{args} parameter. In either
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	929 case, the arguments to the child process must start with the name of
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	930 the command being run.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	931
20529 dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	932 The variants which include a \character{p} near the end
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	933 (\function{execlp()}, \function{execlpe()}, \function{execvp()},
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	934 and \function{execvpe()}) will use the \envvar{PATH} environment
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	935 variable to locate the program \var{file}. When the environment is
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	936 being replaced (using one of the \function{exec*e()} variants,
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	937 discussed in the next paragraph), the
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	938 new environment is used as the source of the \envvar{PATH} variable.
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	939 The other variants, \function{execl()}, \function{execle()},
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	940 \function{execv()}, and \function{execve()}, will not use the
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	941 \envvar{PATH} variable to locate the executable; \var{path} must
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	942 contain an appropriate absolute or relative path.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	943
20529 dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	944 For \function{execle()}, \function{execlpe()}, \function{execve()},
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	945 and \function{execvpe()} (note that these all end in \character{e}),
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	946 the \var{env} parameter must be a mapping which is used to define the
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	947 environment variables for the new process; the \function{execl()},
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	948 \function{execlp()}, \function{execv()}, and \function{execvp()}
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	949 all cause the new process to inherit the environment of the current
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	950 process.
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	951 Availability: \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	952 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	953
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	954 \begin{funcdesc}{_exit}{n}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	955 Exit to the system with status \var{n}, without calling cleanup
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	956 handlers, flushing stdio buffers, etc.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	957 Availability: \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	958
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	959 Note: the standard way to exit is \code{sys.exit(\var{n})}.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	960 \function{_exit()} should normally only be used in the child process
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	961 after a \function{fork()}.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	962 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	963
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	964 \begin{funcdesc}{fork}{}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	965 Fork a child process. Return \code{0} in the child, the child's
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	966 process id in the parent.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	967 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	968 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	969
13067 a679bdb43fad Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 12550 diff changeset	970 \begin{funcdesc}{forkpty}{}
a679bdb43fad Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 12550 diff changeset	971 Fork a child process, using a new pseudo-terminal as the child's
a679bdb43fad Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 12550 diff changeset	972 controlling terminal. Return a pair of \code{(\var{pid}, \var{fd})},
a679bdb43fad Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 12550 diff changeset	973 where \var{pid} is \code{0} in the child, the new child's process id
21108 12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	974 in the parent, and \var{fd} is the file descriptor of the master end
13067 a679bdb43fad Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 12550 diff changeset	975 of the pseudo-terminal. For a more portable approach, use the
a679bdb43fad Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 12550 diff changeset	976 \refmodule{pty} module.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	977 Availability: Some flavors of \UNIX.
13067 a679bdb43fad Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 12550 diff changeset	978 \end{funcdesc}
a679bdb43fad Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 12550 diff changeset	979
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	980 \begin{funcdesc}{kill}{pid, sig}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	981 \index{process!killing}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	982 \index{process!signalling}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	983 Kill the process \var{pid} with signal \var{sig}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	984 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	985 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	986
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	987 \begin{funcdesc}{nice}{increment}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	988 Add \var{increment} to the process's ``niceness''. Return the new
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	989 niceness.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	990 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	991 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	992
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	993 \begin{funcdesc}{plock}{op}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	994 Lock program segments into memory. The value of \var{op}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	995 (defined in \code{<sys/lock.h>}) determines which segments are locked.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	996 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	997 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	998
18074 410bbf5d98f9 Fixed parameter order for os.popen2(), os.popen3(), and os.popen(4). Added Fred Drake <fdrake@acm.org> parents: 18029 diff changeset	999 \begin{funcdescni}{popen}{\unspecified}
410bbf5d98f9 Fixed parameter order for os.popen2(), os.popen3(), and os.popen(4). Added Fred Drake <fdrake@acm.org> parents: 18029 diff changeset	1000 \funclineni{popen2}{\unspecified}
410bbf5d98f9 Fixed parameter order for os.popen2(), os.popen3(), and os.popen(4). Added Fred Drake <fdrake@acm.org> parents: 18029 diff changeset	1001 \funclineni{popen3}{\unspecified}
410bbf5d98f9 Fixed parameter order for os.popen2(), os.popen3(), and os.popen(4). Added Fred Drake <fdrake@acm.org> parents: 18029 diff changeset	1002 \funclineni{popen4}{\unspecified}
410bbf5d98f9 Fixed parameter order for os.popen2(), os.popen3(), and os.popen(4). Added Fred Drake <fdrake@acm.org> parents: 18029 diff changeset	1003 Run child processes, returning opened pipes for communications. These
410bbf5d98f9 Fixed parameter order for os.popen2(), os.popen3(), and os.popen(4). Added Fred Drake <fdrake@acm.org> parents: 18029 diff changeset	1004 functions are described in section \ref{os-newstreams}.
410bbf5d98f9 Fixed parameter order for os.popen2(), os.popen3(), and os.popen(4). Added Fred Drake <fdrake@acm.org> parents: 18029 diff changeset	1005 \end{funcdescni}
410bbf5d98f9 Fixed parameter order for os.popen2(), os.popen3(), and os.popen(4). Added Fred Drake <fdrake@acm.org> parents: 18029 diff changeset	1006
19325 db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1007 \begin{funcdesc}{spawnl}{mode, path, \moreargs}
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1008 \funcline{spawnle}{mode, path, \moreargs, env}
20529 dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1009 \funcline{spawnlp}{mode, file, \moreargs}
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1010 \funcline{spawnlpe}{mode, file, \moreargs, env}
19325 db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1011 \funcline{spawnv}{mode, path, args}
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1012 \funcline{spawnve}{mode, path, args, env}
20529 dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1013 \funcline{spawnvp}{mode, file, args}
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1014 \funcline{spawnvpe}{mode, file, args, env}
19325 db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1015 Execute the program \var{path} in a new process. If \var{mode} is
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1016 \constant{P_NOWAIT}, this function returns the process ID of the new
21279 643244f7f467 s/it/if/ in descriptions of spawn mode argument. Tim Peters <tim.peters@gmail.com> parents: 21108 diff changeset	1017 process; if \var{mode} is \constant{P_WAIT}, returns the process's
19325 db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1018 exit code if it exits normally, or \code{-\var{signal}}, where
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1019 \var{signal} is the signal that killed the process.
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1020
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1021 The \character{l} and \character{v} variants of the
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1022 \function{spawn*()} functions differ in how command-line arguments are
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1023 passed. The \character{l} variants are perhaps the easiest to work
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1024 with if the number of parameters is fixed when the code is written;
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1025 the individual parameters simply become additional parameters to the
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1026 \function{spawnl*()} functions. The \character{v} variants are good
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1027 when the number of parameters is variable, with the arguments being
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1028 passed in a list or tuple as the \var{args} parameter. In either
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1029 case, the arguments to the child process must start with the name of
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1030 the command being run.
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1031
20529 dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1032 The variants which include a second \character{p} near the end
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1033 (\function{spawnlp()}, \function{spawnlpe()}, \function{spawnvp()},
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1034 and \function{spawnvpe()}) will use the \envvar{PATH} environment
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1035 variable to locate the program \var{file}. When the environment is
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1036 being replaced (using one of the \function{spawn*e()} variants,
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1037 discussed in the next paragraph), the new environment is used as the
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1038 source of the \envvar{PATH} variable. The other variants,
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1039 \function{spawnl()}, \function{spawnle()}, \function{spawnv()}, and
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1040 \function{spawnve()}, will not use the \envvar{PATH} variable to
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1041 locate the executable; \var{path} must contain an appropriate absolute
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1042 or relative path.
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1043
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1044 For \function{spawnle()}, \function{spawnlpe()}, \function{spawnve()},
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1045 and \function{spawnvpe()} (note that these all end in \character{e}),
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1046 the \var{env} parameter must be a mapping which is used to define the
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1047 environment variables for the new process; the \function{spawnl()},
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1048 \function{spawnlp()}, \function{spawnv()}, and \function{spawnvp()}
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1049 all cause the new process to inherit the environment of the current
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1050 process.
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1051
19325 db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1052 As an example, the following calls to \function{spawnlp()} and
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1053 \function{spawnvpe()} are equivalent:
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1054
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1055 \begin{verbatim}
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1056 import os
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1057 os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1058
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1059 L = ['cp', 'index.html', '/dev/null']
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1060 os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1061 \end{verbatim}
db488cc9f259 Re-write the description of the os.spawn() functions, and cover the Fred Drake <fdrake@acm.org>* parents: 18812 diff changeset	1062
20529 dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1063 Availability: \UNIX, Windows. \function{spawnvp()} and
dbfed3bf160e Straighten out the exec() function descriptions a bit, and clarify a few Fred Drake <fdrake@acm.org>* parents: 20511 diff changeset	1064 \function{spawnvpe()} are not available on Windows.
18080 ff2d7c183715 Add the appropriate availability annotations for the popen() family of Fred Drake <fdrake@acm.org>* parents: 18074 diff changeset	1065 \versionadded{1.6}
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1066 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1067
20337 4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1068 \begin{datadesc}{P_NOWAIT}
10190 8f4ad14c3407 Remove "_" from the P_* symbols used with the spawn() functions. Fred Drake <fdrake@acm.org>* parents: 10092 diff changeset	1069 \dataline{P_NOWAITO}
20337 4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1070 Possible values for the \var{mode} parameter to the \function{spawn*()}
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1071 family of functions. If either of these values is given, the
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1072 \function{spawn*()} functions will return as soon as the new process
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1073 has been created, with the process ID as the return value.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	1074 Availability: \UNIX, Windows.
18080 ff2d7c183715 Add the appropriate availability annotations for the popen() family of Fred Drake <fdrake@acm.org>* parents: 18074 diff changeset	1075 \versionadded{1.6}
11877 5d0879e1ff37 Update portability information for the spawn() functions and related Fred Drake <fdrake@acm.org>* parents: 11578 diff changeset	1076 \end{datadesc}
5d0879e1ff37 Update portability information for the spawn() functions and related Fred Drake <fdrake@acm.org>* parents: 11578 diff changeset	1077
20337 4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1078 \begin{datadesc}{P_WAIT}
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1079 Possible value for the \var{mode} parameter to the \function{spawn*()}
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1080 family of functions. If this is given as \var{mode}, the
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1081 \function{spawn*()} functions will not return until the new process
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1082 has run to completion and will return the exit code of the process the
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1083 run is successful, or \code{-\var{signal}} if a signal kills the
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1084 process.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	1085 Availability: \UNIX, Windows.
20337 4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1086 \versionadded{1.6}
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1087 \end{datadesc}
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1088
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1089 \begin{datadesc}{P_DETACH}
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1090 \dataline{P_OVERLAY}
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1091 Possible values for the \var{mode} parameter to the
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1092 \function{spawn*()} family of functions. These are less portable than
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1093 those listed above.
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1094 \constant{P_DETACH} is similar to \constant{P_NOWAIT}, but the new
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1095 process is detached from the console of the calling process.
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1096 If \constant{P_OVERLAY} is used, the current process will be replaced;
4bf3fce3f6ce Improve the documentation for the os.P_* constants used with the os.spawn() Fred Drake <fdrake@acm.org>* parents: 20264 diff changeset	1097 the \function{spawn*()} function will not return.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1098 Availability: Windows.
18080 ff2d7c183715 Add the appropriate availability annotations for the popen() family of Fred Drake <fdrake@acm.org>* parents: 18074 diff changeset	1099 \versionadded{1.6}
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1100 \end{datadesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1101
14922 9a8700fdc52b os.startfile() documentation, based on text from Tim Peters. Fred Drake <fdrake@acm.org> parents: 14915 diff changeset	1102 \begin{funcdesc}{startfile}{path}
9a8700fdc52b os.startfile() documentation, based on text from Tim Peters. Fred Drake <fdrake@acm.org> parents: 14915 diff changeset	1103 Start a file with its associated application. This acts like
9a8700fdc52b os.startfile() documentation, based on text from Tim Peters. Fred Drake <fdrake@acm.org> parents: 14915 diff changeset	1104 double-clicking the file in Windows Explorer, or giving the file name
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1105 as an argument to the \program{start} command from the interactive
346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1106 command shell: the file is opened with whatever application (if any)
346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1107 its extension is associated.
14922 9a8700fdc52b os.startfile() documentation, based on text from Tim Peters. Fred Drake <fdrake@acm.org> parents: 14915 diff changeset	1108
9a8700fdc52b os.startfile() documentation, based on text from Tim Peters. Fred Drake <fdrake@acm.org> parents: 14915 diff changeset	1109 \function{startfile()} returns as soon as the associated application
9a8700fdc52b os.startfile() documentation, based on text from Tim Peters. Fred Drake <fdrake@acm.org> parents: 14915 diff changeset	1110 is launched. There is no option to wait for the application to close,
9a8700fdc52b os.startfile() documentation, based on text from Tim Peters. Fred Drake <fdrake@acm.org> parents: 14915 diff changeset	1111 and no way to retrieve the application's exit status. The \var{path}
9a8700fdc52b os.startfile() documentation, based on text from Tim Peters. Fred Drake <fdrake@acm.org> parents: 14915 diff changeset	1112 parameter is relative to the current directory. If you want to use an
9a8700fdc52b os.startfile() documentation, based on text from Tim Peters. Fred Drake <fdrake@acm.org> parents: 14915 diff changeset	1113 absolute path, make sure the first character is not a slash
9a8700fdc52b os.startfile() documentation, based on text from Tim Peters. Fred Drake <fdrake@acm.org> parents: 14915 diff changeset	1114 (\character{/}); the underlying Win32 \cfunction{ShellExecute()}
18812 0c3ad503ad6c Typo: Added missing "if". Fred Drake <fdrake@acm.org> parents: 18675 diff changeset	1115 function doesn't work if it is. Use the \function{os.path.normpath()}
14922 9a8700fdc52b os.startfile() documentation, based on text from Tim Peters. Fred Drake <fdrake@acm.org> parents: 14915 diff changeset	1116 function to ensure that the path is properly encoded for Win32.
9a8700fdc52b os.startfile() documentation, based on text from Tim Peters. Fred Drake <fdrake@acm.org> parents: 14915 diff changeset	1117 Availability: Windows.
9a8700fdc52b os.startfile() documentation, based on text from Tim Peters. Fred Drake <fdrake@acm.org> parents: 14915 diff changeset	1118 \versionadded{2.0}
9a8700fdc52b os.startfile() documentation, based on text from Tim Peters. Fred Drake <fdrake@acm.org> parents: 14915 diff changeset	1119 \end{funcdesc}
9a8700fdc52b os.startfile() documentation, based on text from Tim Peters. Fred Drake <fdrake@acm.org> parents: 14915 diff changeset	1120
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1121 \begin{funcdesc}{system}{command}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1122 Execute the command (a string) in a subshell. This is implemented by
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1123 calling the Standard C function \cfunction{system()}, and has the
10659 69fb81facb03 Small markup nits. Fred Drake <fdrake@acm.org> parents: 10346 diff changeset	1124 same limitations. Changes to \code{posix.environ}, \code{sys.stdin},
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1125 etc.\ are not reflected in the environment of the executed command.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1126 The return value is the exit status of the process encoded in the
10957 bdc1703ff92c At David Ascher's request, clarify that os.system() always returns 0 Fred Drake <fdrake@acm.org> parents: 10878 diff changeset	1127 format specified for \function{wait()}, except on Windows 95 and 98,
11015 41385d50a10c Further clarfication of the system-dependence of the system() return Fred Drake <fdrake@acm.org> parents: 10977 diff changeset	1128 where it is always \code{0}. Note that \POSIX{} does not specify the
41385d50a10c Further clarfication of the system-dependence of the system() return Fred Drake <fdrake@acm.org> parents: 10977 diff changeset	1129 meaning of the return value of the C \cfunction{system()} function,
41385d50a10c Further clarfication of the system-dependence of the system() return Fred Drake <fdrake@acm.org> parents: 10977 diff changeset	1130 so the return value of the Python function is system-dependent.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	1131 Availability: \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1132 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1133
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1134 \begin{funcdesc}{times}{}
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1135 Return a 5-tuple of floating point numbers indicating accumulated
346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1136 (processor or other)
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1137 times, in seconds. The items are: user time, system time, children's
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1138 user time, children's system time, and elapsed real time since a fixed
10659 69fb81facb03 Small markup nits. Fred Drake <fdrake@acm.org> parents: 10346 diff changeset	1139 point in the past, in that order. See the \UNIX{} manual page
69fb81facb03 Small markup nits. Fred Drake <fdrake@acm.org> parents: 10346 diff changeset	1140 \manpage{times}{2} or the corresponding Windows Platform API
69fb81facb03 Small markup nits. Fred Drake <fdrake@acm.org> parents: 10346 diff changeset	1141 documentation.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	1142 Availability: \UNIX, Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1143 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1144
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1145 \begin{funcdesc}{wait}{}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1146 Wait for completion of a child process, and return a tuple containing
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1147 its pid and exit status indication: a 16-bit number, whose low byte is
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1148 the signal number that killed the process, and whose high byte is the
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1149 exit status (if the signal number is zero); the high bit of the low
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1150 byte is set if a core file was produced.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	1151 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1152 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1153
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1154 \begin{funcdesc}{waitpid}{pid, options}
11191 01c51b268c04 Explain the possible range of values for the pid parameter to Fred Drake <fdrake@acm.org> parents: 11179 diff changeset	1155 Wait for completion of a child process given by process id \var{pid},
01c51b268c04 Explain the possible range of values for the pid parameter to Fred Drake <fdrake@acm.org> parents: 11179 diff changeset	1156 and return a tuple containing its process id and exit status
01c51b268c04 Explain the possible range of values for the pid parameter to Fred Drake <fdrake@acm.org> parents: 11179 diff changeset	1157 indication (encoded as for \function{wait()}). The semantics of the
01c51b268c04 Explain the possible range of values for the pid parameter to Fred Drake <fdrake@acm.org> parents: 11179 diff changeset	1158 call are affected by the value of the integer \var{options}, which
01c51b268c04 Explain the possible range of values for the pid parameter to Fred Drake <fdrake@acm.org> parents: 11179 diff changeset	1159 should be \code{0} for normal operation.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	1160 Availability: \UNIX.
11191 01c51b268c04 Explain the possible range of values for the pid parameter to Fred Drake <fdrake@acm.org> parents: 11179 diff changeset	1161
01c51b268c04 Explain the possible range of values for the pid parameter to Fred Drake <fdrake@acm.org> parents: 11179 diff changeset	1162 If \var{pid} is greater than \code{0}, \function{waitpid()} requests
01c51b268c04 Explain the possible range of values for the pid parameter to Fred Drake <fdrake@acm.org> parents: 11179 diff changeset	1163 status information for that specific process. If \var{pid} is
01c51b268c04 Explain the possible range of values for the pid parameter to Fred Drake <fdrake@acm.org> parents: 11179 diff changeset	1164 \code{0}, the request is for the status of any child in the process
01c51b268c04 Explain the possible range of values for the pid parameter to Fred Drake <fdrake@acm.org> parents: 11179 diff changeset	1165 group of the current process. If \var{pid} is \code{-1}, the request
01c51b268c04 Explain the possible range of values for the pid parameter to Fred Drake <fdrake@acm.org> parents: 11179 diff changeset	1166 pertains to any child of the current process. If \var{pid} is less
01c51b268c04 Explain the possible range of values for the pid parameter to Fred Drake <fdrake@acm.org> parents: 11179 diff changeset	1167 than \code{-1}, status is requested for any process in the process
01c51b268c04 Explain the possible range of values for the pid parameter to Fred Drake <fdrake@acm.org> parents: 11179 diff changeset	1168 group \code{-\var{pid}} (the absolute value of \var{pid}).
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1169 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1170
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1171 \begin{datadesc}{WNOHANG}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1172 The option for \function{waitpid()} to avoid hanging if no child
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1173 process status is available immediately.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	1174 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1175 \end{datadesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1176
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	1177 The following functions take a process status code as returned by
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	1178 \function{system()}, \function{wait()}, or \function{waitpid()} as a
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	1179 parameter. They may be used to determine the disposition of a
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11877 diff changeset	1180 process.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1181
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1182 \begin{funcdesc}{WIFSTOPPED}{status}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1183 Return true if the process has been stopped.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	1184 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1185 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1186
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1187 \begin{funcdesc}{WIFSIGNALED}{status}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1188 Return true if the process exited due to a signal.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	1189 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1190 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1191
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1192 \begin{funcdesc}{WIFEXITED}{status}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1193 Return true if the process exited using the \manpage{exit}{2} system
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1194 call.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	1195 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1196 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1197
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1198 \begin{funcdesc}{WEXITSTATUS}{status}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1199 If \code{WIFEXITED(\var{status})} is true, return the integer
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1200 parameter to the \manpage{exit}{2} system call. Otherwise, the return
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1201 value is meaningless.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	1202 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1203 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1204
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1205 \begin{funcdesc}{WSTOPSIG}{status}
10346 4e2d18973b94 Fixed description of WSTOPSIG(), added WTERMSIG(). Problem reported Fred Drake <fdrake@acm.org> parents: 10312 diff changeset	1206 Return the signal which caused the process to stop.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	1207 Availability: \UNIX.
10346 4e2d18973b94 Fixed description of WSTOPSIG(), added WTERMSIG(). Problem reported Fred Drake <fdrake@acm.org> parents: 10312 diff changeset	1208 \end{funcdesc}
4e2d18973b94 Fixed description of WSTOPSIG(), added WTERMSIG(). Problem reported Fred Drake <fdrake@acm.org> parents: 10312 diff changeset	1209
4e2d18973b94 Fixed description of WSTOPSIG(), added WTERMSIG(). Problem reported Fred Drake <fdrake@acm.org> parents: 10312 diff changeset	1210 \begin{funcdesc}{WTERMSIG}{status}
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1211 Return the signal which caused the process to exit.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	1212 Availability: \UNIX.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1213 \end{funcdesc}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1214
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1215
13625 fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope Thomas Wouters <thomas@python.org> parents: 13582 diff changeset	1216 \subsection{Miscellaneous System Information \label{os-path}}
11578 4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1217
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1218
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1219 \begin{funcdesc}{confstr}{name}
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1220 Return string-valued system configuration values.
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1221 \var{name} specifies the configuration value to retrieve; it may be a
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1222 string which is the name of a defined system value; these names are
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1223 specified in a number of standards (\POSIX, \UNIX 95, \UNIX 98, and
11578 4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1224 others). Some platforms define additional names as well. The names
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1225 known to the host operating system are given in the
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1226 \code{confstr_names} dictionary. For configuration variables not
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1227 included in that mapping, passing an integer for \var{name} is also
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1228 accepted.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	1229 Availability: \UNIX.
11578 4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1230
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1231 If the configuration value specified by \var{name} isn't defined, the
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1232 empty string is returned.
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1233
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1234 If \var{name} is a string and is not known, \exception{ValueError} is
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1235 raised. If a specific value for \var{name} is not supported by the
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1236 host system, even if it is included in \code{confstr_names}, an
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1237 \exception{OSError} is raised with \constant{errno.EINVAL} for the
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1238 error number.
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1239 \end{funcdesc}
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1240
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1241 \begin{datadesc}{confstr_names}
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1242 Dictionary mapping names accepted by \function{confstr()} to the
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1243 integer values defined for those names by the host operating system.
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1244 This can be used to determine the set of names known to the system.
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1245 Availability: \UNIX.
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1246 \end{datadesc}
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1247
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1248 \begin{funcdesc}{sysconf}{name}
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1249 Return integer-valued system configuration values.
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1250 If the configuration value specified by \var{name} isn't defined,
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1251 \code{-1} is returned. The comments regarding the \var{name}
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1252 parameter for \function{confstr()} apply here as well; the dictionary
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1253 that provides information on the known names is given by
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1254 \code{sysconf_names}.
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20529 diff changeset	1255 Availability: \UNIX.
11578 4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1256 \end{funcdesc}
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1257
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1258 \begin{datadesc}{sysconf_names}
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1259 Dictionary mapping names accepted by \function{sysconf()} to the
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1260 integer values defined for those names by the host operating system.
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1261 This can be used to determine the set of names known to the system.
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1262 Availability: \UNIX.
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1263 \end{datadesc}
4c3e55c828d3 Document getgroups(), getlogin(), fpathconf(), pathconf(), Fred Drake <fdrake@acm.org> parents: 11534 diff changeset	1264
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1265
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1266 The follow data values are used to support path manipulation
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1267 operations. These are defined for all platforms.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1268
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1269 Higher-level operations on pathnames are defined in the
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1270 \refmodule{os.path} module.
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1271
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1272
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	1273 \begin{datadesc}{curdir}
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1274 The constant string used by the operating system to refer to the current
346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1275 directory.
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18080 diff changeset	1276 For example: \code{'.'} for \POSIX{} or \code{':'} for the Macintosh.
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	1277 \end{datadesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	1278
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	1279 \begin{datadesc}{pardir}
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1280 The constant string used by the operating system to refer to the parent
346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1281 directory.
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18080 diff changeset	1282 For example: \code{'..'} for \POSIX{} or \code{'::'} for the Macintosh.
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	1283 \end{datadesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	1284
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	1285 \begin{datadesc}{sep}
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1286 The character used by the operating system to separate pathname components,
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18080 diff changeset	1287 for example, \character{/} for \POSIX{} or \character{:} for the
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18080 diff changeset	1288 Macintosh. Note that knowing this is not sufficient to be able to
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18080 diff changeset	1289 parse or concatenate pathnames --- use \function{os.path.split()} and
8850 c351523ebc05 Markup nits. Fred Drake <fdrake@acm.org> parents: 8849 diff changeset	1290 \function{os.path.join()} --- but it is occasionally useful.
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	1291 \end{datadesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	1292
6205 e554b9f4a3aa Added os.altsep; this is '/' on DOS/Windows, and None on systems with Guido van Rossum <guido@python.org> parents: 5818 diff changeset	1293 \begin{datadesc}{altsep}
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1294 An alternative character used by the operating system to separate pathname
346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1295 components, or \code{None} if only one separator character exists. This is
346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1296 set to \character{/} on DOS and Windows systems where \code{sep} is a
346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1297 backslash.
6205 e554b9f4a3aa Added os.altsep; this is '/' on DOS/Windows, and None on systems with Guido van Rossum <guido@python.org> parents: 5818 diff changeset	1298 \end{datadesc}
e554b9f4a3aa Added os.altsep; this is '/' on DOS/Windows, and None on systems with Guido van Rossum <guido@python.org> parents: 5818 diff changeset	1299
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2527 diff changeset	1300 \begin{datadesc}{pathsep}
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1301 The character conventionally used by the operating system to separate
346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1302 search patch components (as in \envvar{PATH}), such as \character{:} for
346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1303 \POSIX{} or \character{;} for DOS and Windows.
8597 7bc714144b98 Documented os.linesep (line separator). Guido van Rossum <guido@python.org> parents: 7877 diff changeset	1304 \end{datadesc}
7bc714144b98 Documented os.linesep (line separator). Guido van Rossum <guido@python.org> parents: 7877 diff changeset	1305
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2527 diff changeset	1306 \begin{datadesc}{defpath}
21108 12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	1307 The default search path used by \function{execp()} and
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	1308 \function{spawnp()} if the environment doesn't have a \code{'PATH'}
12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	1309 key.
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2527 diff changeset	1310 \end{datadesc}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2527 diff changeset	1311
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1312 \begin{datadesc}{linesep}
4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1313 The string used to separate (or, rather, terminate) lines on the
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18080 diff changeset	1314 current platform. This may be a single character, such as \code{'\e
21108 12668d0af8f7 Various cleanups & markup fixes, mostly relating to the stat and statvfs Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	1315 n'} for \POSIX{} or \code{'\e r'} for Mac OS, or multiple characters,
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	1316 for example, \code{'\e r\e n'} for DOS and Windows.
10083 4894dcea126b Fix the os/posix documentation issue. Fred Drake <fdrake@acm.org> parents: 9736 diff changeset	1317 \end{datadesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libos.tex @ 21467:4e35fa5d5708 legacy-trunk