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 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 `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
+//!     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 to a file, retrying when interrupted or following a short
+//!        write 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

[Mark Mentovai, 2014/12/17 01:05:24]

ReadFile(), not `ReadFile`. Same on lines 81, 92, 104.

The guideline with the documentation is to use `backticks` for things outside of
Crashpad, because Doxygen can’t generate docs for those, and they wouldn’t
otherwise be set off in the generated docs. For things inside Crashpad, the docs
will automatically link correctly, so we don’t also need backticks to force a
monospaced display.

[scottmg, 2014/12/17 01:50:27]

Ah, I see. Done.

+//!     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.

[Mark Mentovai, 2014/12/17 01:05:24]

“`close()` or `CloseHandle()`”? Line 129 too, and maybe clean up line 131 by
just saying “the underlying function.”

[scottmg, 2014/12/17 01:50:27]

Done.

 //!
 //! \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_