Add LoggingOpenFileFor{Read|Write}

util/file/file_io.h

 // Copyright 2014 The Crashpad Authors. All rights reserved.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
 //
 //     http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS,
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
 #ifndef CRASHPAD_UTIL_FILE_FILE_IO_H_
 #define CRASHPAD_UTIL_FILE_FILE_IO_H_
 
 #include <sys/types.h>
 
 #include "build/build_config.h"
 
 #if defined(OS_WIN)
 #include <windows.h>
 #endif
 
+namespace base {
+class FilePath;
+}  // namespace base
+
 namespace crashpad {
 
-#if defined(OS_POSIX)
+#if defined(OS_POSIX) || DOXYGEN
+//! \brief Platform-specific alias for a low level file handle.
 using FileHandle = int;
 #elif defined(OS_WIN)
 using FileHandle = HANDLE;
 #endif
 
+//! \brief Determines the mode that LoggingOpenFileForWrite() uses.
+enum class FileWriteMode {
+  //! \brief Opens the file if it exists, or creates a new file.
+  kAppend,

[Mark Mentovai, 2014/12/18 21:52:32]

kAppend still sounds like it seeks to the end…

How about:

kReuseOrCreate
kTruncateOrCreate
kCreateOrFail

so that everything specifies a conceptual operation and its fallback.

I also realize that the one thing all three of these have in common is that they
can create, and I’m almost of the mind that we can name the enum FileCreateMode
and then have kReuse, kTruncate, and k…? It falls apart because there’s no great
name for the third one, and if you saw FileCreateMode::kReuse in code, you still
might erroneously think that it means “don’t create, just reuse.”

[scottmg, 2014/12/18 22:12:44]

"Reuse" sounds a bit funny to me, but I can't think of a better one.
kOpenOrCreate sort of works, but since it's for a function that is just doing
opens, doesn't clear things up.

Done as above.

+
+  //! \brief Creates a new file. If the file already exists, it will be
+  //!        overwritten.
+  kCreate,
+
+  //! \brief Creates a new file. If the file already exists, the open will fail.
+  kCreateNew,
+};
+
 //! \brief Reads from a file, retrying when interrupted on POSIX or following a
 //!        short read.
 //!
 //! This function reads into \a buffer, stopping only when \a size bytes have
 //! been read or when end-of-file has been reached. On Windows, reading from
 //! sockets is not currently supported.
 //!
 //! \return The number of bytes read and placed into \a buffer, or `-1` on
 //!     error, with `errno` or `GetLastError()` set appropriately. On error, a
 //!     portion of \a file may have been read into \a buffer.
@@ skipping 70 matching lines @@
 //! \brief Wraps ReadFile(), ensuring that it indicates end-of-file.
 //!
 //! Attempts to read a single byte from \a file, expecting no data to be read.
 //! If the underlying ReadFile() fails, or if a byte actually is read, this
 //! function causes execution to terminate without returning.
 //!
 //! \sa CheckedReadFile
 //! \sa ReadFile
 void CheckedReadFileAtEOF(FileHandle file);
 
+//! \brief Wraps `open()` or `CreateFile()`, creating a file for output. Logs
+//!        an error if the operation fails.
+//!
+//! \a write_mode determines the style (clobber, truncate, etc.) that is used

[Mark Mentovai, 2014/12/18 21:52:32]

clobber == truncate, right?

[scottmg, 2014/12/18 22:12:44]

Done.

+//! to open the file. On POSIX, if \a world_readable, `0644` will be used as
+//! `mode` permissions bits for `open()`, otherwise `0600` will be used. On

[Mark Mentovai, 2014/12/18 21:52:32]

Yup, score!

+//! Windows, the file is always opened in binary mode (that is, no CRLF
+//! translation).
+//!
+//! \return The newly opened FileHandle, or an invalid FileHandle on failure.
+//!
+//! \sa FileWriteMode
+//! \sa ScopedFD
+//! \sa ScopedFileHANDLE
+FileHandle LoggingOpenFileForWrite(const base::FilePath& path,
+                                   FileWriteMode write_mode,
+                                   bool world_readable);
+
+//! \brief Wraps `open()` or `CreateFile()`, opening an existing file for
+//!        reading. Logs an error if the operation fails.
+//!
+//! \return The newly opened FileHandle, or an invalid FileHandle on failure.
+//!
+//! \sa ScopedFD
+//! \sa ScopedFileHANDLE
+FileHandle LoggingOpenFileForRead(const base::FilePath& path);
+
 //! \brief Wraps `close()` or `CloseHandle()`, logging an error if the operation
 //!        fails.
 //!
 //! \return On success, `true` is returned. On failure, an error is logged and
 //!     `false` is returned.
 bool LoggingCloseFile(FileHandle file);
 
 //! \brief Wraps `close()` or `CloseHandle()`, ensuring that it succeeds.
 //!
 //! If the underlying function fails, this function causes execution to
 //! terminate without returning.
 void CheckedCloseFile(FileHandle file);
 
 }  // namespace crashpad
 
 #endif  // CRASHPAD_UTIL_FILE_FILE_IO_H_