Mercurial > gnulib

annotate doc/xstdopen.texi @ 40231:9b3c79fdfe0b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
strtod: fix clash with strtold Problem reported for RHEL 5 by Jesse Caldwell (Bug#34817). * lib/strtod.c (compute_minus_zero, minus_zero): Simplify by remving the macro / external variable, and having just a function. User changed. This avoids the need for an external variable that might clash.
author Paul Eggert <eggert@cs.ucla.edu>
date Mon, 11 Mar 2019 16:40:29 -0700
parents 943155cd4a86
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
40092
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
1 @c GNU xstdopen and *-safer modules documentation
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
2
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
3 @c Copyright (C) 2019 Free Software Foundation, Inc.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
4
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
5 @c Permission is granted to copy, distribute and/or modify this document
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
6 @c under the terms of the GNU Free Documentation License, Version 1.3
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
7 @c or any later version published by the Free Software Foundation;
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
8 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
9 @c Texts. A copy of the license is included in the ``GNU Free
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
10 @c Documentation License'' file as part of this distribution.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
11
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
12 @c Written by Bruno Haible, based on ideas from Paul Eggert.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
13
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
14 @node Closed standard fds
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
15 @section Handling closed standard file descriptors
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
16
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
17 @cindex xstdopen
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
18 @cindex stdopen
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
19 @cindex dirent-safer
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
20 @cindex fcntl-safer
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
21 @cindex fopen-safer
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
22 @cindex freopen-safer
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
23 @cindex openat-safer
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
24 @cindex pipe2-safer
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
25 @cindex popen-safer
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
26 @cindex stdlib-safer
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
27 @cindex tmpfile-safer
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
28 @cindex unistd-safer
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
29
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
30 Usually, when a program gets invoked, its file descriptors
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
31 0 (for standard input), 1 (for standard output), and 2 (for standard error)
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
32 are open. But there are situations when some of these file descriptors are
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
33 closed. These situations can arise when
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
34 @itemize @bullet
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
35 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
36 The invoking process invokes @code{close()} on the file descriptor before
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
37 @code{exec}, or
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
38 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
39 The invoking process invokes @code{posix_spawn_file_actions_addclose()} for
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
40 the file descriptor before @code{posix_spawn} or @code{posix_spawnp}, or
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
41 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
42 The invoking process is a Bourne shell, and the shell script uses the
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
43 POSIX syntax for closing the file descriptor:
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
44 @code{<&-} for closing standard input,
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
45 @code{>&-} for closing standard output, or
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
46 @code{2>&-} for closing standard error.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
47 @end itemize
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
48
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
49 When a closed file descriptor is accessed through a system call, such as
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
50 @code{fcntl()}, @code{fstat()}, @code{read()}, or @code{write()}, the
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
51 system calls fails with error @code{EBADF} ("Bad file descriptor").
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
52
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
53 When a new file descriptor is allocated, the operating system chooses the
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
54 smallest non-negative integer that does not yet correspond to an open file
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
55 descriptor. So, when a given fd (0, 1, or 2) is closed, opening a new file
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
56 descriptor may assign the new file descriptor to this fd. This can have
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
57 unintended effects, because now standard input/output/error of your process
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
58 is referring to a file that was not meant to be used in that role.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
59
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
60 This situation is a security risk because the behaviour of the program
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
61 in this situation was surely never tested, therefore anything can happen
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
62 then -- from overwriting precious files of the user to endless loops.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
63
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
64 To deal with this situation, you first need to determine whether your
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
65 program is affected by the problem.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
66 @itemize @bullet
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
67 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
68 Does your program invoke functions that allocate new file descriptors?
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
69 These are the system calls
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
70 @itemize @bullet
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
71 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
72 @code{open()}, @code{openat()}, @code{creat()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
73 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
74 @code{dup()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
75 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
76 @code{fopen()}, @code{freopen()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
77 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
78 @code{pipe()}, @code{pipe2()}, @code{popen()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
79 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
80 @code{opendir()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
81 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
82 @code{tmpfile()}, @code{mkstemp()}, @code{mkstemps()}, @code{mkostemp()},
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
83 @code{mkostemps()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
84 @end itemize
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
85 @noindent
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
86 Note that you also have to consider the libraries that your program uses.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
87 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
88 If your program may open two or more file descriptors or FILE streams for
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
89 reading at the same time, and some of them may reference standard input,
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
90 your program @emph{is affected}.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
91 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
92 If your program may open two or more file descriptors or FILE streams for
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
93 writing at the same time, and some of them may reference standard output
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
94 or standard error, your program @emph{is affected}.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
95 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
96 If your program does not open new file descriptors or FILE streams, it is
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
97 @emph{not affected}.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
98 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
99 If your program opens only one new file descriptor or FILE stream at a time,
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
100 it is @emph{not affected}. This is often the case for programs that are
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
101 structured in simple phases: first a phase where input is read from a file
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
102 into memory, then a phase of processing in memory, finally a phase where
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
103 the result is written to a file.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
104 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
105 If your program opens only two new file descriptors or FILE streams at a
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
106 time, out of which one is for reading and the one is for writing, it is
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
107 @emph{not affected}. This is because if the first file descriptor is
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
108 allocated and the second file descriptor is picked as 0, 1, or 2, and
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
109 both happen to be the same, writing to the one opened in @code{O_RDONLY}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
110 mode will produce an error @code{EBADF}, as desired.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
111 @end itemize
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
112
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
113 If your program is affected, what is the mitigation?
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
114
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
115 Some operating systems install open file descriptors in place of the
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
116 closed ones, either in the @code{exec} system call or during program
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
117 startup. When such a file descriptor is accessed through a system call,
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
118 it behaves like an open file descriptor opened for the ``wrong'' direction:
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
119 the system calls @code{fcntl()} and @code{fstat()} succeed, whereas
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
120 @code{read()} from fd 0 and @code{write()} to fd 1 or 2 fail with error
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
121 @code{EBADF} ("Bad file descriptor"). The important point here is that
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
122 when your program allocates a new file descriptor, it will have a value
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
123 greater than 2.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
124
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
125 This mitigation is enabled on HP-UX, for all programs, and on glibc,
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
126 FreeBSD, NetBSD, OpenBSD, but only for setuid or setgid programs. Since
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
127 it is operating system dependent, it is not a complete mitigation.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
128
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
129 For a complete mitigation, Gnulib provides two alternative sets of modules:
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
130 @itemize @bullet
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
131 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
132 The @code{xstdopen} module.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
133 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
134 The @code{*-safer} modules:
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
135 @code{fcntl-safer},
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
136 @code{openat-safer},
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
137 @code{unistd-safer},
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
138 @code{fopen-safer},
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
139 @code{freopen-safer},
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
140 @code{pipe2-safer},
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
141 @code{popen-safer},
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
142 @code{dirent-safer},
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
143 @code{tmpfile-safer},
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
144 @code{stdlib-safer}.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
145 @end itemize
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
146
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
147 The approach with the @code{xstdopen} module is simpler, but it adds three
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
148 system calls to program startup. Whereas the approach with the @code{*-safer}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
149 modules is more complex, but adds no overhead (no additional system calls)
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
150 in the normal case.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
151
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
152 To use the approach with the @code{xstdopen} module:
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
153 @enumerate
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
154 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
155 Import the module @code{xstdopen} from Gnulib.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
156 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
157 In the compilation unit that contains the @code{main} function, include
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
158 @code{"xstdopen.h"}.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
159 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
160 In the @code{main} function, near the beginning, namely right after
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
161 the i18n related initializations (@code{setlocale}, @code{bindtextdomain},
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
162 @code{textdomain} invocations, if any) and
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
163 the @code{closeout} initialization (if any), insert the invocation:
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
164 @smallexample
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
165 /* Ensure that stdin, stdout, stderr are open. */
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
166 xstdopen ();
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
167 @end smallexample
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
168 @end enumerate
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
169
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
170 To use the approach with the @code{*-safer} modules:
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
171 @enumerate
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
172 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
173 Import the relevant modules from Gnulib.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
174 @item
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
175 In the compilation units that contain these function calls, include the
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
176 replacement header file.
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
177 @end enumerate
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
178 Do so according to this table:
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
179 @multitable @columnfractions .28 .32 .4
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
180 @headitem Function @tab Module @tab Header file
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
181 @item @code{open()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
182 @tab @code{fcntl-safer}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
183 @tab @code{"fcntl--.h"}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
184 @item @code{openat()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
185 @tab @code{openat-safer}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
186 @tab @code{"fcntl--.h"}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
187 @item @code{creat()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
188 @tab @code{fcntl-safer}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
189 @tab @code{"fcntl--.h"}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
190 @item @code{dup()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
191 @tab @code{unistd-safer}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
192 @tab @code{"unistd--.h"}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
193 @item @code{fopen()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
194 @tab @code{fopen-safer}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
195 @tab @code{"stdio--.h"}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
196 @item @code{freopen()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
197 @tab @code{freopen-safer}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
198 @tab @code{"stdio--.h"}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
199 @item @code{pipe()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
200 @tab @code{unistd-safer}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
201 @tab @code{"unistd--.h"}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
202 @item @code{pipe2()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
203 @tab @code{pipe2-safer}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
204 @tab @code{"unistd--.h"}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
205 @item @code{popen()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
206 @tab @code{popen-safer}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
207 @tab @code{"stdio--.h"}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
208 @item @code{opendir()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
209 @tab @code{dirent-safer}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
210 @tab @code{"dirent--.h"}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
211 @item @code{tmpfile()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
212 @tab @code{tmpfile-safer}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
213 @tab @code{"stdio--.h"}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
214 @item @code{mkstemp()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
215 @tab @code{stdlib-safer}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
216 @tab @code{"stdlib--.h"}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
217 @item @code{mkstemps()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
218 @tab @code{stdlib-safer}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
219 @tab @code{"stdlib--.h"}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
220 @item @code{mkostemp()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
221 @tab @code{stdlib-safer}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
222 @tab @code{"stdlib--.h"}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
223 @item @code{mkostemps()}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
224 @tab @code{stdlib-safer}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
225 @tab @code{"stdlib--.h"}
943155cd4a86 doc: Document the xstdopen and *-safer modules.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
226 @end multitable