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.
+  kReuseOrCreate,
+
+  //! \brief Creates a new file. If the file already exists, it will be
+  //!     overwritten.
+  kTruncateOrCreate,
+
+  //! \brief Creates a new file. If the file already exists, the open will fail.
+  kCreateOrFail,
+};
+
 //! \brief Reads from a file, retrying when interrupted on POSIX or following a
-//!        short read.
+//!     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.
 //!
 //! \sa WriteFile
 //! \sa LoggingReadFile
 //! \sa CheckedReadFile
 //! \sa CheckedReadFileAtEOF
 ssize_t ReadFile(FileHandle file, void* buffer, size_t size);
 
 //! \brief Writes to a file, retrying when interrupted or following a short
-//!        write on POSIX.
+//!     write on POSIX.
 //!
 //! This function writes to \a file, stopping only when \a size bytes have been
 //! written.
 //!
 //! \return The number of bytes written from \a buffer, or `-1` on error, with
 //!     `errno` or `GetLastError()` set appropriately. On error, a portion of
 //!     \a buffer may have been written to \a file.
 //!
 //! \sa ReadFile
 //! \sa LoggingWriteFile
@@ skipping 51 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()`, 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 `open()` or `CreateFile()`, creating a file for output. Logs
+//!     an error if the operation fails.
+//!
+//! \a write_mode determines the style (truncate, reuse, etc.) that is used 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
+//! 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 `close()` or `CloseHandle()`, logging an error if the operation
-//!        fails.
+//!     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_