diff --git a/client/crashpad_client.h b/client/crashpad_client.h index 693557e0..844512f1 100644 --- a/client/crashpad_client.h +++ b/client/crashpad_client.h @@ -44,11 +44,11 @@ class CrashpadClient { //! \brief Starts a Crashpad handler process, performing any necessary //! handshake to configure it. //! - //! This method directs crashes to the Crashpad handler. On Mac OS X, this - //! is applicable to this process and all child processes. On Windows, child - //! processes must also register by using SetHandlerIPCPipe(). + //! This method directs crashes to the Crashpad handler. On macOS, this is + //! applicable to this process and all subsequent child processes. On Windows, + //! child processes must also register by using SetHandlerIPCPipe(). //! - //! On Mac OS X, this method starts a Crashpad handler and obtains a Mach send + //! On macOS, this method starts a Crashpad handler and obtains a Mach send //! right corresponding to a receive right held by the handler process. The //! handler process runs an exception server on this port. This method sets //! the task’s exception port for `EXC_CRASH`, `EXC_RESOURCE`, and `EXC_GUARD` @@ -56,8 +56,8 @@ class CrashpadClient { //! with behavior `EXCEPTION_STATE_IDENTITY | MACH_EXCEPTION_CODES` and thread //! state flavor `MACHINE_THREAD_STATE`. Exception ports are inherited, so a //! Crashpad handler started here will remain the handler for any child - //! processes created after StartHandler() is called. Child processes do not - //! need to call StartHandler() or be aware of Crashpad in any way. The + //! processes created after StartHandler() is called. These child processes do + //! not need to call StartHandler() or be aware of Crashpad in any way. The //! Crashpad handler will receive crashes from child processes that have //! inherited it as their exception handler even after the process that called //! StartHandler() exits. @@ -109,7 +109,7 @@ class CrashpadClient { //! \brief Sets the process’ crash handler to a Mach service registered with //! the bootstrap server. //! - //! This method is only defined on OS X. + //! This method is only defined on macOS. //! //! See StartHandler() for more detail on how the port and handler are //! configured. @@ -122,7 +122,7 @@ class CrashpadClient { //! \brief Sets the process’ crash handler to a Mach port. //! - //! This method is only defined on OS X. + //! This method is only defined on macOS. //! //! See StartHandler() for more detail on how the port and handler are //! configured. @@ -234,7 +234,7 @@ class CrashpadClient { //! \brief Configures the process to direct its crashes to the default handler //! for the operating system. //! - //! On OS X, this sets the task’s exception port as in SetHandlerMachPort(), + //! On macOS, this sets the task’s exception port as in SetHandlerMachPort(), //! but the exception handler used is obtained from //! SystemCrashReporterHandler(). If the system’s crash reporter handler //! cannot be determined or set, the task’s exception ports for crash-type diff --git a/client/crashpad_info.h b/client/crashpad_info.h index 9e7abfc1..0462eaf9 100644 --- a/client/crashpad_info.h +++ b/client/crashpad_info.h @@ -164,9 +164,9 @@ struct CrashpadInfo { //! \brief Adds a custom stream to the minidump. //! //! The memory block referenced by \a data and \a size will added to the - //! minidump as separate stream with type \stream_type. The memory referred to - //! by \a data and \a size is owned by the caller and must remain valid while - //! it is in effect for the CrashpadInfo object. + //! minidump as separate stream with type \a stream_type. The memory referred + //! to by \a data and \a size is owned by the caller and must remain valid + //! while it is in effect for the CrashpadInfo object. //! //! Note that streams will appear in the minidump in the reverse order to //! which they are added. diff --git a/client/prune_crash_reports.h b/client/prune_crash_reports.h index b66e9349..6dac5f30 100644 --- a/client/prune_crash_reports.h +++ b/client/prune_crash_reports.h @@ -111,7 +111,7 @@ class DatabaseSizePruneCondition final : public PruneCondition { DISALLOW_COPY_AND_ASSIGN(DatabaseSizePruneCondition); }; -//! \breif A PruneCondition that conjoins two other PruneConditions. +//! \brief A PruneCondition that conjoins two other PruneConditions. class BinaryPruneCondition final : public PruneCondition { public: enum Operator { diff --git a/compat/mac/mach-o/getsect.cc b/compat/mac/mach-o/getsect.cc index 71d3066c..6cda9ffe 100644 --- a/compat/mac/mach-o/getsect.cc +++ b/compat/mac/mach-o/getsect.cc @@ -72,11 +72,11 @@ using GetSegmentDataType = extern "C" { -// These implementations look up their functions in libmacho at run time. If -// the system libmacho provides these functions as it normally does on Mac OS X -// 10.7 and later, the system’s versions are used directly. Otherwise, the -// versions in third_party/apple_cctools are used, which are actually just -// copies of the system’s functions. +// These implementations look up their functions in libmacho at run time. If the +// system libmacho provides these functions as it normally does on OS X 10.7 and +// later, the system’s versions are used directly. Otherwise, the versions in +// third_party/apple_cctools are used, which are actually just copies of the +// system’s functions. uint8_t* getsectiondata(const MachHeader* mhp, const char* segname, diff --git a/compat/non_win/dbghelp.h b/compat/non_win/dbghelp.h index 71ef1f4c..78ec2952 100644 --- a/compat/non_win/dbghelp.h +++ b/compat/non_win/dbghelp.h @@ -279,21 +279,21 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_SYSTEM_INFO { //! component. //! //! - For Windows 7 (NT 6.1) SP1, version 6.1.7601, this would be `6`. - //! - For Mac OS X 10.9.2, this would be `10`. + //! - For macOS 10.12.1, this would be `10`. uint32_t MajorVersion; //! \brief The system’s operating system version number’s second (minor) //! component. //! //! - For Windows 7 (NT 6.1) SP1, version 6.1.7601, this would be `1`. - //! - For Mac OS X 10.9.2, this would be `9`. + //! - For macOS 10.12.1, this would be `12`. uint32_t MinorVersion; //! \brief The system’s operating system version number’s third (build or //! patch) component. //! //! - For Windows 7 (NT 6.1) SP1, version 6.1.7601, this would be `7601`. - //! - For Mac OS X 10.9.2, this would be `2`. + //! - For macOS 10.12.1, this would be `1`. uint32_t BuildNumber; //! \brief The system’s operating system family. This may be a \ref @@ -311,9 +311,9 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_SYSTEM_INFO { //! - On Windows, this is the name of the installed operating system service //! pack, such as “Service Pack 1”. If no service pack is installed, this //! field references an empty string. - //! - On Mac OS X, this is the operating system build number from `sw_vers - //! -buildVersion`. For Mac OS X 10.9.2 on most hardware types, this would - //! be `13C64`. + //! - On macOS, this is the operating system build number from `sw_vers + //! -buildVersion`. For macOS 10.12.1 on most hardware types, this would + //! be `16B2657`. //! - On Linux and other Unix-like systems, this is the kernel version from //! `uname -srvm`, possibly with additional information appended. On //! Android, the `ro.build.fingerprint` system property is appended. @@ -417,17 +417,17 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_EXCEPTION { //! \brief The top-level exception code identifying the exception, in //! operating system-specific values. //! - //! For Mac OS X minidumps, this will be an \ref EXC_x "EXC_*" exception type, + //! For macOS minidumps, this will be an \ref EXC_x "EXC_*" exception type, //! such as `EXC_BAD_ACCESS`. `EXC_CRASH` will not appear here for exceptions //! processed as `EXC_CRASH` when generated from another preceding exception: //! the original exception code will appear instead. The exception type as it //! was received will appear at index 0 of #ExceptionInformation. //! - //! For Windows minidumps, this will be an \ref EXCEPTION_x "EXCEPTION_*" - //! exception type, such as `EXCEPTION_ACCESS_VIOLATION`. + //! For Windows minidumps, this will be an `EXCEPTION_*` exception type, such + //! as `EXCEPTION_ACCESS_VIOLATION`. //! //! \note This field is named ExceptionCode, but what is known as the - //! “exception code” on Mac OS X/Mach is actually stored in the + //! “exception code” on macOS/Mach is actually stored in the //! #ExceptionFlags field of a minidump file. //! //! \todo Document the possible values by OS. There may be OS-specific enums @@ -437,16 +437,16 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_EXCEPTION { //! \brief Additional exception flags that further identify the exception, in //! operating system-specific values. //! - //! For Mac OS X minidumps, this will be the value of the exception code at - //! index 0 as received by a Mach exception handler, except: + //! For macOS minidumps, this will be the value of the exception code at index + //! 0 as received by a Mach exception handler, except: //! * For exception type `EXC_CRASH` generated from another preceding //! exception, the original exception code will appear here, not the code //! as received by the Mach exception handler. //! * For exception types `EXC_RESOURCE` and `EXC_GUARD`, the high 32 bits of //! the code received by the Mach exception handler will appear here. //! - //! In all cases for Mac OS X minidumps, the code as it was received by the - //! Mach exception handler will appear at index 1 of #ExceptionInformation. + //! In all cases for macOS minidumps, the code as it was received by the Mach + //! exception handler will appear at index 1 of #ExceptionInformation. //! //! For Windows minidumps, this will either be `0` if the exception is //! continuable, or `EXCEPTION_NONCONTINUABLE` to indicate a noncontinuable @@ -475,12 +475,12 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_EXCEPTION { //! \brief Additional information about the exception, specific to the //! operating system and possibly the #ExceptionCode. //! - //! For Mac OS X minidumps, this will contain the exception type as received - //! by a Mach exception handler and the values of the `codes[0]` and - //! `codes[1]` (exception code and subcode) parameters supplied to the Mach - //! exception handler. Unlike #ExceptionCode and #ExceptionFlags, the values - //! received by a Mach exception handler are used directly here even for the - //! `EXC_CRASH`, `EXC_RESOURCE`, and `EXC_GUARD` exception types. + //! For macOS minidumps, this will contain the exception type as received by a + //! Mach exception handler and the values of the `codes[0]` and `codes[1]` + //! (exception code and subcode) parameters supplied to the Mach exception + //! handler. Unlike #ExceptionCode and #ExceptionFlags, the values received by + //! a Mach exception handler are used directly here even for the `EXC_CRASH`, + //! `EXC_RESOURCE`, and `EXC_GUARD` exception types. //! For Windows, these are additional arguments (if any) as provided to //! `RaiseException()`. @@ -982,8 +982,9 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_MEMORY_INFO { //! \brief The memory protection when the region was initially allocated. This //! member can be one of the memory protection options (such as - //! \ref PAGE_x PAGE_EXECUTE, \ref PAGE_x PAGE_NOACCESS, etc.), along with - //! \ref PAGE_x PAGE_GUARD or \ref PAGE_x PAGE_NOCACHE, as needed. + //! \ref PAGE_x "PAGE_EXECUTE", \ref PAGE_x "PAGE_NOACCESS", etc.), along + //! with \ref PAGE_x "PAGE_GUARD" or \ref PAGE_x "PAGE_NOCACHE", as + //! needed. uint32_t AllocationProtect; uint32_t __alignment1; @@ -993,7 +994,8 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_MEMORY_INFO { uint64_t RegionSize; //! \brief The state of the pages in the region. This can be one of - //! \ref MEM_x MEM_COMMIT, \ref MEM_x MEM_FREE, or \ref MEM_x MEM_RESERVE. + //! \ref MEM_x "MEM_COMMIT", \ref MEM_x "MEM_FREE", or \ref MEM_x + //! "MEM_RESERVE". uint32_t State; //! \brief The access protection of the pages in the region. This member is @@ -1001,7 +1003,7 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_MEMORY_INFO { uint32_t Protect; //! \brief The type of pages in the region. This can be one of \ref MEM_x - //! MEM_IMAGE, \ref MEM_x MEM_MAPPED, or \ref MEM_x MEM_PRIVATE. + //! "MEM_IMAGE", \ref MEM_x "MEM_MAPPED", or \ref MEM_x "MEM_PRIVATE". uint32_t Type; uint32_t __alignment2; diff --git a/doc/appengine/README b/doc/appengine/README index b92e311b..9434ba09 100644 --- a/doc/appengine/README +++ b/doc/appengine/README @@ -28,7 +28,7 @@ To deploy: $ version=$(git rev-parse --short=12 HEAD) $ [[ -n "$(git status --porcelain)" ]] && version+=-dirty -$ goapp deploy -version "${version}" +$ …/go_appengine/goapp deploy -version "${version}" Note that app.yaml does not name a “version” to encourage you to use a git hash as the version, as above. diff --git a/doc/support/crashpad.doxy b/doc/support/crashpad.doxy index 0d216454..198b7176 100644 --- a/doc/support/crashpad.doxy +++ b/doc/support/crashpad.doxy @@ -162,7 +162,7 @@ STRIP_FROM_PATH = # using the -I flag. STRIP_FROM_INC_PATH = . \ - compat/mac \ + compat/non_mac \ compat/non_win # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but @@ -716,7 +716,7 @@ CITE_BIB_FILES = # messages are off. # The default value is: NO. -QUIET = NO +QUIET = YES # The WARNINGS tag can be used to turn on/off the warning messages that are # generated to standard error (stderr) by doxygen. If WARNINGS is set to YES @@ -732,7 +732,7 @@ WARNINGS = YES # will automatically be disabled. # The default value is: YES. -WARN_IF_UNDOCUMENTED = YES +WARN_IF_UNDOCUMENTED = NO # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for # potential errors in the documentation, such as not documenting some parameters @@ -826,7 +826,10 @@ RECURSIVE = YES # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = third_party +EXCLUDE = compat/mac \ + compat/non_cxx11_lib \ + compat/win \ + third_party # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -1126,7 +1129,7 @@ HTML_STYLESHEET = # list). For an example see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = +HTML_EXTRA_STYLESHEET = doc/support/crashpad_doxygen.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note diff --git a/doc/support/crashpad.doxy.h b/doc/support/crashpad.doxy.h index 5bfefedd..ae328d30 100644 --- a/doc/support/crashpad.doxy.h +++ b/doc/support/crashpad.doxy.h @@ -22,3 +22,13 @@ //! \namespace crashpad::test //! \brief The testing namespace, for use in test code only. + +//! \mainpage Crashpad Interface Documentation +//! +//! Most generated interface documentation is reachable through Namespaces, Classes +//! (includes `struct`s, `union`s, and interfaces), or Files (includes macros). +//! +//! Additional documentation is available at the Crashpad home page. diff --git a/doc/support/crashpad_doxygen.css b/doc/support/crashpad_doxygen.css new file mode 100644 index 00000000..f21cfe90 --- /dev/null +++ b/doc/support/crashpad_doxygen.css @@ -0,0 +1,60 @@ +/* Copyright 2016 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. */ + +@import "https://fonts.googleapis.com/css?family=Open+Sans:300,400,700&subset=latin,cyrillic-ext,greek-ext,cyrillic,greek,vietnamese,latin-ext"; +@import "https://fonts.googleapis.com/css?family=Source+Code+Pro"; + +body, +table, +div, +p, +dl, +.title, +.icon, +table.directory, +.navpath li.navelem a, +#projectname, +#projectbrief, +#projectnumber, +div.toc li, +div.toc h3, +#powerTip div, +.sm-dox a, +.sm-dox a:focus, +.sm-dox a:hover, +.sm-dox a:active { + font-family: 'Open Sans', + 'Lucida Grande', + 'Lucida Sans Unicode', + Helvetica, + Arial, + sans-serif; +} + +code, +tt, +pre.fragment, +div.line, +.overload, +.params .paramdir, +.sm-dox a span.sub-arrow { + font-family: 'Source Code Pro', + Monaco, + 'Lucida Console', + monospace; +} + +.icon { + height: auto; +} diff --git a/doc/support/generate.sh b/doc/support/generate.sh index aa3d7035..1e5bc92f 100755 --- a/doc/support/generate.sh +++ b/doc/support/generate.sh @@ -37,10 +37,5 @@ maybe_mkdir "${output_dir}/doxygen" rsync -Ilr --delete --exclude .git "out/doc/doxygen/html/" \ "${output_dir}/doxygen" -# Remove old things that used to be present -rm -rf "${output_dir}/doc" -rm -rf "${output_dir}/man" -rm -f "${output_dir}/index.html" - # Ensure a favicon exists at the root since the browser will always request it. cp doc/favicon.ico "${output_dir}/" diff --git a/minidump/minidump_extensions.h b/minidump/minidump_extensions.h index 68fa6e04..00ac6e88 100644 --- a/minidump/minidump_extensions.h +++ b/minidump/minidump_extensions.h @@ -209,7 +209,7 @@ enum MinidumpOS : uint32_t { kMinidumpOSUnix = 0x8000, - //! \brief Mac OS X, Darwin for traditional systems. + //! \brief macOS, Darwin for traditional systems. kMinidumpOSMacOSX = 0x8101, //! \brief iOS, Darwin for mobile devices. @@ -276,7 +276,7 @@ struct ALIGNAS(4) PACKED MinidumpSimpleStringDictionary { //! #version, so that newer parsers will be able to determine whether the added //! fields are valid or not. //! -//! \sa #MinidumpModuleCrashpadInfoList +//! \sa MinidumpModuleCrashpadInfoList struct ALIGNAS(4) PACKED MinidumpModuleCrashpadInfo { //! \brief The structure’s currently-defined version number. //! @@ -423,7 +423,7 @@ struct ALIGNAS(4) PACKED MinidumpCrashpadInfo { //! This field is present when #version is at least `1`. MINIDUMP_LOCATION_DESCRIPTOR simple_annotations; - //! \brief A pointer to a #MinidumpModuleCrashpadInfoList structure. + //! \brief A pointer to a MinidumpModuleCrashpadInfoList structure. //! //! This field is present when #version is at least `1`. MINIDUMP_LOCATION_DESCRIPTOR module_list; diff --git a/minidump/minidump_misc_info_writer.cc b/minidump/minidump_misc_info_writer.cc index e880aa7f..5f88c50c 100644 --- a/minidump/minidump_misc_info_writer.cc +++ b/minidump/minidump_misc_info_writer.cc @@ -68,8 +68,8 @@ std::string BuildString(const SystemSnapshot* system_snapshot) { #if defined(OS_MACOSX) // Converts the value of the MAC_OS_VERSION_MIN_REQUIRED or // MAC_OS_X_VERSION_MAX_ALLOWED macro from to a number -// identifying the minor Mac OS X version that it represents. For example, with -// an argument of MAC_OS_X_VERSION_10_6, this function will return 6. +// identifying the minor macOS version that it represents. For example, with an +// argument of MAC_OS_X_VERSION_10_6, this function will return 6. int AvailabilityVersionToMacOSXMinorVersion(int availability) { // Through MAC_OS_X_VERSION_10_9, the minor version is the tens digit. if (availability >= 1000 && availability <= 1099) { diff --git a/minidump/minidump_module_crashpad_info_writer.h b/minidump/minidump_module_crashpad_info_writer.h index ab77447b..d79ac2f4 100644 --- a/minidump/minidump_module_crashpad_info_writer.h +++ b/minidump/minidump_module_crashpad_info_writer.h @@ -125,11 +125,12 @@ class MinidumpModuleCrashpadInfoListWriter final //! \brief Adds a MinidumpModuleCrashpadInfo to the //! MinidumpModuleCrashpadInfoList. //! - //! \param[in] module Extended Crashpad-specific information about the module. - //! This object takes ownership of \a module and becomes its parent in the - //! overall tree of internal::MinidumpWritable objects. - //! \param[in] module_list_index The index of the MINIDUMP_MODULE in the - //! minidump file’s MINIDUMP_MODULE_LIST stream that corresponds to \a + //! \param[in] module_crashpad_info Extended Crashpad-specific information + //! about the module. This object takes ownership of \a + //! module_crashpad_info and becomes its parent in the overall tree of + //! internal::MinidumpWritable objects. + //! \param[in] minidump_module_list_index The index of the MINIDUMP_MODULE in + //! the minidump file’s MINIDUMP_MODULE_LIST stream that corresponds to \a //! module_crashpad_info. //! //! \note Valid in #kStateMutable. diff --git a/navbar.md b/navbar.md index 8eb7e1c4..d530414f 100644 --- a/navbar.md +++ b/navbar.md @@ -19,7 +19,6 @@ limitations under the License. * [Home][home] * [Developing](/doc/developing.md) * [Interface Docs](https://crashpad.chromium.org/doxygen/) - * [Man Pages](https://crashpad.chromium.org/man/) * [Man Pages](/doc/man.md) * [Source Code](https://chromium.googlesource.com/crashpad/crashpad/) diff --git a/snapshot/capture_memory.h b/snapshot/capture_memory.h index ef5f4ed9..d6a3a6df 100644 --- a/snapshot/capture_memory.h +++ b/snapshot/capture_memory.h @@ -71,8 +71,8 @@ class CaptureMemory { //! unsigned) so that there's a reasonable chance that the value is a pointer. //! //! \param[in] context The context to inspect. - //! \param[in] process_reader A MemoryCaptureProcessReader to read from the - //! target process, and that handles adding new ranges. + //! \param[in] delegate A Delegate that handles reading from the target + //! process and adding new ranges. static void PointedToByContext(const CPUContext& context, Delegate* delegate); //! \brief For all pointer-like values in a memory range of the target @@ -83,8 +83,8 @@ class CaptureMemory { //! base address and size must be pointer-aligned and an integral number //! of //! pointers long. - //! \param[in] process_reader A MemoryCaptureProcessReader to read from the - //! target process, and that handles adding new ranges. + //! \param[in] delegate A Delegate that handles reading from the target + //! process and adding new ranges. static void PointedToByMemoryRange(const MemorySnapshot& memory, Delegate* delegate); diff --git a/snapshot/cpu_context.h b/snapshot/cpu_context.h index bfef4d09..67b298e8 100644 --- a/snapshot/cpu_context.h +++ b/snapshot/cpu_context.h @@ -133,7 +133,7 @@ struct CPUContextX86_64 { uint16_t fop; // FPU opcode union { // The expression of these union members is determined by the use of - // fxsave/fxrstor or fxsave64/fxrstor64 (fxsaveq/fxrstorq). Mac OS X and + // fxsave/fxrstor or fxsave64/fxrstor64 (fxsaveq/fxrstorq). macOS and // Windows systems use the traditional fxsave/fxrstor structure. struct { // fxsave/fxrstor diff --git a/snapshot/exception_snapshot.h b/snapshot/exception_snapshot.h index eef9f47a..11a94153 100644 --- a/snapshot/exception_snapshot.h +++ b/snapshot/exception_snapshot.h @@ -50,21 +50,21 @@ class ExceptionSnapshot { //! //! This is an operating system-specific value. //! - //! For Mac OS X, this will be an \ref EXC_x "EXC_*" exception type, such as + //! For macOS, this will be an \ref EXC_x "EXC_*" exception type, such as //! `EXC_BAD_ACCESS`. `EXC_CRASH` will not appear here for exceptions //! processed as `EXC_CRASH` when generated from another preceding exception: //! the original exception code will appear instead. The exception type as it //! was received will appear at index 0 of Codes(). //! - //! For Windows, this will be an \ref EXCEPTION_x "EXCEPTION_*" exception type - //! such as `EXCEPTION_ACCESS_VIOLATION`. + //! For Windows, this will be an `EXCEPTION_*` exception type, such as + //! `EXCEPTION_ACCESS_VIOLATION`. virtual uint32_t Exception() const = 0; //! \brief Returns the second-level exception code identifying the exception. //! //! This is an operating system-specific value. //! - //! For Mac OS X, this will be the value of the exception code at index 0 as + //! For macOS, this will be the value of the exception code at index 0 as //! received by a Mach exception handler, except: //! * For `EXC_CRASH` exceptions generated from another preceding exception, //! the original exception code will appear here, not the code as received @@ -72,7 +72,7 @@ class ExceptionSnapshot { //! * For `EXC_RESOURCE` and `EXC_GUARD` exceptions, the high 32 bits of the //! exception code at index 0 will appear here. //! - //! In all cases on Mac OS X, the full exception code at index 0 as it was + //! In all cases on macOS, the full exception code at index 0 as it was //! received will appear at index 1 of Codes(). //! //! On Windows, this will either be `0` if the exception is continuable, or @@ -85,7 +85,7 @@ class ExceptionSnapshot { //! the instruction pointer that contained an offending instruction. For //! exceptions where this value cannot be determined, it will be `0`. //! - //! For Mac OS X, this will be the value of the exception code at index 1 as + //! For macOS, this will be the value of the exception code at index 1 as //! received by a Mach exception handler. virtual uint64_t ExceptionAddress() const = 0; @@ -97,7 +97,7 @@ class ExceptionSnapshot { //! they may not be present at all. In this case, an empty vector will be //! returned. //! - //! For Mac OS X, this will be a vector containing the original exception type + //! For macOS, this will be a vector containing the original exception type //! and the values of `code[0]` and `code[1]` as received by a Mach exception //! handler. //! diff --git a/snapshot/mac/cpu_context_mac.h b/snapshot/mac/cpu_context_mac.h index 1d016cf5..c96ad3c4 100644 --- a/snapshot/mac/cpu_context_mac.h +++ b/snapshot/mac/cpu_context_mac.h @@ -27,7 +27,7 @@ namespace internal { #if defined(ARCH_CPU_X86_FAMILY) || DOXYGEN //! \brief Initializes a CPUContextX86 structure from native context structures -//! on Mac OS X. +//! on macOS. //! //! \a flavor, \a state, and \a state_count may be supplied by exception //! handlers in order for the \a context parameter to be initialized by the @@ -68,7 +68,7 @@ void InitializeCPUContextX86(CPUContextX86* context, const x86_debug_state32_t* x86_debug_state32); //! \brief Initializes a CPUContextX86_64 structure from native context -//! structures on Mac OS X. +//! structures on macOS. //! //! \a flavor, \a state, and \a state_count may be supplied by exception //! handlers in order for the \a context parameter to be initialized by the diff --git a/snapshot/mac/exception_snapshot_mac.h b/snapshot/mac/exception_snapshot_mac.h index 17720728..9a6ddcaa 100644 --- a/snapshot/mac/exception_snapshot_mac.h +++ b/snapshot/mac/exception_snapshot_mac.h @@ -34,7 +34,7 @@ class ProcessReader; namespace internal { //! \brief An ExceptionSnapshot of an exception sustained by a running (or -//! crashed) process on a Mac OS X system. +//! crashed) process on a macOS system. class ExceptionSnapshotMac final : public ExceptionSnapshot { public: ExceptionSnapshotMac(); @@ -47,6 +47,14 @@ class ExceptionSnapshotMac final : public ExceptionSnapshot { //! //! \param[in] process_reader A ProcessReader for the task that sustained the //! exception. + //! \param[in] behavior + //! \param[in] exception_thread + //! \param[in] exception + //! \param[in] code + //! \param[in] code_count + //! \param[in,out] flavor + //! \param[in] state + //! \param[in] state_count //! //! \return `true` if the snapshot could be created, `false` otherwise with //! an appropriate message logged. diff --git a/snapshot/mac/mach_o_image_annotations_reader_test.cc b/snapshot/mac/mach_o_image_annotations_reader_test.cc index d25ba438..f4f53494 100644 --- a/snapshot/mac/mach_o_image_annotations_reader_test.cc +++ b/snapshot/mac/mach_o_image_annotations_reader_test.cc @@ -199,8 +199,8 @@ class TestMachOImageAnnotationsReader final for (const std::string& annotation : all_annotations_vector) { // Look for the expectation as a leading susbtring, because the actual // string that dyld uses will have the contents of the - // DYLD_INSERT_LIBRARIES environment variable appended to it on Mac - // OS X 10.10. + // DYLD_INSERT_LIBRARIES environment variable appended to it on OS X + // 10.10. if (annotation.substr(0, expected_annotation.length()) == expected_annotation) { found = true; @@ -217,8 +217,8 @@ class TestMachOImageAnnotationsReader final bool found = false; for (const std::string& annotation : all_annotations_vector) { // Look for the expectation as a leading substring, because the actual - // string will contain the library’s pathname and, on Mac OS X 10.9 - // and later, a reason. + // string will contain the library’s pathname and, on OS X 10.9 and + // later, a reason. if (annotation.substr(0, expected_annotation_length) == kExpectedAnnotation) { found = true; diff --git a/snapshot/mac/memory_snapshot_mac.h b/snapshot/mac/memory_snapshot_mac.h index dbb02ee7..bbc39de3 100644 --- a/snapshot/mac/memory_snapshot_mac.h +++ b/snapshot/mac/memory_snapshot_mac.h @@ -27,7 +27,7 @@ namespace crashpad { namespace internal { //! \brief A MemorySnapshot of a memory region in a process on the running -//! system, when the system runs Mac OS X. +//! system, when the system runs macOS. class MemorySnapshotMac final : public MemorySnapshot { public: MemorySnapshotMac(); diff --git a/snapshot/mac/process_reader.h b/snapshot/mac/process_reader.h index 57d02641..c3696110 100644 --- a/snapshot/mac/process_reader.h +++ b/snapshot/mac/process_reader.h @@ -191,18 +191,18 @@ class ProcessReader { //! tag value. If these conditions cannot be met fully, as much of the red //! zone will be captured as is possible while meeting these conditions. //! - //! \param[inout] start_address The base address of the region to begin + //! \param[in,out] start_address The base address of the region to begin //! capturing stack memory from. On entry, \a start_address is the stack //! pointer. On return, \a start_address may be decreased to encompass a //! red zone. - //! \param[inout] region_base The base address of the region that contains + //! \param[in,out] region_base The base address of the region that contains //! stack memory. This is distinct from \a start_address in that \a //! region_base will be page-aligned. On entry, \a region_base is the //! base address of a region that contains \a start_address. On return, //! if \a start_address is decremented and is outside of the region //! originally described by \a region_base, \a region_base will also be //! decremented appropriately. - //! \param[inout] region_size The size of the region that contains stack + //! \param[in,out] region_size The size of the region that contains stack //! memory. This region begins at \a region_base. On return, if \a //! region_base is decremented, \a region_size will be incremented //! appropriately. diff --git a/snapshot/mac/process_reader_test.cc b/snapshot/mac/process_reader_test.cc index ed717b65..e679d2ef 100644 --- a/snapshot/mac/process_reader_test.cc +++ b/snapshot/mac/process_reader_test.cc @@ -587,7 +587,7 @@ class ScopedOpenCLNoOpKernel { ASSERT_EQ(CL_SUCCESS, rv) << "clCreateContext"; // The goal of the program in |sources| is to produce a cl_kernels image - // that doesn’t strictly conform to Mach-O expectations. On Mac OS X 10.10, + // that doesn’t strictly conform to Mach-O expectations. On OS X 10.10, // cl_kernels modules show up with an __LD,__compact_unwind section, showing // up in the __TEXT segment. MachOImageSegmentReader would normally reject // modules for this problem, but a special exception is made when this diff --git a/snapshot/mac/process_snapshot_mac.h b/snapshot/mac/process_snapshot_mac.h index 6c41a662..d3e6eb45 100644 --- a/snapshot/mac/process_snapshot_mac.h +++ b/snapshot/mac/process_snapshot_mac.h @@ -46,8 +46,8 @@ namespace crashpad { -//! \brief A ProcessSnapshot of a running (or crashed) process running on a Mac -//! OS X system. +//! \brief A ProcessSnapshot of a running (or crashed) process running on a +//! macOS system. class ProcessSnapshotMac final : public ProcessSnapshot { public: ProcessSnapshotMac(); @@ -83,21 +83,21 @@ class ProcessSnapshotMac final : public ProcessSnapshot { //! \brief Sets the value to be returned by ReportID(). //! - //! On Mac OS X, the crash report ID is under the control of the snapshot + //! On macOS, the crash report ID is under the control of the snapshot //! producer, which may call this method to set the report ID. If this is not //! done, ReportID() will return an identifier consisting entirely of zeroes. void SetReportID(const UUID& report_id) { report_id_ = report_id; } //! \brief Sets the value to be returned by ClientID(). //! - //! On Mac OS X, the client ID is under the control of the snapshot producer, + //! On macOS, the client ID is under the control of the snapshot producer, //! which may call this method to set the client ID. If this is not done, //! ClientID() will return an identifier consisting entirely of zeroes. void SetClientID(const UUID& client_id) { client_id_ = client_id; } //! \brief Sets the value to be returned by AnnotationsSimpleMap(). //! - //! On Mac OS X, all process annotations are under the control of the snapshot + //! On macOS, all process annotations are under the control of the snapshot //! producer, which may call this method to establish these annotations. //! Contrast this with module annotations, which are under the control of the //! process being snapshotted. diff --git a/snapshot/mac/process_types/crashreporterclient.proctype b/snapshot/mac/process_types/crashreporterclient.proctype index b40aa358..409782c9 100644 --- a/snapshot/mac/process_types/crashreporterclient.proctype +++ b/snapshot/mac/process_types/crashreporterclient.proctype @@ -43,7 +43,7 @@ PROCESS_TYPE_STRUCT_BEGIN(crashreporter_annotations_t) PROCESS_TYPE_STRUCT_MEMBER(uint64_t, version) // unsigned long PROCESS_TYPE_STRUCT_VERSIONED(crashreporter_annotations_t, version) - // Version 4 (Mac OS X 10.7) + // Version 4 (OS X 10.7) PROCESS_TYPE_STRUCT_MEMBER(uint64_t, message) // char* PROCESS_TYPE_STRUCT_MEMBER(uint64_t, signature_string) // char* PROCESS_TYPE_STRUCT_MEMBER(uint64_t, backtrace) // char* diff --git a/snapshot/mac/process_types/custom.cc b/snapshot/mac/process_types/custom.cc index 60c6e504..5fe92288 100644 --- a/snapshot/mac/process_types/custom.cc +++ b/snapshot/mac/process_types/custom.cc @@ -21,6 +21,8 @@ #include "snapshot/mac/process_types/internal.h" #include "util/mach/task_memory.h" +#if !DOXYGEN + namespace crashpad { namespace process_types { namespace internal { @@ -157,3 +159,5 @@ bool crashreporter_annotations_t::ReadInto( } // namespace internal } // namespace process_types } // namespace crashpad + +#endif // !DOXYGEN diff --git a/snapshot/mac/process_types_test.cc b/snapshot/mac/process_types_test.cc index 1bb8d101..ce092fe1 100644 --- a/snapshot/mac/process_types_test.cc +++ b/snapshot/mac/process_types_test.cc @@ -83,8 +83,8 @@ TEST(ProcessTypes, DyldImagesSelf) { dyld_info.all_image_info_addr); EXPECT_GT(dyld_info.all_image_info_size, 1u); - // This field is only present in the Mac OS X 10.7 SDK (at build time) and - // kernel (at run time). + // This field is only present in the OS X 10.7 SDK (at build time) and kernel + // (at run time). #if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_7 if (MacOSXMinorVersion() >= 7) { #if !defined(ARCH_CPU_64_BITS) diff --git a/snapshot/mac/system_snapshot_mac.cc b/snapshot/mac/system_snapshot_mac.cc index 185372dd..3c39088f 100644 --- a/snapshot/mac/system_snapshot_mac.cc +++ b/snapshot/mac/system_snapshot_mac.cc @@ -228,7 +228,7 @@ uint32_t SystemSnapshotMac::CPUX86Leaf7Features() const { INITIALIZATION_STATE_DCHECK_VALID(initialized_); #if defined(ARCH_CPU_X86_FAMILY) - // The machdep.cpu.leaf7_feature_bits sysctl isn’t supported prior to Mac OS X + // The machdep.cpu.leaf7_feature_bits sysctl isn’t supported prior to OS X // 10.7, so read this by calling cpuid directly. // // machdep.cpu.max_basic could be used to check whether to read the leaf, but diff --git a/snapshot/mac/thread_snapshot_mac.h b/snapshot/mac/thread_snapshot_mac.h index bbb7f77b..28334434 100644 --- a/snapshot/mac/thread_snapshot_mac.h +++ b/snapshot/mac/thread_snapshot_mac.h @@ -33,7 +33,7 @@ class ProcessReader; namespace internal { //! \brief A ThreadSnapshot of a thread in a running (or crashed) process on a -//! Mac OS X system. +//! macOS system. class ThreadSnapshotMac final : public ThreadSnapshot { public: ThreadSnapshotMac(); diff --git a/snapshot/module_snapshot.h b/snapshot/module_snapshot.h index 5989e4ba..cd3dbd39 100644 --- a/snapshot/module_snapshot.h +++ b/snapshot/module_snapshot.h @@ -82,8 +82,8 @@ class ModuleSnapshot { //! \brief The module is a dynamic loader. //! //! This is the module responsible for loading other modules. This is - //! normally `dyld` for Mac OS X and `ld.so` for Linux and other systems - //! using ELF. + //! normally `dyld` for macOS and `ld.so` for Linux and other systems using + //! ELF. kModuleTypeDynamicLoader, }; @@ -97,7 +97,7 @@ class ModuleSnapshot { //! \brief Returns the size that the module occupies in the snapshot process’ //! address space, starting at its base address. //! - //! For Mac OS X snapshots, this method only reports the size of the `__TEXT` + //! For macOS snapshots, this method only reports the size of the `__TEXT` //! segment, because segments may not be loaded contiguously. virtual uint64_t Size() const = 0; @@ -113,7 +113,7 @@ class ModuleSnapshot { //! If no file version can be determined, the \a version_* parameters are set //! to `0`. //! - //! For Mac OS X snapshots, this is taken from the module’s `LC_ID_DYLIB` load + //! For macOS snapshots, this is taken from the module’s `LC_ID_DYLIB` load //! command for shared libraries, and is `0` for other module types. virtual void FileVersion(uint16_t* version_0, uint16_t* version_1, @@ -125,8 +125,8 @@ class ModuleSnapshot { //! If no source version can be determined, the \a version_* parameters are //! set to `0`. //! - //! For Mac OS X snapshots, this is taken from the module’s - //! `LC_SOURCE_VERSION` load command. + //! For macOS snapshots, this is taken from the module’s `LC_SOURCE_VERSION` + //! load command. virtual void SourceVersion(uint16_t* version_0, uint16_t* version_1, uint16_t* version_2, @@ -164,7 +164,7 @@ class ModuleSnapshot { //! are intended for diagnostic use, including crash analysis. A module may //! contain multiple annotations, so they are returned in a vector. //! - //! For Mac OS X snapshots, these annotations are found by interpreting the + //! For macOS snapshots, these annotations are found by interpreting the //! module’s `__DATA,__crash_info` section as `crashreporter_annotations_t`. //! System libraries using the crash reporter client interface may reference //! annotations in this structure. Additional annotations messages may be @@ -183,7 +183,7 @@ class ModuleSnapshot { //! keys and values are strings. These are referred to in Chrome as “crash //! keys.” //! - //! For Mac OS X snapshots, these annotations are found by interpreting the + //! For macOS snapshots, these annotations are found by interpreting the //! `__DATA,crashpad_info` section as `CrashpadInfo`. Clients can use the //! Crashpad client interface to store annotations in this structure. Most //! annotations under the client’s direct control will be retrievable by this diff --git a/snapshot/system_snapshot.h b/snapshot/system_snapshot.h index 82f5d480..549f0b67 100644 --- a/snapshot/system_snapshot.h +++ b/snapshot/system_snapshot.h @@ -36,7 +36,7 @@ class SystemSnapshot { //! \brief The snapshot system’s operating system is unknown. kOperatingSystemUnknown = 0, - //! \brief Mac OS X. + //! \brief macOS. kOperatingSystemMacOSX, //! \brief Windows. @@ -104,7 +104,7 @@ class SystemSnapshot { virtual std::string CPUVendor() const = 0; //! \brief Returns frequency information about the snapshot system’s CPUs in - //! \current_hz and \a max_hz. + //! \a current_hz and \a max_hz. //! //! \param[out] current_hz The snapshot system’s CPU clock frequency in Hz at //! the time of the snapshot. @@ -198,21 +198,21 @@ class SystemSnapshot { //! in \a major, \a minor, \a bugfix, and \a build. //! //! \param[out] major The snapshot system’s operating system’s first (major) - //! version number component. This would be `10` for Mac OS X 10.9.5, and + //! version number component. This would be `10` for macOS 10.12.1, and //! `6` for Windows 7 (NT 6.1) SP1 version 6.1.7601. //! \param[out] minor The snapshot system’s operating system’s second (minor) - //! version number component. This would be `9` for Mac OS X 10.9.5, and + //! version number component. This would be `12` for macOS 10.12.1, and //! `1` for Windows 7 (NT 6.1) SP1 version 6.1.7601. //! \param[out] bugfix The snapshot system’s operating system’s third (bugfix) - //! version number component. This would be `5` for Mac OS X 10.9.5, and + //! version number component. This would be `1` for macOS 10.12.1, and //! `7601` for Windows 7 (NT 6.1) SP1 version 6.1.7601. //! \param[out] build A string further identifying an operating system - //! version. For Mac OS X 10.9.5, this would be `"13F34"`. For Windows, + //! version. For macOS 10.12.1, this would be `"16B2657"`. For Windows, //! this would be `"Service Pack 1"` if that service pack was installed. - //! For Linux and other Unix-like systems, this would be the kernel - //! version from `uname -srvm`, possibly with additional information - //! appended. On Android, the `ro.build.fingerprint` system property would - //! be appended. + //! On Android, the `ro.build.fingerprint` system property would be + //! appended. For Linux and other Unix-like systems, this would be the + //! kernel version from `uname -srvm`, possibly with additional + //! information appended. virtual void OSVersion(int* major, int* minor, int* bugfix, @@ -221,17 +221,17 @@ class SystemSnapshot { //! \brief Returns the snapshot system’s full operating system version //! information in string format. //! - //! For Mac OS X, the string contains values from the operating system and - //! kernel. A Mac OS X 10.9.5 snapshot system would be identified as `"Mac OS - //! X 10.9.5 (13F34); Darwin 13.4.0 Darwin Kernel Version 13.4.0: Sun Aug 17 - //! 19:50:11 PDT 2014; root:xnu-2422.115.4~1/RELEASE_X86_64 x86_64"`. + //! For macOS, the string contains values from the operating system and + //! kernel. A macOS 10.12.1 system snapshot would be identified as `"Mac OS + //! X 10.12.1 (16B2657); Darwin 16.1.0 Darwin Kernel Version 16.1.0: Wed Oct + //! 19 20:31:56 PDT 2016; root:xnu-3789.21.4~4/RELEASE_X86_64 x86_64"`. virtual std::string OSVersionFull() const = 0; //! \brief Returns a description of the snapshot system’s hardware in string //! format. //! - //! For Mac OS X, the string contains the Mac model and board ID. A mid-2014 - //! 15" MacBook Pro would be identified as `"MacBookPro11,3 + //! For macOS, the string contains the Mac model and board ID. A mid-2014 15" + //! MacBook Pro would be identified as `"MacBookPro11,3 //! (Mac-2BD1B31983FE1663)"`. virtual std::string MachineDescription() const = 0; @@ -258,7 +258,7 @@ class SystemSnapshot { //! being observed. //! \param[out] daylight_name The name of the time zone while daylight saving //! time is being observed. - virtual void TimeZone(DaylightSavingTimeStatus* observes_daylight, + virtual void TimeZone(DaylightSavingTimeStatus* dst_status, int* standard_offset_seconds, int* daylight_offset_seconds, std::string* standard_name, diff --git a/snapshot/test/test_process_snapshot.h b/snapshot/test/test_process_snapshot.h index 633d9b9b..7dd31247 100644 --- a/snapshot/test/test_process_snapshot.h +++ b/snapshot/test/test_process_snapshot.h @@ -121,7 +121,7 @@ class TestProcessSnapshot final : public ProcessSnapshot { //! \brief Adds a handle snapshot to be returned by Handles(). //! - //! \param[in] region The handle snapshot that will be included in Handles(). + //! \param[in] handle The handle snapshot that will be included in Handles(). void AddHandle(const HandleSnapshot& handle) { handles_.push_back(handle); } diff --git a/snapshot/win/exception_snapshot_win.h b/snapshot/win/exception_snapshot_win.h index 3ccf38ae..7aedb3a4 100644 --- a/snapshot/win/exception_snapshot_win.h +++ b/snapshot/win/exception_snapshot_win.h @@ -53,9 +53,9 @@ class ExceptionSnapshotWin final : public ExceptionSnapshot { //! \param[in] process_reader A ProcessReader for the process that sustained //! the exception. //! \param[in] thread_id The thread ID in which the exception occurred. - //! \param[in] exception_pointers_address The address of an - //! `EXCEPTION_POINTERS` record in the target process, passed through from - //! the exception handler. + //! \param[in] exception_pointers The address of an `EXCEPTION_POINTERS` + //! record in the target process, passed through from the exception + //! handler. //! //! \note If the exception was triggered by //! CrashpadClient::DumpAndCrashTargetProcess(), this has the side-effect diff --git a/snapshot/win/pe_image_annotations_reader.h b/snapshot/win/pe_image_annotations_reader.h index 868b076c..85f3bed3 100644 --- a/snapshot/win/pe_image_annotations_reader.h +++ b/snapshot/win/pe_image_annotations_reader.h @@ -41,8 +41,8 @@ class PEImageAnnotationsReader { //! \brief Constructs the object. //! //! \param[in] process_reader The reader for the remote process. - //! \param[in] image_reader The PEImageReader for the PE image file contained - //! within the remote process. + //! \param[in] pe_image_reader The PEImageReader for the PE image file + //! contained within the remote process. //! \param[in] name The module's name, a string to be used in logged messages. //! This string is for diagnostic purposes only, and may be empty. PEImageAnnotationsReader(ProcessReaderWin* process_reader, diff --git a/snapshot/win/thread_snapshot_win.h b/snapshot/win/thread_snapshot_win.h index 7b566885..7df23ab3 100644 --- a/snapshot/win/thread_snapshot_win.h +++ b/snapshot/win/thread_snapshot_win.h @@ -48,7 +48,7 @@ class ThreadSnapshotWin final : public ThreadSnapshot { //! the thread. //! \param[in] process_reader_thread The thread within the ProcessReaderWin //! for which the snapshot should be created. - //! \param[in] gather_indirectly_referenced_memory_bytes_remaining. If + //! \param[in,out] gather_indirectly_referenced_memory_bytes_remaining If //! non-null, add extra memory regions to the snapshot pointed to by the //! thread's stack. The size of the regions added is subtracted from the //! count, and when it's `0`, no more regions will be added. diff --git a/test/win/win_multiprocess.h b/test/win/win_multiprocess.h index 418df790..663c7594 100644 --- a/test/win/win_multiprocess.h +++ b/test/win/win_multiprocess.h @@ -71,7 +71,7 @@ class WinMultiprocess { //! //! The default expected termination code is `EXIT_SUCCESS` (`0`). //! - //! \param[in] code The expected exit status of the child. + //! \param[in] exit_code The expected exit status of the child. void SetExpectedChildExitCode(unsigned int exit_code); //! \brief Returns the read pipe's file handle. diff --git a/third_party/apple_cctools/README.crashpad b/third_party/apple_cctools/README.crashpad index a2aadf72..43b08618 100644 --- a/third_party/apple_cctools/README.crashpad +++ b/third_party/apple_cctools/README.crashpad @@ -13,11 +13,11 @@ like ar, as, nm, strings, and strip, and platform-specific tools like lipo and otool. It also contains support libraries such as libmacho, which contains interfaces for dealing with Mach-O images. -libmacho is available on Mac OS X as a runtime library that is part of -libSystem, but versions of libmacho included in operating system versions prior -to Mac OS X 10.7 did not include the getsectiondata() and getsegmentdata() -functions. This library is present here to provide implementations of these -functions for systems that do not have them. +libmacho is available on macOS as a runtime library that is part of libSystem, +but versions of libmacho included in operating system versions prior to Mac OS X +10.7 did not include the getsectiondata() and getsegmentdata() functions. This +library is present here to provide implementations of these functions for +systems that do not have them. Crashpad code is not expected to use this library directly. It should use the getsectiondata() and getsegmentdata() wrappers in compat, which will use diff --git a/tools/tool_support.h b/tools/tool_support.h index 79dc7524..e3a50614 100644 --- a/tools/tool_support.h +++ b/tools/tool_support.h @@ -41,6 +41,8 @@ class ToolSupport { //! of its arguments. //! //! \param[in] me The tool’s name, the basename of `argv[0]`. + //! \param[in] hint A hint to display before the suggestion to try `--help`. + //! Optional, may be `nullptr`, in which case no hint will be presented. static void UsageHint(const base::FilePath& me, const char* hint); #if defined(OS_POSIX) || DOXYGEN diff --git a/util/mac/launchd.h b/util/mac/launchd.h index 25450752..21b43f8d 100644 --- a/util/mac/launchd.h +++ b/util/mac/launchd.h @@ -27,9 +27,9 @@ namespace crashpad { //! \{ //! \brief Wraps the `` function of the same name. //! -//! The Mac OS X 10.10 SDK deprecates ``, although the functionality -//! it provides is still useful. These wrappers allow the deprecated functions -//! to be called without triggering deprecated-declaration warnings. +//! The OS X 10.10 SDK deprecates ``, although the functionality it +//! provides is still useful. These wrappers allow the deprecated functions to +//! be called without triggering deprecated-declaration warnings. inline launch_data_t LaunchDataAlloc(launch_data_type_t type) { return launch_data_alloc(type); diff --git a/util/mac/mac_util.cc b/util/mac/mac_util.cc index a792e511..7c51cc2e 100644 --- a/util/mac/mac_util.cc +++ b/util/mac/mac_util.cc @@ -181,9 +181,8 @@ std::string IORegistryEntryDataPropertyAsString(io_registry_entry_t entry, namespace crashpad { int MacOSXMinorVersion() { - // The Darwin major version is always 4 greater than the Mac OS X minor - // version for Darwin versions beginning with 6, corresponding to Mac OS X - // 10.2. + // The Darwin major version is always 4 greater than the macOS minor version + // for Darwin versions beginning with 6, corresponding to Mac OS X 10.2. static int mac_os_x_minor_version = DarwinMajorVersion() - 4; DCHECK(mac_os_x_minor_version >= 2); return mac_os_x_minor_version; diff --git a/util/mac/mac_util.h b/util/mac/mac_util.h index 9cedfdfb..d8b71598 100644 --- a/util/mac/mac_util.h +++ b/util/mac/mac_util.h @@ -21,8 +21,8 @@ namespace crashpad { //! \brief Returns the version of the running operating system. //! -//! \return The minor version of the operating system, such as `9` for Mac OS X -//! 10.9.2. +//! \return The minor version of the operating system, such as `12` for macOS +//! 10.12.1. //! //! \note This is similar to the base::mac::IsOS*() family of functions, but //! is provided for situations where the caller needs to obtain version @@ -35,17 +35,17 @@ int MacOSXMinorVersion(); //! All parameters are required. No parameter may be `nullptr`. //! //! \param[out] major The major version of the operating system, such as `10` -//! for Mac OS X 10.9.2. -//! \param[out] minor The major version of the operating system, such as `9` for -//! Mac OS X 10.9.2. -//! \param[out] bugfix The bugfix version of the operating system, such as `2` -//! for Mac OS X 10.9.2. -//! \param[out] build The operating system’s build string, such as "13C64" for -//! Mac OS X 10.9.2. -//! \param[out] server `true` for a Mac OS X Server installation, `false` -//! otherwise (for a desktop/laptop, client, or workstation system). +//! for macOS 10.12.1. +//! \param[out] minor The major version of the operating system, such as `12` +//! for macOS 10.12.1. +//! \param[out] bugfix The bugfix version of the operating system, such as `1` +//! for macOS 10.12.1. +//! \param[out] build The operating system’s build string, such as `"16B2657"` +//! for macOS 10.12.1. +//! \param[out] server `true` for a macOS Server installation, `false` otherwise +//! (for a desktop/laptop, client, or workstation system). //! \param[out] version_string A string representing the full operating system -//! version, such as `"Mac OS X 10.9.2 (13C64)"`. +//! version, such as `"macOS 10.12.1 (16B2657)"`. //! //! \return `true` on success, `false` on failure, with an error message logged. //! A failure is considered to have occurred if any element could not be diff --git a/util/mac/service_management.h b/util/mac/service_management.h index 802e5449..16cb45aa 100644 --- a/util/mac/service_management.h +++ b/util/mac/service_management.h @@ -28,8 +28,8 @@ namespace crashpad { //! //! \return `true` if the job was submitted successfully, otherwise `false`. //! -//! \note This function is provided because `SMJobSubmit()` is deprecated in Mac -//! OS X 10.10. It may or may not be implemented using `SMJobSubmit()` from +//! \note This function is provided because `SMJobSubmit()` is deprecated in OS +//! X 10.10. It may or may not be implemented using `SMJobSubmit()` from //! `ServiceManagement.framework`. bool ServiceManagementSubmitJob(CFDictionaryRef job_cf); @@ -42,12 +42,11 @@ bool ServiceManagementSubmitJob(CFDictionaryRef job_cf); //! \return `true` if the job was removed successfully or if an asynchronous //! attempt to remove the job was started successfully, otherwise `false`. //! -//! \note This function is provided because `SMJobRemove()` is deprecated in Mac -//! OS X 10.10. On Mac OS X 10.10, observed in DP8 14A361c, it also blocks -//! for far too long (`_block_until_job_exits()` contains a one-second -//! `sleep()`, filed as radar 18398683) and does not signal failure via its -//! return value when asked to remove a nonexistent job (filed as radar -//! 18268941). +//! \note This function is provided because `SMJobRemove()` is deprecated in OS +//! X 10.10. On OS X 10.10, observed in DP8 14A361c, it also blocks for far +//! too long (`_block_until_job_exits()` contains a one-second `sleep()`, +//! filed as radar 18398683) and does not signal failure via its return +//! value when asked to remove a nonexistent job (filed as radar 18268941). bool ServiceManagementRemoveJob(const std::string& label, bool wait); //! \brief Determines whether a specified job is loaded in the user launchd @@ -60,7 +59,7 @@ bool ServiceManagementRemoveJob(const std::string& label, bool wait); //! \note A loaded job is not necessarily presently running, nor has it //! necessarily ever run in the past. //! \note This function is provided because `SMJobCopyDictionary()` is -//! deprecated in Mac OS X 10.10. It may or may not be implemented using +//! deprecated in OS X 10.10. It may or may not be implemented using //! `SMJobCopyDictionary()` from `ServiceManagement.framework`. bool ServiceManagementIsJobLoaded(const std::string& label); @@ -72,7 +71,7 @@ bool ServiceManagementIsJobLoaded(const std::string& label); //! \return The job’s process ID if running, otherwise `0`. //! //! \note This function is provided because `SMJobCopyDictionary()` is -//! deprecated in Mac OS X 10.10. It may or may not be implemented using +//! deprecated in OS X 10.10. It may or may not be implemented using //! `SMJobCopyDictionary()` from `ServiceManagement.framework`. pid_t ServiceManagementIsJobRunning(const std::string& label); diff --git a/util/mac/xattr.cc b/util/mac/xattr.cc index 138de3e4..75d7938d 100644 --- a/util/mac/xattr.cc +++ b/util/mac/xattr.cc @@ -117,8 +117,8 @@ bool WriteXattrInt(const base::FilePath& file, XattrStatus ReadXattrTimeT(const base::FilePath& file, const base::StringPiece& name, time_t* value) { - // time_t on OS X is defined as a long, but it will be read into an - // int64_t here, since there is no string conversion method for long. + // time_t on macOS is defined as a long, but it will be read into an int64_t + // here, since there is no string conversion method for long. std::string tmp; XattrStatus status; if ((status = ReadXattr(file, name, &tmp)) != XattrStatus::kOK) diff --git a/util/mach/child_port_handshake.h b/util/mach/child_port_handshake.h index 50de118a..429164a9 100644 --- a/util/mach/child_port_handshake.h +++ b/util/mach/child_port_handshake.h @@ -218,6 +218,9 @@ class ChildPortHandshake { //! - Regardless of return value, destroys the server’s receive right and //! closes the pipe. //! + //! \param[in] server_write_fd The write side of the pipe shared with the + //! client process. This function takes ownership of this file descriptor, + //! and will close it prior to returning. //! \param[in] port_right_type The port right type expected to be received //! from the client. If the port right received from the client does not //! match the expected type, the received port right will be destroyed, @@ -253,9 +256,9 @@ class ChildPortHandshake { //! `simpleroutine`, and the server does not send a reply. This allows //! check-in to occur without blocking to wait for a reply. //! - //! \param[in] pipe_read The “read” side of the pipe shared with the server - //! process. This function takes ownership of this file descriptor, and - //! will close it prior to returning. + //! \param[in] client_read_fd The “read” side of the pipe shared with the + //! server process. This function takes ownership of this file descriptor, + //! and will close it prior to returning. //! \param[in] port The port right that will be passed to the server by //! `child_port_check_in()`. //! \param[in] right_type The right type to furnish the server with. If \a diff --git a/util/mach/child_port_server.h b/util/mach/child_port_server.h index b82e99a3..47d72e4d 100644 --- a/util/mach/child_port_server.h +++ b/util/mach/child_port_server.h @@ -37,6 +37,10 @@ class ChildPortServer : public MachMessageServer::Interface { //! This behaves equivalently to a `handle_child_port_check_in()` function //! used with `child_port_server()`. //! + //! \param[in] server + //! \param[in] token + //! \param[in] port + //! \param[in] right_type //! \param[in] trailer The trailer received with the request message. //! \param[out] destroy_request `true` if the request message is to be //! destroyed even when this method returns success. See diff --git a/util/mach/exc_client_variants.h b/util/mach/exc_client_variants.h index d96e689e..3fa06a0b 100644 --- a/util/mach/exc_client_variants.h +++ b/util/mach/exc_client_variants.h @@ -56,15 +56,25 @@ namespace crashpad { //! and may be set to `0` (\a old_state_count) or `nullptr` (the remaining //! parameters). //! +//! Except as noted, the parameters and return value are equivalent to those of +//! the `*exception_raise*()` family of functions. +//! //! \param[in] behavior The exception behavior, which dictates which function //! will be called. It is an error to call this function with an invalid //! value for \a behavior. -//! \param[in] code If \behavior indicates a behavior without +//! \param[in] exception_port +//! \param[in] thread +//! \param[in] task +//! \param[in] exception +//! \param[in] code If \a behavior indicates a behavior without //! `MACH_EXCEPTION_CODES`, the elements of \a code will be truncated in //! order to be passed to the appropriate exception handler. -//! -//! All other parameters are treated equivalently to their treatment by the -//! `*exception_raise*()` family of functions. +//! \param[in] code_count +//! \param[in,out] flavor +//! \param[in] old_state +//! \param[in] old_state_count +//! \param[out] new_state +//! \param[out] new_state_count //! //! \return The return value of the function called. kern_return_t UniversalExceptionRaise(exception_behavior_t behavior, diff --git a/util/mach/exc_client_variants_test.cc b/util/mach/exc_client_variants_test.cc index ca3101cd..29a272b9 100644 --- a/util/mach/exc_client_variants_test.cc +++ b/util/mach/exc_client_variants_test.cc @@ -115,7 +115,7 @@ class TestExcClientVariants : public MachMultiprocess, } // Use a flavor known to be different from the incoming flavor, for a test - // of the “out” side of the inout flavor parameter. + // of the “out” side of the in-out flavor parameter. *flavor = exception_ + 20; *new_state_count = MACHINE_THREAD_STATE_COUNT; diff --git a/util/mach/exc_server_variants.h b/util/mach/exc_server_variants.h index 0d947432..c7b35d41 100644 --- a/util/mach/exc_server_variants.h +++ b/util/mach/exc_server_variants.h @@ -64,17 +64,32 @@ class UniversalMachExcServer final : public MachMessageServer::Interface { //! This behaves equivalently to a `catch_exception_raise_state_identity()` //! function used with `exc_server()`, or a //! `catch_mach_exception_raise_state_identity()` function used with - //! `mach_exc_server()`. The meanings of most parameters are identical to - //! their meanings to these functions. + //! `mach_exc_server()`. Except as noted, the parameters and return value + //! are equivalent to those of these other functions. //! //! \param[in] behavior `EXCEPTION_DEFAULT`, `EXCEPTION_STATE`, //! or `EXCEPTION_STATE_IDENTITY`, possibly with `MACH_EXCEPTION_CODES` //! ORed in. This identifies which exception request message was //! processed and thus which other parameters are valid. + //! \param[in] exception_port + //! \param[in] thread + //! \param[in] task + //! \param[in] exception + //! \param[in] code + //! \param[in] code_count + //! \param[in,out] flavor + //! \param[in] old_state + //! \param[in] old_state_count + //! \param[out] new_state + //! \param[out] new_state_count //! \param[in] trailer The trailer received with the request message. - //! \param[out] destroy_request `true` if the request message is to be - //! destroyed even when this method returns success. See + //! \param[out] destroy_complex_request `true` if the request message is to + //! be destroyed even when this method returns success. See //! MachMessageServer::Interface. + //! + //! \return A code indicating whether the exception was handled. See + //! ExcServerSuccessfulReturnValue() for success codes. On failure, + //! a code such as `KERN_FAILURE`. virtual kern_return_t CatchMachException( exception_behavior_t behavior, exception_handler_t exception_port, @@ -201,7 +216,7 @@ kern_return_t ExcServerSuccessfulReturnValue(exception_type_t exception, //! from the \a new_state parameter of //! internal::SimplifiedExcServer::Interface::CatchException(), for example. //! This parameter is untouched if \a behavior is not state-carrying. -//! \param[inout] new_state_count On entry, the number of `natural_t` words +//! \param[in,out] new_state_count On entry, the number of `natural_t` words //! available to be written to in \a new_state. On return, the number of //! significant `natural_t` words in \a new_state. This may be taken //! directly from the \a new_state_count parameter of diff --git a/util/mach/exception_types.cc b/util/mach/exception_types.cc index cef90f9a..09366b57 100644 --- a/util/mach/exception_types.cc +++ b/util/mach/exception_types.cc @@ -29,9 +29,9 @@ extern "C" { -// proc_get_wakemon_params() is present in the Mac OS X 10.9 SDK, but no -// declaration is provided. This provides a declaration and marks it for weak -// import if the deployment target is below 10.9. +// proc_get_wakemon_params() is present in the OS X 10.9 SDK, but no declaration +// is provided. This provides a declaration and marks it for weak import if the +// deployment target is below 10.9. int proc_get_wakemon_params(pid_t pid, int* rate_hz, int* flags) __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); @@ -76,8 +76,8 @@ ProcGetWakemonParamsType GetProcGetWakemonParams() { namespace { // Wraps proc_get_wakemon_params(), calling it if the system provides it. It’s -// present on Mac OS X 10.9 and later. If it’s not available, sets errno to -// ENOSYS and returns -1. +// present on OS X 10.9 and later. If it’s not available, sets errno to ENOSYS +// and returns -1. int ProcGetWakemonParams(pid_t pid, int* rate_hz, int* flags) { #if MAC_OS_X_VERSION_MAX_ALLOWED < MAC_OS_X_VERSION_10_9 // proc_get_wakemon_params() isn’t in the SDK. Look it up dynamically. @@ -146,17 +146,17 @@ bool IsExceptionNonfatalResource(exception_type_t exception, // RLIMIT_CPU_USAGE_MONITOR as the second argument and CPUMON_MAKE_FATAL set // in the flags. if (MacOSXMinorVersion() >= 10) { - // In Mac OS X 10.10, the exception code indicates whether the exception - // is fatal. See 10.10 xnu-2782.1.97/osfmk/kern/thread.c + // In OS X 10.10, the exception code indicates whether the exception is + // fatal. See 10.10 xnu-2782.1.97/osfmk/kern/thread.c // THIS_THREAD_IS_CONSUMING_TOO_MUCH_CPU__SENDING_EXC_RESOURCE(). return resource_flavor == FLAVOR_CPU_MONITOR; } - // In Mac OS X 10.9, there’s no way to determine whether the exception is - // fatal. Unlike RESOURCE_TYPE_WAKEUPS below, there’s no way to determine - // this outside the kernel. proc_rlimit_control()’s RLIMIT_CPU_USAGE_MONITOR - // is the only interface to modify CPUMON_MAKE_FATAL, but it’s only able to - // set this bit, not obtain its current value. + // In OS X 10.9, there’s no way to determine whether the exception is fatal. + // Unlike RESOURCE_TYPE_WAKEUPS below, there’s no way to determine this + // outside the kernel. proc_rlimit_control()’s RLIMIT_CPU_USAGE_MONITOR is + // the only interface to modify CPUMON_MAKE_FATAL, but it’s only able to set + // this bit, not obtain its current value. // // Default to assuming that these exceptions are nonfatal. They are nonfatal // by default and no users of proc_rlimit_control() were found on 10.9.5 diff --git a/util/mach/exception_types_test.cc b/util/mach/exception_types_test.cc index 372b57f0..d82dcbb9 100644 --- a/util/mach/exception_types_test.cc +++ b/util/mach/exception_types_test.cc @@ -102,7 +102,7 @@ TEST(ExceptionTypes, IsExceptionNonfatalResource) { EXPECT_TRUE(IsExceptionNonfatalResource(EXC_RESOURCE, code, pid)); if (MacOSXMinorVersion() >= 10) { - // FLAVOR_CPU_MONITOR_FATAL was introduced in Mac OS X 10.10. + // FLAVOR_CPU_MONITOR_FATAL was introduced in OS X 10.10. code = 0; EXC_RESOURCE_ENCODE_TYPE(code, RESOURCE_TYPE_CPU); EXC_RESOURCE_ENCODE_FLAVOR(code, FLAVOR_CPU_MONITOR_FATAL); diff --git a/util/mach/mach_message.h b/util/mach/mach_message.h index 2fd81511..df4b6b4f 100644 --- a/util/mach/mach_message.h +++ b/util/mach/mach_message.h @@ -53,7 +53,8 @@ enum : mach_msg_timeout_t { //! ClockMonotonicNanoseconds(), although this is an implementation detail. using MachMessageDeadline = uint64_t; -//! \brief Special constants used as \ref MachMessageDeadline values. +//! \brief Special constants used as \ref crashpad::MachMessageDeadline +//! "MachMessageDeadline" values. enum : MachMessageDeadline { //! \brief MachMessageWithDeadline() should not block at all in its operation. kMachMessageDeadlineNonblocking = 0, @@ -98,15 +99,22 @@ MachMessageDeadline MachMessageDeadlineFromTimeout( //! Except as noted, the parameters and return value are identical to those of //! `mach_msg()`. //! +//! \param[in,out] message +//! \param[in] options +//! \param[in] receive_size +//! \param[in] receive_port //! \param[in] deadline The time by which this call should complete. If the //! deadline is exceeded, this call will return `MACH_SEND_TIMED_OUT` or //! `MACH_RCV_TIMED_OUT`. +//! \param[in] notify_port //! \param[in] run_even_if_expired If `true`, a deadline that is expired when //! this function is called will be treated as though a deadline of //! #kMachMessageDeadlineNonblocking had been specified. When `false`, an //! expired deadline will result in a `MACH_SEND_TIMED_OUT` or //! `MACH_RCV_TIMED_OUT` return value, even if the deadline is already //! expired when the function is called. +//! +//! \return The return value of `mach_msg()` mach_msg_return_t MachMessageWithDeadline(mach_msg_header_t* message, mach_msg_option_t options, mach_msg_size_t receive_size, @@ -134,9 +142,9 @@ void PrepareMIGReplyFromRequest(const mach_msg_header_t* in_header, //! \brief Sets the error code in a reply message for a MIG server routine. //! -//! \param[inout] out_header The reply message to operate on. \a out_header will -//! be treated as a `mig_reply_error_t*` and its `RetCode` field will be -//! set. This argument is accepted as a `mach_msg_header_t*` instead of a +//! \param[in,out] out_header The reply message to operate on. \a out_header +//! will be treated as a `mig_reply_error_t*` and its `RetCode` field will +//! be set. This argument is accepted as a `mach_msg_header_t*` instead of a //! `mig_reply_error_t*` because that is the type that callers are expected //! to possess in the C API. //! \param[in] error The error code to store in \a out_header. diff --git a/util/mach/mach_message_server.cc b/util/mach/mach_message_server.cc index 0af19018..39633730 100644 --- a/util/mach/mach_message_server.cc +++ b/util/mach/mach_message_server.cc @@ -147,7 +147,7 @@ mach_msg_return_t MachMessageServer::Run(Interface* interface, // mach_msg_server() and mach_msg_server_once() would consider whether // |options| contains MACH_SEND_TRAILER and include MAX_TRAILER_SIZE in this - // computation if it does, but that option is ineffective on OS X. + // computation if it does, but that option is ineffective on macOS. const mach_msg_size_t reply_size = interface->MachMessageServerReplySize(); DCHECK_GE(reply_size, sizeof(mach_msg_empty_send_t)); const mach_msg_size_t reply_alloc = round_page(reply_size); diff --git a/util/mach/mach_message_server_test.cc b/util/mach/mach_message_server_test.cc index fc45e262..a2d2eb1f 100644 --- a/util/mach/mach_message_server_test.cc +++ b/util/mach/mach_message_server_test.cc @@ -321,9 +321,9 @@ class TestMachMessageServer : public MachMessageServer::Interface, kern_return_t kr; if (options_.child_send_all_requests_before_receiving_any_replies) { - // On Mac OS X 10.10, the queue limit of a new Mach port seems to be 2 - // by default, which is below the value of MACH_PORT_QLIMIT_DEFAULT. Set - // the port’s queue limit explicitly here. + // On OS X 10.10, the queue limit of a new Mach port seems to be 2 by + // default, which is below the value of MACH_PORT_QLIMIT_DEFAULT. Set the + // port’s queue limit explicitly here. mach_port_limits limits = {}; limits.mpl_qlimit = MACH_PORT_QLIMIT_DEFAULT; kr = mach_port_set_attributes(mach_task_self(), diff --git a/util/misc/initialization_state_dcheck.h b/util/misc/initialization_state_dcheck.h index e45a6f82..7b6df986 100644 --- a/util/misc/initialization_state_dcheck.h +++ b/util/misc/initialization_state_dcheck.h @@ -35,9 +35,9 @@ namespace crashpad { //! Initialize() methods. The chief advantage of InitializationStateDcheck over //! having a member variable to track state is that when the only use of the //! variable is to DCHECK, it wastes space (in memory and executable code) in -//! non-DCHECK builds unless the code is also peppered with ugly #ifdefs. +//! non-DCHECK builds unless the code is also peppered with ugly `#%ifdef`s. //! -//! This implementation concentrates the ugly #ifdefs in one location. +//! This implementation concentrates the ugly `#%ifdef`s in one location. //! //! Usage: //! diff --git a/util/misc/metrics.h b/util/misc/metrics.h index a6a7f986..fd2e1200 100644 --- a/util/misc/metrics.h +++ b/util/misc/metrics.h @@ -89,12 +89,12 @@ class Metrics { //! \brief Unexpected exception behavior. //! - //! This value is only used on Mac OS X. + //! This value is only used on macOS. kUnexpectedExceptionBehavior = 1, //! \brief Failed due to attempt to suspend self. //! - //! This value is only used on Mac OS X. + //! This value is only used on macOS. kFailedDueToSuspendSelf = 2, //! \brief The process snapshot could not be captured. diff --git a/util/net/http_transport.h b/util/net/http_transport.h index cd31facf..f9948aa2 100644 --- a/util/net/http_transport.h +++ b/util/net/http_transport.h @@ -74,9 +74,9 @@ class HTTPTransport { //! \brief Performs the HTTP request with the configured parameters and waits //! for the execution to complete. //! - //! \param[out] response On success, this will be set to the HTTP response - //! body. This parameter is optional and may be set to `nullptr` if the - //! response body is not required. + //! \param[out] response_body On success, this will be set to the HTTP + //! response body. This parameter is optional and may be set to `nullptr` + //! if the response body is not required. //! //! \return Whether or not the request was successful, defined as returning //! a HTTP status 200 (OK) code. diff --git a/util/net/http_transport_test.cc b/util/net/http_transport_test.cc index bbfe8780..e8495308 100644 --- a/util/net/http_transport_test.cc +++ b/util/net/http_transport_test.cc @@ -279,7 +279,7 @@ TEST(HTTPTransport, UnchunkedPlainText) { } void RunUpload33k(bool has_content_length) { - // On OS X, NSMutableURLRequest winds up calling into a CFReadStream’s Read() + // On macOS, NSMutableURLRequest winds up calling into a CFReadStream’s Read() // callback with a 32kB buffer. Make sure that it’s able to get everything // when enough is available to fill this buffer, requiring more than one // Read(). diff --git a/util/posix/close_multiple.h b/util/posix/close_multiple.h index 2a66f28a..baf72b2b 100644 --- a/util/posix/close_multiple.h +++ b/util/posix/close_multiple.h @@ -28,8 +28,8 @@ namespace crashpad { //! //! Unlike the BSD function, this function may not close file descriptors //! immediately, but may instead mark them as close-on-exec. The actual behavior -//! chosen is specific to the operating system. On Mac OS X, file descriptors -//! are marked close-on-exec instead of being closed outright in order to avoid +//! chosen is specific to the operating system. On macOS, file descriptors are +//! marked close-on-exec instead of being closed outright in order to avoid //! raising `EXC_GUARD` exceptions for guarded file descriptors that are //! protected against `close()`. //! diff --git a/util/posix/drop_privileges.cc b/util/posix/drop_privileges.cc index 5c809904..884a411c 100644 --- a/util/posix/drop_privileges.cc +++ b/util/posix/drop_privileges.cc @@ -31,10 +31,10 @@ void DropPrivileges() { // is set not equal to the real ID. This code never specifies -1, so the // setreuid() and setregid() alone should work according to the standard. // - // In practice, on Mac OS X, setuid() and setgid() (or seteuid() and - // setegid()) must be called first. Otherwise, setreuid() and setregid() do - // not alter the saved IDs, leaving open the possibility for future privilege - // escalation. + // In practice, on older versions of macOS, setuid() and setgid() (or + // seteuid() and setegid()) must be called first. Otherwise, setreuid() and + // setregid() do not alter the saved IDs, leaving open the possibility for + // future privilege escalation. // // The problem exists in 10.9.5 xnu-2422.115.4/bsd/kern/kern_prot.c // setreuid(). Based on its comments, it purports to set the svuid to the new @@ -45,8 +45,8 @@ void DropPrivileges() { // is different from the desired euid. The workaround of calling setuid() or // seteuid() before setreuid() works because it sets the euid so that by the // time setreuid() runs, the old euid is actually the value that ought to be - // set as the svuid. setregid() is similar. This bug is filed as radar - // 18987552. + // set as the svuid. setregid() is similar. This bug was reported as radar + // 18987552, fixed in 10.10.3 and security updates to 10.9.5 and 10.8.5. // // setuid() and setgid() alone will only set the saved IDs when running as // root. When running a setuid non-root or setgid program, they do not alter diff --git a/util/stdlib/map_insert.h b/util/stdlib/map_insert.h index 956271b3..d2c3b842 100644 --- a/util/stdlib/map_insert.h +++ b/util/stdlib/map_insert.h @@ -21,12 +21,12 @@ namespace crashpad { //! \brief Inserts a mapping from \a key to \a value into \a map, or replaces -//! an existing mapping so that \a key maps to \value. +//! an existing mapping so that \a key maps to \a value. //! -//! This behaves similarly to `std::map<>::insert_or_assign()` proposed for +//! This behaves similarly to `std::map<>::%insert_or_assign()` proposed for //! C++17, except that the \a old_value parameter is added. //! -//! \param[inout] map The map to operate on. +//! \param[in,out] map The map to operate on. //! \param[in] key The key that should be mapped to \a value. //! \param[in] value The value that \a key should map to. //! \param[out] old_value If \a key was previously present in \a map, this will diff --git a/util/string/split_string.cc b/util/string/split_string.cc index 9d0d675a..fe7a7eb4 100644 --- a/util/string/split_string.cc +++ b/util/string/split_string.cc @@ -32,21 +32,22 @@ bool SplitStringFirst(const std::string& string, return true; } -std::vector SplitString(const std::string& str, char delimiter) { +std::vector SplitString(const std::string& string, + char delimiter) { std::vector result; - if (str.empty()) + if (string.empty()) return result; size_t start = 0; while (start != std::string::npos) { - size_t end = str.find_first_of(delimiter, start); + size_t end = string.find_first_of(delimiter, start); std::string part; if (end == std::string::npos) { - part = str.substr(start); + part = string.substr(start); start = std::string::npos; } else { - part = str.substr(start, end - start); + part = string.substr(start, end - start); start = end + 1; } diff --git a/util/string/split_string.h b/util/string/split_string.h index 4ea89d24..af4f953c 100644 --- a/util/string/split_string.h +++ b/util/string/split_string.h @@ -30,7 +30,7 @@ namespace crashpad { //! character. //! //! \return `true` if \a string was split successfully. `false` if \a string -//! did not contain a \delimiter character or began with a \delimiter +//! did not contain a \a delimiter character or began with a \a delimiter //! character. bool SplitStringFirst(const std::string& string, char delimiter, @@ -41,8 +41,9 @@ bool SplitStringFirst(const std::string& string, //! //! \param[in] string The string to split. //! \param[in] delimiter The delimiter to split at. +//! //! \return The individual parts of the string. -std::vector SplitString(const std::string& str, char delimiter); +std::vector SplitString(const std::string& string, char delimiter); } // namespace crashpad diff --git a/util/win/command_line.h b/util/win/command_line.h index eb3f7124..c12d6539 100644 --- a/util/win/command_line.h +++ b/util/win/command_line.h @@ -29,7 +29,7 @@ namespace crashpad { //! non-empty, a space will precede \a argument. //! //! \param[in] argument The argument to append to \a command_line. -//! \param[inout] command_line The command line being constructed. +//! \param[in,out] command_line The command line being constructed. void AppendCommandLineArgument(const std::wstring& argument, std::wstring* command_line);