2 * Copyright 2017 Facebook, Inc.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
20 #include <sys/types.h>
25 #include <folly/Portability.h>
26 #include <folly/Range.h>
27 #include <folly/ScopeGuard.h>
28 #include <folly/portability/Fcntl.h>
29 #include <folly/portability/SysUio.h>
30 #include <folly/portability/Unistd.h>
35 * Convenience wrappers around some commonly used system calls. The *NoInt
36 * wrappers retry on EINTR. The *Full wrappers retry on EINTR and also loop
37 * until all data is written. Note that *Full wrappers weaken the thread
38 * semantics of underlying system calls.
40 int openNoInt(const char* name, int flags, mode_t mode = 0666);
41 int closeNoInt(int fd);
43 int dup2NoInt(int oldfd, int newfd);
44 int fsyncNoInt(int fd);
45 int fdatasyncNoInt(int fd);
46 int ftruncateNoInt(int fd, off_t len);
47 int truncateNoInt(const char* path, off_t len);
48 int flockNoInt(int fd, int operation);
49 int shutdownNoInt(int fd, int how);
51 ssize_t readNoInt(int fd, void* buf, size_t n);
52 ssize_t preadNoInt(int fd, void* buf, size_t n, off_t offset);
53 ssize_t readvNoInt(int fd, const iovec* iov, int count);
55 ssize_t writeNoInt(int fd, const void* buf, size_t n);
56 ssize_t pwriteNoInt(int fd, const void* buf, size_t n, off_t offset);
57 ssize_t writevNoInt(int fd, const iovec* iov, int count);
60 * Wrapper around read() (and pread()) that, in addition to retrying on
61 * EINTR, will loop until all data is read.
63 * This wrapper is only useful for blocking file descriptors (for non-blocking
64 * file descriptors, you have to be prepared to deal with incomplete reads
65 * anyway), and only exists because POSIX allows read() to return an incomplete
66 * read if interrupted by a signal (instead of returning -1 and setting errno
69 * Note that this wrapper weakens the thread safety of read(): the file pointer
70 * is shared between threads, but the system call is atomic. If multiple
71 * threads are reading from a file at the same time, you don't know where your
72 * data came from in the file, but you do know that the returned bytes were
73 * contiguous. You can no longer make this assumption if using readFull().
74 * You should probably use pread() when reading from the same file descriptor
75 * from multiple threads simultaneously, anyway.
77 * Note that readvFull and preadvFull require iov to be non-const, unlike
78 * readv and preadv. The contents of iov after these functions return
81 ssize_t readFull(int fd, void* buf, size_t n);
82 ssize_t preadFull(int fd, void* buf, size_t n, off_t offset);
83 ssize_t readvFull(int fd, iovec* iov, int count);
84 ssize_t preadvFull(int fd, iovec* iov, int count, off_t offset);
87 * Similar to readFull and preadFull above, wrappers around write() and
88 * pwrite() that loop until all data is written.
90 * Generally, the write() / pwrite() system call may always write fewer bytes
91 * than requested, just like read(). In certain cases (such as when writing to
92 * a pipe), POSIX provides stronger guarantees, but not in the general case.
93 * For example, Linux (even on a 64-bit platform) won't write more than 2GB in
94 * one write() system call.
96 * Note that writevFull and pwritevFull require iov to be non-const, unlike
97 * writev and pwritev. The contents of iov after these functions return
100 * These functions return -1 on error, or the total number of bytes written
101 * (which is always the same as the number of requested bytes) on success.
103 ssize_t writeFull(int fd, const void* buf, size_t n);
104 ssize_t pwriteFull(int fd, const void* buf, size_t n, off_t offset);
105 ssize_t writevFull(int fd, iovec* iov, int count);
106 ssize_t pwritevFull(int fd, iovec* iov, int count, off_t offset);
109 * Read entire file (if num_bytes is defaulted) or no more than
110 * num_bytes (otherwise) into container *out. The container is assumed
111 * to be contiguous, with element size equal to 1, and offer size(),
112 * reserve(), and random access (e.g. std::vector<char>, std::string,
115 * Returns: true on success or false on failure. In the latter case
116 * errno will be set appropriately by the failing system primitive.
118 template <class Container>
122 size_t num_bytes = std::numeric_limits<size_t>::max()) {
123 static_assert(sizeof(out[0]) == 1,
124 "readFile: only containers with byte-sized elements accepted");
126 size_t soFar = 0; // amount of bytes successfully read
128 DCHECK(out.size() >= soFar); // resize better doesn't throw
134 if (fstat(fd, &buf) == -1) {
137 // Some files (notably under /proc and /sys on Linux) lie about
138 // their size, so treat the size advertised by fstat under advise
139 // but don't rely on it. In particular, if the size is zero, we
140 // should attempt to read stuff. If not zero, we'll attempt to read
142 constexpr size_t initialAlloc = 1024 * 4;
145 buf.st_size > 0 ? (size_t(buf.st_size) + 1) : initialAlloc, num_bytes));
147 while (soFar < out.size()) {
148 const auto actual = readFull(fd, &out[soFar], out.size() - soFar);
153 if (soFar < out.size()) {
157 // Ew, allocate more memory. Use exponential growth to avoid
158 // quadratic behavior. Cap size to num_bytes.
159 out.resize(std::min(out.size() * 3 / 2, num_bytes));
166 * Same as above, but takes in a file name instead of fd
168 template <class Container>
170 const char* file_name,
172 size_t num_bytes = std::numeric_limits<size_t>::max()) {
175 const auto fd = openNoInt(file_name, O_RDONLY);
181 // Ignore errors when closing the file
185 return readFile(fd, out, num_bytes);
189 * Writes container to file. The container is assumed to be
190 * contiguous, with element size equal to 1, and offering STL-like
191 * methods empty(), size(), and indexed access
192 * (e.g. std::vector<char>, std::string, fbstring, StringPiece).
194 * "flags" dictates the open flags to use. Default is to create file
195 * if it doesn't exist and truncate it.
197 * Returns: true on success or false on failure. In the latter case
198 * errno will be set appropriately by the failing system primitive.
200 * Note that this function may leave the file in a partially written state on
201 * failure. Use writeFileAtomic() if you want to ensure that the existing file
202 * state will be unchanged on error.
204 template <class Container>
205 bool writeFile(const Container& data,
206 const char* filename,
207 int flags = O_WRONLY | O_CREAT | O_TRUNC,
208 mode_t mode = 0666) {
209 static_assert(sizeof(data[0]) == 1,
210 "writeFile works with element size equal to 1");
211 int fd = open(filename, flags, mode);
215 bool ok = data.empty() ||
216 writeFull(fd, &data[0], data.size()) == static_cast<ssize_t>(data.size());
217 return closeNoInt(fd) == 0 && ok;
221 * Write file contents "atomically".
223 * This writes the data to a temporary file in the destination directory, and
224 * then renames it to the specified path. This guarantees that the specified
225 * file will be replaced the the specified contents on success, or will not be
226 * modified on failure.
228 * Note that on platforms that do not provide atomic filesystem rename
229 * functionality (e.g., Windows) this behavior may not be truly atomic.
231 void writeFileAtomic(
232 StringPiece filename,
235 mode_t permissions = 0644);
236 void writeFileAtomic(
237 StringPiece filename,
239 mode_t permissions = 0644);
240 void writeFileAtomic(
241 StringPiece filename,
243 mode_t permissions = 0644);
246 * A version of writeFileAtomic() that returns an errno value instead of
249 * Returns 0 on success or an errno value on error.
251 int writeFileAtomicNoThrow(
252 StringPiece filename,
255 mode_t permissions = 0644);