Cross platform low level file IO wrappers

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_FD_IO_H_
-#define CRASHPAD_UTIL_FILE_FD_IO_H_
+#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 crashpad {
 
-//! \brief Wraps `read()`, retrying when interrupted or following a short read.
+#if defined(OS_POSIX)
+using FileHandle = int;
+#elif defined(OS_WIN)
+using FileHandle = HANDLE;
+#endif
+
+//! \brief Reads a file, retrying when interrupted on POSIX.

[Mark Mentovai, 2014/12/16 22:40:25]

This comment used to mention short reads. It should at least continue to mention
them for POSIX. Same on line 49 for WriteFile().

[Mark Mentovai, 2014/12/16 22:40:25]

This comment is confusing, because it sounds like it reads the entire contents
of a file. Change it to “Reads from a file”?

Same on line 49 (“Writes to a file”).

[scottmg, 2014/12/17 00:22:58]

Done.

[scottmg, 2014/12/17 00:22:58]

Done.

 //!
 //! This function reads into \a buffer, stopping only when \a size bytes have
-//! been read or when `read()` returns 0, indicating that end-of-file has been
-//! reached.
+//! been read or when end-of-file has been reached.
 //!
 //! \return The number of bytes read and placed into \a buffer, or `-1` on
-//!     error, with `errno` set appropriately. On error, a portion of \a fd may
-//!     have been read into \a buffer.
+//!     error, with `errno` or `GetLastError` set appropriately. On error, a

[Mark Mentovai, 2014/12/16 22:40:25]

Sorry to be pedantic about silly things like this, but the Crashpad comment
style uses () on function names: `GetLastError()`. Same on line 55.

The Doxygen-generated docs show up at
http://docs.crashpad.googlecode.com/git/doxygen/index.html and it’s nice for
them to be consistent in style.

[scottmg, 2014/12/17 00:22:58]

Done.

+//!     portion of \a file may have been read into \a buffer.
 //!
-//! \sa WriteFD
-//! \sa LoggingReadFD
-//! \sa CheckedReadFD
-//! \sa CheckedReadFDAtEOF
-ssize_t ReadFD(int fd, void* buffer, size_t size);
+//! \sa WriteFile
+//! \sa LoggingReadFile
+//! \sa CheckedReadFile
+//! \sa CheckedReadFileAtEOF
+ssize_t ReadFile(FileHandle file, void* buffer, size_t size);
 
-//! \brief Wraps `write()`, retrying when interrupted or following a short
-//!     write.
+//! \brief Writes a file, retrying when interrupted on POSIX.
 //!
-//! This function writes to \a fd, stopping only when \a size bytes have been
+//! 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` set appropriately. On error, a portion of \a buffer may have
-//!     been written to \a fd.
+//!     `errno` or `GetLastError` set appropriately. On error, a portion of
+//!     \a buffer may have been written to \a file.
 //!
-//! \sa ReadFD
-//! \sa LoggingWriteFD
-//! \sa CheckedWriteFD
-ssize_t WriteFD(int fd, const void* buffer, size_t size);
+//! \sa ReadFile
+//! \sa LoggingWriteFile
+//! \sa CheckedWriteFile
+ssize_t WriteFile(FileHandle file, const void* buffer, size_t size);
 
-//! \brief Wraps ReadFD(), ensuring that exactly \a size bytes are read.
+//! \brief Wraps ReadFile(), ensuring that exactly \a size bytes are read.
 //!
 //! \return `true` on success. If \a size is out of the range of possible
-//!     `read()` return values, if the underlying ReadFD() fails, or if other
-//!     than \a size bytes were read, this function logs a message and returns
-//!     `false`.
+//!     `ReadFile` return values, if the underlying ReadFile() fails, or if
+//!     other than \a size bytes were read, this function logs a message and
+//!     returns `false`.
 //!
-//! \sa LoggingWriteFD
-//! \sa ReadFD
-//! \sa CheckedReadFD
-//! \sa CheckedReadFDAtEOF
-bool LoggingReadFD(int fd, void* buffer, size_t size);
+//! \sa LoggingWriteFile
+//! \sa ReadFile
+//! \sa CheckedReadFile
+//! \sa CheckedReadFileAtEOF
+bool LoggingReadFile(FileHandle file, void* buffer, size_t size);
 
