Add Locking calls to file_io.h plus implementations and test

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,
@@ skipping 60 matching lines @@
 
 //! \brief Determines the permissions bits for files created on POSIX systems.
 enum class FilePermissions : bool {
   //! \brief Equivalent to `0600`.
   kOwnerOnly,
 
   //! \brief Equivalent to `0644`.
   kWorldReadable,
 };
 
+//! \brief Determines the locking mode that LoggingLockFile uses.
+enum class FileLocking : bool {
+  //! \brief Equivalent to `flock` with `LOCK_SH`.
+  kShared,
+
+  //! \brief Equivalent to `flock` with `LOCK_EX`.
+  kExclusive,
+};
+
 //! \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 84 matching lines @@
 //!
 //! \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, \a permissions determines the value that is passed
 //! as `mode` to `open()`. On Windows, the file is always opened in binary mode
-//! (that is, no CRLF translation).
+//! (that is, no CRLF translation). On Windows, the file is opened for sharing,

[Robert Sesek, 2015/03/12 15:28:03]

Are files normally exclusive on Windows? Do we want most files opened as
sharable if so?

[scottmg, 2015/03/19 22:06:19]

I don't think there's an expected default. I just made them exclusive to start
with so that it'd be clear when something required sharing.

+//! see LoggingLockFile() and LoggingUnlockFile() to control concurrent access.
 //!
 //! \return The newly opened FileHandle, or an invalid FileHandle on failure.
 //!
 //! \sa FileWriteMode
 //! \sa FilePermissions
 //! \sa ScopedFileHandle
 FileHandle LoggingOpenFileForWrite(const base::FilePath& path,
                                    FileWriteMode write_mode,
                                    FilePermissions permissions);
 
+//! \brief Locks the given \a file similar to `flock`.
+//!
+//! It is an error to attempt to lock a file in a different mode when it is
+//! already locked. This call will block until the lock is acquired.
+//!
+//! \param[in] file The open file handle to be locked.
+//! \param[in] locking Controls whether the lock is shared (generally for
+//!     multiple readers) or exclusive (generally for a single writer).
+//!
+//! \return `true` on success, or `false` and a message will be logged.
+bool LoggingLockFile(FileHandle file, FileLocking locking);
+
+//! \brief Unlocks a file previously locked with LoggingLockFile().
+//!
+//! It is an error to attempt to unlock a file that was not previously locked.
+//!
+//! \param[in] file The open locked file handle to be unlocked.
+//!
+//! \return `true` on success, or `false` and a message will be logged.
+bool LoggingUnlockFile(FileHandle file);
+
 //! \brief Wraps `lseek()` or `SetFilePointerEx()`. Logs an error if the
 //!     operation fails.
 //!
 //! Repositions the offset of the open \a file to the specified \a offset,
 //! relative to \a whence. \a whence must be one of `SEEK_SET`, `SEEK_CUR`, or
 //! `SEEK_END`, and is interpreted in the usual way.
 //!
 //! \return The resulting offset in bytes from the beginning of the file, or
 //!     `-1` on failure.
 FileOffset LoggingSeekFile(FileHandle file, FileOffset offset, int whence);
 
 //! \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_