-//! \brief Wraps WriteFD(), ensuring that exactly \a size bytes are written.
+//! \brief Wraps WriteFile(), ensuring that exactly \a size bytes are written.
 //!
 //! \return `true` on success. If \a size is out of the range of possible
-//!     `write()` return values, if the underlying WriteFD() fails, or if other
-//!     than \a size bytes were written, this function logs a message and
+//!     `WriteFile` return values, if the underlying WriteFile() fails, or if
+//!     other than \a size bytes were written, this function logs a message and
 //!     returns `false`.
 //!
-//! \sa LoggingReadFD
-//! \sa WriteFD
-//! \sa CheckedWriteFD
-bool LoggingWriteFD(int fd, const void* buffer, size_t size);
+//! \sa LoggingReadFile
+//! \sa WriteFile
+//! \sa CheckedWriteFile
+bool LoggingWriteFile(FileHandle file, const void* buffer, size_t size);
 
-//! \brief Wraps ReadFD(), ensuring that exactly \a size bytes are read.
+//! \brief Wraps ReadFile(), ensuring that exactly \a size bytes are read.
 //!
-//! If \a size is out of the range of possible `read()` return values, if the
-//! underlying ReadFD() fails, or if other than \a size bytes were read, this
+//! If \a size is out of the range of possible `ReadFile` return values, if the
+//! underlying ReadFile() fails, or if other than \a size bytes were read, this
 //! function causes execution to terminate without returning.
 //!
-//! \sa CheckedWriteFD
-//! \sa ReadFD
-//! \sa LoggingReadFD
-//! \sa CheckedReadFDAtEOF
-void CheckedReadFD(int fd, void* buffer, size_t size);
+//! \sa CheckedWriteFile
+//! \sa ReadFile
+//! \sa LoggingReadFile
+//! \sa CheckedReadFileAtEOF
+void CheckedReadFile(FileHandle file, void* buffer, size_t size);
 
-//! \brief Wraps WriteFD(), ensuring that exactly \a size bytes are written.
+//! \brief Wraps WriteFile(), ensuring that exactly \a size bytes are written.
 //!
-//! If \a size is out of the range of possible `write()` return values, if the
-//! underlying WriteFD() fails, or if other than \a size bytes were written,
+//! If \a size is out of the range of possible `WriteFile` return values, if the
+//! underlying WriteFile() fails, or if other than \a size bytes were written,
 //! this function causes execution to terminate without returning.
 //!
-//! \sa CheckedReadFD
-//! \sa WriteFD
-//! \sa LoggingWriteFD
-void CheckedWriteFD(int fd, const void* buffer, size_t size);
+//! \sa CheckedReadFile
+//! \sa WriteFile
+//! \sa LoggingWriteFile
+void CheckedWriteFile(FileHandle file, const void* buffer, size_t size);
 
-//! \brief Wraps ReadFD(), ensuring that it indicates end-of-file.
+//! \brief Wraps ReadFile(), ensuring that it indicates end-of-file.
 //!
-//! Attempts to read a single byte from \a fd, expecting no data to be read. If
-//! the underlying ReadFD() fails, or if a byte actually is read, this function
-//! causes execution to terminate without returning.
+//! 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 CheckedReadFD
-//! \sa ReadFD
-void CheckedReadFDAtEOF(int fd);
+//! \sa CheckedReadFile
+//! \sa ReadFile
+void CheckedReadFileAtEOF(FileHandle file);
 
 //! \brief Wraps `close()`, logging an error if the operation fails.
 //!
 //! \return On success, `true` is returned. On failure, an error is logged and
 //!     `false` is returned.
-bool LoggingCloseFD(int fd);
+bool LoggingCloseFile(FileHandle file);
 
 //! \brief Wraps `close()`, ensuring that it succeeds.
 //!
 //! If `close()` fails, this function causes execution to terminate without
 //! returning.
-void CheckedCloseFD(int fd);
+void CheckedCloseFile(FileHandle file);
 
 }  // namespace crashpad
 
-#endif  // CRASHPAD_UTIL_FILE_FD_IO_H_
+#endif  // CRASHPAD_UTIL_FILE_FILE_IO_H_